\section{Conventions de programmation}\index{modules}\label{sec:mod}
{\cesam2k} est structuré en {\tt MODULE}s
notion spécifique \`a {\tt FORTRAN95}. L'intérêt principal structure
réside dans le contrôle, {\em par le compilateur}, de la concordance
des types ({\tt real, integer}
etc..), des dimensions des tableaux, du nombre arguments
entre l'instruction
d'appel et le sous-programme appelé. De façon simplifiée on peut dire
que les modules constituent une extension des {\tt COMMON}s au sens où ils
incluent non seulement
des variables, mais aussi des sous-programmes des types, \etc
De plus, un module
regroupe un ensemble de variables\footnote{Variable est à prendre ici
dans son sens le plus
général de variable réelle, entière, tableau, chaîne de caractères
\etc} et/ou de sous-programmes, qui peuvent être:
\begin{description} 
\item [{\tt PUBLIC}] c'est à dire accessibles\footnote{Eventuellement de
fa\c con restrictive en utilisant l'intruction {\tt ONLY}, \cf \paragr{sec:res}.} du programme
principal et des sous-programmes {\em appartenant ou n'appartenant pas}
au module,
\item [``private''] c'est à dire accessibles {\em uniquement} par les
sous-programmes {\em appartenant} au module.
\end{description}
Cette derni\`ere possibilité permet
d'utiliser, dans des {\em modules différents},
des routines de même nom ayant, \'eventuellement, des fonctions et/ou des
listes d'appel
différentes. Les variables de module sont, par ailleurs, des variables
acc\'essibles directement par tous les sous-programmes
{\tt(PUBLIC} ou {\tt PRIVATE)} du module,
elles ne transitent donc
pas nécessairement par les listes d'arguments. Cette dernière disposition,
très pratique par ailleurs, rend les programmes un peu difficile à lire car
il faut remonter à la définition des variables dans la partie déclarative
du module pour savoir le type de la variable ({\tt REAL, INTEGER}, \etc\ ).
Pour faciliter ces identifications on détaille dans l'appendice, \cf
\paragr{sec:lm},
le type et l'utilisation de chaque variable des différents
modules de {\cesam2k}. 

\noindent Par convention, le fichier contenant un module a pour
nom celui du module affecté du préfixe {\sf mod\_}, par exemple:

\centerline{\sf mod\_numerique.}

\noindent Il est pratique de regrouper dans un même {\tt MODULE}
les sous-programmes relatifs \`a une même entité physique,
par exemple les \EOS, les \opa, ou encore les routines de mathématique.
Dans les différents modules et le programme {\sf cesam2k} les
sous-programmes sont introduits par des {\tt INCLUDE} afin d'en faciliter
la gestion. {\sc cesam4} ayant servi de base à {\cesam2k}, on a conservé
la structure ``fixed form''. Les routines ont donc les extensions
{\sf .f} et non pas 
{\sf .f90} ou encore {\sf .f95}. Les cartes ``suite'' ont conservé
leur numérotation (1, 2,...), pratique qui évite de permuter des lignes
en particulier dans les initialisations de tableaux.
\medskip

\PB{Les routines des versions précédentes de {\sc cesam} ne peuvent être
utilisées par {\cesam2k} même si elles ont le même nom et la même
fonction.} 

\noindent Dans un module les ``{\tt PARAMETER}'' 
sont des quantités (réels, entiers, cha\^\i nes de caract\`eres,
tableaux...)
qui peuvent être, soit {\tt PUBLIC}, soit {\tt PRIVQTE}. Elles sont
initialisées explicitement, par exemple {\tt pi=3.1416d0, He='He4', n=2000}.
Elles se différencient des variables au sens o\`u le compilateur refuse
de les modifier ultérieurement, ce qui constitue une sécurité.

\noindent {\em Acc\`es restrictif~: } Un sous-programme d'un module
de nom {\sf mod\_a} a accès à une\label{sec:res}
variable public {\tt x} d'un module de nom {\sf mod\_b} à travers
l'instruction:\index{acc\`es restrictif}\index{acc\`es non restrictif}

\centerline {\tt USE mod\_b, ONLY : x}

\noindent {\em Acc\`es non restrictif~: }L'instruction précédente,
réduite à {\tt USE mod\_b},
donne accès à toutes les variables public du module {\sf mod\_b}; pour
des raisons sécuritaires, on a systématiquement utilisé
la restriction {\tt ONLY}. Cettte règle s'applique non seulement aux
variables mais aussi aux routines.

\noindent {\sc fortran95} permet de faire la distinctions entre variable
d'entrée {\tt INTENT (in)} de sortie {\tt INTENT(out)} ou
d'entrée/sortie {\tt INTENT(inout)} d'un sous-programme. Le compilateur
détecte si, \`a tord, variable déclarée {\tt INTENT(in)} est modifiée ou
 si, par oubli, une variable
{\tt INTENT(out)} ne re\c coit pas d'affectation. Lorsqu'une routine
{\sf ssp\_a}
et une routine {\sf ssp\_b} de deux modules différents, ont des 
variables communes dans leurs listes d'arguments,
la routine {\sf ssp\_a} appelant la routine 
{\sf ssp\_b}, le compilateur doit pouvoir
vérifier la cohérence des déclarations {\tt INTENT(in)}, {\tt INTENT(out)}
et {\tt INTENT(inout)}; en particulier vérifier qu'une variable
déclarée {\tt INTENT(in)} dans {\sf ssp\_a} ne soit pas modifiée dans
{\sf ssp\_b}. Cette vérification se fait à l'aide des instructions se
trouvant dans les fichiers d'extension {\sf .mod} créés
lors de la compilation des modules. Lors de la compilation du module
auquel appartient la routine {\sf ssp\_b}, il faut donc que le module
auquel appartient
la routine {\sf ssp\_a} ait déjà été compilé. D'o\`u la raison de
l'impératif de l'ordre de compilation des modules évoqué
au \paragr{sec:compil}.
\medskip

\PB{Au cas où un module doit être modifié, par exemple pour y ajouter
 une variable ou une fonction, il est nécessaire de recompiler tous les
 modules qui y font appel, et d'en 
 replacer les object-modules obtenus dans la bibliothèque.}
 
\medskip

\noi Au cas où une variable {\tt x} commune est déclaréee {\tt INTENT(in)}
dans la
routine {\sf ssp\_a} et {\tt INTENT(out)} ou {\tt INTENT(inout)}
dans la routine {\sf ssp\_b} le compilateur détecte l'incompatibilité,
 il convient de la réaffecter la variable {\tt xx=x}. 

\noi Dans un module les variables {\tt PUBLIC} ont, à peu près,
le même rôle que les variables des {\tt COMMON}.
Elles sont donc modifiables dans tout sous-programme utilisant le
module qui les contient. {\sc fortran95} prévoit un dispositif pour
éviter de modifier {\em involontairement} les variables {\tt PUBLIC}
d'un module. Il consiste, pour ce sous-programme, à donner à ces variable
un nom local en faisant pointer des variables locales 
sur les variables concernées du module. Par exemple
{\tt z0} (métallicité initiale), est une
variable {\tt PUBLIC} du module\index{variable locale}\index{L}
{\sf mod\_donnees} 
en faisant pointer la variable locale {\tt Lz0} sur la variable de module
{\tt z0}:

\centerline{\tt USE mod\_donnees, ONLY : Lz0 => z0,}

\noi on évitera de modifier par erreur la variable {\tt z0}.

\noi Cette disposition sécuritaire est appliquée
principalement lorsque des routines de source externes sont utilisées,
par exemple pour l'équation d'état {\sf etat\_eff}.

%Dans {\cesam2k}, par convention, une variable locale ainsi
%formée est affectée du préfixe ``{\tt }L'' (Local). 
%Les variables déclarées {\tt intent(in)}, i.e. comme variable d'entrée
%d'un sous-programme {\sf sp1}, ne peuvent pas figurer comme argument
%d'un sous-programme\footnote{Sauf si {\sf sp1} et {\sf sp2}
%appartiennent au même module, auquel cas le compilateur reconnait
%l'arborescence.} {\sf sp2} appelé par {\sf sp1}. 
%En {\em général} le compilateur ne peut pas
%détecter si ces variables risquent d'être modifiées dans {\sf sp2}.
%Des réaffectations locales sont alors  nécessaires pour
%assurer l'intégrité
%des variables déclarées {\tt intent(in)}. 
\noindent Par convention les noms des variables réaffectées se
distinguent, par :
\begin{description}
\item  [l'affectation] du préfixe {\tt L},
Exemple: {\tt Lxchim} est le nom local du tableau {\tt xchim},
\item [la répétition] de la premi\`ere lettre du nom de la variable,
Exemple: {\tt pptq} est le nom local de la variable {\tt ptq}.
\end{description}

\section{Les modules de {\cesam2k}}\index{routine générique}
\index{module}
Par convention les noms des modules de {\cesam2k} se différencient
de ceux des sous
programmes\footnote{Dans la notice les extensions {\sf .f, .f90, .f95}
 sont omises.} par le préfixe ``{\sf mod\_}''.
Si une modification importante d'un module est effectuée, par exemple
ajout d'un
argument dans la liste d'appel d'une routine, le plus simple
de recompiler toute la source de {\cesam2k} en reconstituant la
bibliothèque {\sf libcesam2k.a} et de former le module ex\'ecutable {\tt
cesam2k.out} \cf\paragr{sec:compil}. Toutefois, ainsi qu'il est indiqu\'e
ci-apr\`es, il suffit parfois de ne recompiler qu'un nombre restreint
de {\tt MODULES}. En cas de modification mineure, comme l'ajout d'une
d\'ecimale \`a $\pi$, il suffit de recompiler le module et de le replacer
dans la biblioth\`eque.
 
\subsection{Module mod\_atm}\index{mod\_atm}\index{mod\_cesam} 
\index{atmosphère}
Ce module regroupe les routines de restitution de l'atmosphère.
On trouvera \paragr{sec:matm} la liste des variables et fonctions
du module {\sf mod\_atm}. Si ce module est modifié,
il convient de recompiler le module {\sf mod\_cesam}.

\subsection{Module mod\_kind}\index{mod\_kind}\index{kind}
\index{Module mod\_kind}
Ce module définit les types {\tt dp}: double précision
et {\tt sp}: simple précision. Toutes les quantités sont {\tt PUBLIC}.
Si une modification de ce module est effectuée, il est nécessaire
de recompiler toute la source de {\cesam2k} et de reconstituer la
bibliothèque {\sf libcesam2k.a} \cf\paragr{sec:compil}.
On trouvera \paragr{sec:amdk} la liste des variables et fonctions
du module {\sf mod\_kind}.
 
\subsection{Module mod\_numerique}\index{mod\_numerique}
Le module {\sf mod\_numerique} regroupe les outils numériques et
informatiques utilisés par {\cesam2k}.
Si une modification de ce module est effectuée, il est nécessaire
de recompiler toute la source de {\cesam2k} et de reconstituer la
bibliothèque {\sf libcesam2k.a} \cf\paragr{sec:compil}.
On trouvera \paragr{sec:amnum} la liste des variables et fonctions
du module {\sf mod\_numerique}.

\subsection{Module mod\_donnees}\index{mod\_donnees}
\index{Module mod\_donnees}
Ce module regroupe l'ensemble des données à la fois des constantes 
physiques ou mathématiques fondamentales par exemple
la masse de l'électron {\tt me},
des constantes propres à {\cesam2k}, par exemple
le pas temporel maximum {\tt dtmax}, enfin des données nécessaires
au calcul du modèle,
par exemple la masse initiale de l'étoile {\tt mtot}.
Quelques constantes physiques,
plus spécifiques, sont définies localement dans les routines qui les
utilisent. Tous les paramètres et les variables de ce module sont
{\tt PUBLIC}; le module regroupe aussi les routines qui permettant de lire
ou d'initialiser ces quantités.
Si une modification de ce module est effectuée,
le plus simple consiste à reconstituer la bibliotèque
{\sf libcesam2k.a} \cf\paragr{sec:compil}.
On trouvera \paragr{sec:amd} la liste des variables et fonctions
du module {\sf mod\_donnees}.

\subsection{Module mod\_variables}\index{mod\_variables}
\label{sec:var}
Ce module regroupe essentiellement les variables générales de {\cesam2k}
comme par exemple le vecteur des variables quasi-statiques, ou encore le
vecteur de la composition chimique généralisée.
Si une modification de ce module est effectuée,
le plus simple consiste à reconstituer la bibliotèque
{\sf libcesam2k.a} \cf\paragr{sec:compil}.
On trouvera \paragr{sec:amvar} la liste des variables et fonctions
du module {\sf mod\_variables}.

\subsection{Module mod\_etat}\index{mod\_etat}\label{sec:metat}
Ce module regroupe les routines de {\cesam2k}
concernant l'équation d'état et les routines propres d'exploitation.
Si une modification de ce module est effectuée,
il est nécessaire de recompiler les modules
{\sf mod\_etat}, {\sf mod\_opa}, {\sf mod\_conv},
{\sf mod\_atm}, {\sf mod\_nuc}, {\sf mod\_evol}, {\sf mod\_static},
{\sf mod\_cesam}, et {\sf mod\_exploit}. Il faut ensuite
réintroduire les object-module correspondants dans la
bibliothèque {\sf libcesam2k.a} -- en utilisant par exemple la procédure
{\sf lib\_del\_repl} du \paragr{sec:libd}; il faudra aussi recréer le
module exécutable -- \cf\paragr{sec:compil}
On trouvera \paragr{sec:amet} la liste des variables et fonctions
du module {\sf mod\_etat}.

\subsection{Module mod\_opa}\index{mod\_opa}\label{sec:mopa}
Ce module regroupe les routines de {\cesam2k}
concernant l'opacité, et les routines propres d'exploitation.
Si une modification de ce module est effectuée,
il est nécessaire de recompiler les modules
{\sf mod\_opa}, {\sf mod\_conv}, {\sf mod\_atm}, {\sf mod\_nuc}, 
{\sf mod\_evol}, {\sf mod\_static}, {\sf mod\_cesam} et {\sf mod\_exploit}.
Il faut ensuite
réintroduire les object-module correspondants dans la
bibliothèque {\sf libcesam2k.a} -- 
en utilisant par exemple la procédure
{\sf lib\_del\_repl} du \paragr{sec:libd}; il faudra aussi recréer le
module exécutable -- \cf\paragr{sec:compil}.
On trouvera \paragr{sec:amop} la liste des variables et fonctions
du module {\sf mod\_opa}.

\subsection{Module mod\_conv}\label{sec:mconv}
\index{mod\_conv}\index{convection}
Ce module regroupe les routines de {\cesam2k}
concernant la convection.
Si une modification de ce module est effectuée,
il est nécessaire de recompiler les modules
{\sf mod\_conv}, {\sf mod\_atm}, {\sf mod\_nuc}, {\sf mod\_evol}, 
{\sf mod\_static}, {\sf mod\_cesam} et {\sf mod\_exploit}.
Il faut ensuite
réintroduire les object-module correspondants dans la
bibliothèque {\sf libcesam2k.a} -- 
en utilisant par exemple la procédure
{\sf lib\_del\_repl} du \paragr{sec:libd}; il faudra aussi recréer le
module exécutable -- \cf\paragr{sec:compil}.
On trouvera \paragr{sec:amco} la liste des variables et fonctions
du module {\sf mod\_conv}.

\subsection{Module mod\_atm}\label{sec:matm}
\index{atmosphère}\index{}\index{}
Ce module regroupe les routines de {\cesam2k}
concernant la restitution de l'atmosphère.
Si une modification de ce module est effectuée,
il est nécessaire de recompiler les modules
{\sf mod\_atm}, {\sf mod\_nuc}, {\sf mod\_evol}, {\sf mod\_static}, 
{\sf mod\_cesam} et {\sf mod\_exploit}. Il faut ensuite
réintroduire les object-module correspondants dans la
bibliothèque {\sf libcesam2k.a} -- 
en utilisant par exemple la procédure
{\sf lib\_del\_repl} du \paragr{sec:libd}; il faudra aussi recréer le
module exécutable -- \cf\paragr{sec:compil}.
On trouvera \paragr{sec:amatm} la liste des variables et fonctions
du module {\sf mod\_atm}.

\subsection{Module mod\_nuc}\label{sec:mnuc}\index{mod\_nuc}
Ce module regroupe les routines de {\cesam2k}
concernant les réactions thermonucléaires,
les routines propres d'exploitation et
les paramètres propres, valeurs max. des dimensions de tableaux.
Le calcul des taux des réactions est effectué par la routine
générique {\sf nuc};
les réseaux de réactions sont différenciés par leur nom: {\tt nom\_nuc}
lu par {\sf lit\_nl} fonction publique du module {\sf mod\_donnees}.
Si une modification de ce module est effectuée,
il est nécessaire de recompiler les modules
{\sf mod\_nuc}, {\sf mod\_evol}, {\sf mod\_static}, {\sf mod\_cesam} et 
{\sf mod\_exploit}. Il faut ensuite
réintroduire les object-module correspondants dans la
bibliothèque {\sf libcesam2k.a} -- 
en utilisant par exemple la procédure
{\sf lib\_del\_repl} du \paragr{sec:libd}; il faudra aussi recréer le
module exécutable -- \cf\paragr{sec:compil}.
On trouvera \paragr{sec:amnuc} la liste des variables et fonctions
du module {\sf mod\_nuc}.

\subsection{Module mod\_evol}\label{sec:mevol}\index{mod\_evol}
Ce module regroupe les routines de {\cesam2k}
concernant l'évolution de la composition chimique avec et sans diffusion.
Si une modification de ce module est effectuée,
il est nécessaire de recompiler les modules
{\sf mod\_evol}, {\sf mod\_static}, {\sf mod\_cesam} et 
{\sf mod\_exploit}. Il faut ensuite
réintroduire les object-module correspondants dans la
bibliothèque {\sf libcesam2k.a} -- 
en utilisant par exemple la procédure
{\sf lib\_del\_repl} du \paragr{sec:libd}; il faudra aussi recréer le
module exécutable -- \cf\paragr{sec:compil}.
On trouvera \paragr{sec:amevol} la liste des variables et fonctions
du module {\sf mod\_evol}.

\subsection{Module mod\_static}\label{sec:qstat}
\index{mod\_static}
Ce module regroupe les variables et les fonctions concernant
l'évolution temporelle du mod\`ele quasi-statique.
Si une modification de ce module est effectuée,
il est nécessaire de recompiler les modules
{\sf mod\_static}, {\sf mod\_cesam} et {\sf mod\_exploit}. Il faut ensuite
réintroduire les object-module correspondants dans la
bibliothèque {\sf libcesam2k.a} -- 
en utilisant par exemple la procédure
{\sf lib\_del\_repl} du \paragr{sec:libd}; il faudra aussi recréer le
module exécutable -- \cf\paragr{sec:compil}.
On trouvera \paragr{sec:amqst} la liste des variables et fonctions
du module {\sf mod\_static}.

\subsection{Module mod\_cesam}\index{cesam}\index{mod\_cesam}
\label{sec:mcesam}
Ce module module contient la routine {\sf cesam} et diverses routines
de sortie. {\sf cesam} est en fait
le programme principal. Cette disposition permet de mettre {\sf cesam}
dans la bibliothèque et évite de recompiler le programme principal
lors de tests et mises au point.
Si une modification de ce module est effectuée,
il est nécessaire de recompiler les modules
{\sf mod\_cesam} et {\sf mod\_exploit}. Il faut ensuite
réintroduire les object-module correspondants dans la
bibliothèque {\sf libcesam2k.a} -- 
en utilisant par exemple la procédure
{\sf lib\_del\_repl} du \paragr{sec:libd}; il faudra aussi recréer le
module exécutable -- \cf\paragr{sec:compil}.
On trouvera \paragr{sec:amcs} la liste des variables et fonctions
du module {\sf mod\_cesam}.

\subsection{Module mod\_exploit}\index{mod\_exploit}
\label{sec:mexploit}
Ce module contient des programmes et des routines facilitant l'exploitation
de {\cesam2k}.
Si une modification de ce module est effectuée,
il est nécessaire de recompiler le module
{\sf mod\_exploit} (par exemple en utilisant la procédure {\sf compilef95})
puis de réintroduire l'object-module correspondant dans la
bibliothèque {\sf libcesam2k.a} -- en utilisant par exemple la procédure
{\sf lib\_del\_repl} du \paragr{sec:libd}; il faudra aussi recréer le
module exécutable -- \cf\paragr{sec:compil}.
On trouvera \paragr{sec:amexp} la liste des variables et fonctions
du module {\sf mod\_exploit}.
