\section{\cesam2k}
\index{cesam2k.out}\index{mon\_modele.don}\index{TESTS}
\index{données}\index{FORTRAN95}\index{EXPLOIT}\index{NOTICE}
\index{SCRIPTS}\index{SOURCE}\index{SUN\_STAR\_DATA}
L'exploitation de \cesam2k repose l'exécutable, {\tt cesam2k.out},
créé une fois pour toutes. C'est dans un fichier de données, d'extension générique
{\tt ".don"}, que la
physique à utiliser est indiquée conjointement aux principaux paramètres
définissant le modèle à calculer; un exemple est donné au \paragr{sec:tfonc}.
Il n'est donc pas nécessaire de créer un exécutable adapté à chaque
utilisation \footnote{Sauf, bien sûr, pour des modifications, debug, etc...}.
Il est toutefois possible de mo\-di\-fier la plupart des options, numériques ou
physiques retenues, grâce à des fichiers dits de ``réglage'' décrits au
\paragr{sec:perso}. Ils permettent d'adapter, de façon externe
\cesam2k aux moyens de calcul dont on dispose et, dans une large mesure,
aux particularités physiques des modèles à calculer. Sans pour autant avoir recours au
fichier de réglage, il est possible d'adapter certains paramètres du fichier de données
comme, par exemple, fixer à son maximum le nombre de couches à utiliser,
\cfparagr{sec:nlcesam}.

\medskip
\noi \cesam2k est programmé en {\tt FORTRAN95}, ce qui permet un
dimensionnement dynamique des tableaux.
Les compilateurs suivants ont été utilisés avec succès (liste non exhaustive)~:
\index{compilateurs}\index{LINUX}\index{UNIX}\index{WINDOWS}
\begin{itemize}
\item sous {\sc linux/unix}~: {\tt ifc}, {\tt ifort}, Lahey-Fujitsu {\tt lf95},
gfortran,
\item sous {\sc windows}~: Compact Visual Fortran
\end{itemize}

\index{numéro de version}\index{journal}\label{sec:journal}
\noi La signification du numéro de {\tt VERSION i.j.k} est la
suivante~:
\begin{description}
\item [i] augmente d'une unité à chaque modification du contenu des fichiers
binaires de reprise *.pms, *.rep, *.dat, \etc les indices suivants {\bf j} et
{\bf k} étant remis à 0.
\item [j] augmente d'une unité à chaque modification du contenu d'un des
fichier ASCII de
données *.don ou de personnalisation, l'indice suivant {\bf k} est remis à 0.
\item [k] augmente d'une unité pour chaque ensemble de modifications ayant une
conséquence sur les résultats.
\end{description}
Dans le sous-directory {\tt SOURCE}, le fichier "{\tt journal}" contient une
description succincte de la chronologie des aménagements effectués.
\bigskip

 \subsection{PGPLOT}\index{PGPLOT}\index{pgplot\_factice}\label{sec:pgplot}
\cesam2k utilise le logiciel de dessin PGPLOT pour effectuer des dessins "on line"
permettant de suivre le déroulement des calculs et aussi de faciliter le debug.
La configuration de ce packtage n'est pas prévue avec le compilateur {\tt ifc}.
Thierry Corbard, Observatoire de la Côte d'Azur, a construit
les procédures nécessaires que l'on trouvera dans le sous-directory
{\tt SCRIPTS}. Avec les compilateur plus modernes, cette difficulté a été
contournée. Sous LINUX, la commande: {\tt apt-get install pgplot5} permet
d'effectuer l'installation sans difficulté.\\

Il est possible d'éviter l'utilisation de dessin "on line". Pour ce faire, avant la
formation du module exécutable décommenter la dernière ligne du module {\tt
MOD\_CESAM}. Le fichier {\tt pgplot\_factice.f} contient des émulations des
routines de {\tt PGPLOT}. Coder {\tt NOM\_DES='no\_des'} et
{\tt NOM\_DES\_ROT='no\_des'} dans le fichier de données \cfparagr{sec:fichdon}.
Dans les Makefiles {\tt Make, Make\_expl, Make\_exe}, dans les instructions
de link, supprimer les chemins à la bibliothèque {\tt PGPLOT} ainsi que dans le
fichier {\tt .bashrc}.

\subsection{Variables quasi-statiques utilisées à partir de la version V3.5.0.}
A cause de difficultés coercitives et non résolues de convergence,
la possibilité
d'utiliser le rayon comme variable principale d'espace a été supprimée à partir
de la version V3.5.0. Les variables d'espace correspondantes,
dites {\em "eulériennes"}, $R,\ L,\ M$ ont été remplacées
par l'ensemble $R,\ L,\ M^{1/3}$ qui, tout en évitant la singularité
centrale\footnote{C'est une remarque pertinente de L.Piau qui est à l'origine de
cette amélioration significative.}, permet de décrire les phases d'évolutions
avec une luminosité locale négative. Cette situation peut survenir lorsque
les pertes par neutrinos deviennent importantes, particulièrement dans les
phases avancées; ou encore au cours du calcul avec une correction devenant
{\em anormalement} excessive.

\noi Les routines {\tt static\_m.f} et {\tt static\_r.f} ont donc
été respectivement remplacées par {\tt static\_m23.f} et {\tt static\_m13.f}.
Les modifications qui ont été nécessaires sont décrites dans le fichier
{\tt journal.f} du directory {\tt SOURCE}.
L'ensemble initial de variables $R^2,\ L^{2/3},\ M^{2/3}$, conservé dans
{\tt static\_m23.f}, permet de calculer des modèles dans les mêmes conditions que
précédemment; l'alternative est implicitement indiquée dans le fichier de données.

\subsection{Particularités de la présente version}
Dans la présente version les particularités suivantes ont été introduites~:
\begin{enumerate}
\item Remplacement du contrôle de la variation temporelle de la génération d'énergie
graviphique par ceux de la pression et de la température locales.
\item Imposition du positionnement des discontinuités dues au mélange convectif au
voisinage des points de grille (sauf dans les couches les plus externes).
\item Introduction de subscripts aux arguments du fichier de données permettant d'adapter le calcul à des contraintes particulières
comme, par exemple la génération d'un fichier {\tt .HR} condensé (extension {\tt .LR}).
\item En vue de debug, possibilité de dessins des variables principales à l'issue
de chaque pas temporel ou à chaque itération.
\end{enumerate}
% \end{document}

\section{Contenu de la distribution}\label{sec:distri}
Le package {\tt CESAM2k}\footnote{2k pour ``2000''.} contient les cinq
sous-directory~:
\begin{itemize}
 \item {\tt EXPLOIT}~: ensemble de programmes, de scripts shell, d'exemples ainsi
 que le {\tt Makefile}\footnote{Les Makefiles sont construits suivant les règles
 de GNU Make, version 4.0.} pour l'installation,
 l'exploitation et la création de données ou de paramètres relevants
  de la physique ou du numérique, par exemple le calcul de $Fe/H$, ou de la correction
  bolométrique ou encore de la calibration solaire.
 \item {\tt NOTICE}~: sources {\LaTeX} et fichiers postcript de la notice
 d'utilisation, de l'aide-mémoire et de leurs {\tt Makefile}s d'installation.
 \index{NOTICE}\index{aide mémoire}
  \item {\tt SCRIPTS}~: ensemble de procédures {\tt UNIX/LINUX} pour
 l'installation et l'exploitation avec le shell {\tt bash}.
  \item {\tt SOURCE}~: ensemble des routines, modules et programmes
 de la source et le {\tt Makefile} d'installation.
 \item {\tt SUN\_STAR\_DATA}~: ensemble de données physiques, essentiellement des
 packages, des programmes pour l'exploitation de tables d'EOS et d'opacité.
 \item {\tt TESTS}~: divers programmes de test\footnote{Certains de ces programmes
 devront être adaptés à la présente version de \cesam2k.} comme, par exemple tester
 la mise en place d'une nouvelle EOS, ou encore d'un réseau de réactions nucléaires...
\end{itemize}

\medskip

\index{mod\_atm.f}\index{mod\_kind.f}\index{kind}
\index{mod\_numerique.f}\index{mod\_donnees.f}
\index{mod\_variables.f}\index{mod\_exploit.f}\index{mod\_cesam.f}
\index{mod\_static.f}\index{mod\_numerique.f}\index{mod\_evol.f}
\index{mod\_nuc.f}\index{mod\_conv.f}\index{mod\_opa.f}\index{mod\_etat.f}

\bigskip

Les modules regroupés dans la {\tt SOURCE} ont les fonctionalités suivantes~:
\begin{itemize}
 \item Module {\tt mod\_kind}~: définit les types des variables utilisées.
 \item Module {\tt mod\_numerique}~: regroupe les routines purement numériques
 et les routines d'exploitation des données physiques.
 \item Module {\tt mod\_donnees}~: regroupe la plupart des quantités fixes au
 cours de l'évolution.
 \item Module {\tt mod\_variables}~: regroupe la plupart des quantités
 variables au cours de l'évolution.
 \item Module {\tt mod\_etat\_saha}~: regroupe les routines concernant l'équation
 d'état {\tt etat\_saha} créée par A.V.Oreshina \& V.A.Baturin.
 \item Module {\tt mod\_etat}~: regroupe les routines concernant l'équation
 d'état.
 \item Module {\tt mod\_opa}~: regroupe les routines concernant le calcul de
 l'opacité.
 \item Module {\tt mod\_conv}~: regroupe les routines concernant la convection.
 \item Module {\tt mod\_atm}~: regroupe les routines de restitution de
 l'atmosphère.
 \item Module {\tt mod\_nuc}~: regroupe les routines concernant les réactions
 thermonucléaires.
 \item Module {\tt mod\_bp\_for\_alecian}~: regroupe les routines concernant le
 calcul des accélérations radiatives, suivant le formalisme de G.Alécian.
 \item Module {\tt mod\_evol}~: regroupe les routines concernant l'évolution
 temporelle de la composition chimique.
 \item Module {\tt mod\_static}~: regroupe les routines concernées par
 la résolution de l'équilibre quasi-statique.
 \item Module {\tt mod\_cesam}~: regroupe les routines concernant la gestion du
 calcul des évolutions.
 \item Module {\tt mod\_exploit}~: regroupe des routines concernées par
 l'exploitation des résultats.
\item Module {\tt mod\_photo}~: regroupe des routines concernées par la photométrie.
\item Module {\tt mod\_sismo}~: regroupe des routines concernées par la sismologie.
\item Module {\tt mod\_spectro}~: regroupe des routines concernées par la
spectroscopie.
\end{itemize}
% \end{document}

Chaque routine {\tt PRIVATE} et/ou {\tt PUBLIC} est
introduite par un {\tt INCLUDE} dans le fichier de son module d'appartenance; le nom
de ce dernier est indiqué dans les commentaires au début de chaque routine.

L'organigramme général du code est schématisé  \paragr{fig:org}.
\begin{figure}[ht]
%\includegraphics[width=0.9\textwidth]{Orga-gene.eps}
\includegraphics[width=0.9\textwidth]{Orga-gene.png}
\caption{Schéma de l'organigramme général de \cesam2k.
Le programme {\tt cesam2k}, compilé une fois pour toutes, fait appel à la
routine {\tt cesam} qui constitue en fait, le programme principal. Dans
{\tt cesam}, après des initialisations, on sépare le traitement
des 3 possibilités~: i)  poursuite d'une évolution, ii) initialisation sur la
ZAMS homogène, iii) initialisation d'une PMS. Le calcul se poursuit par des
opérations de gestion de l'évolution, listing, création de fichiers de
sortie, dessin, etc... Est ensuite fait appel à {\tt resout}, où
 les équations de l'équilibre quasi-statique sont résolues en
 alternance avec celles de l'évolution du moment cinétique et
 de la composition chi\-mi\-que.
 Ces dernières sont résolues séparément dans {\tt evol}.
 Une fois la convergence obtenue, il y a retour vers les
 algorithmes de gestion de l'évolution de {\tt cesam} et, de là,
 poursuite de
 l'évolution ou retour à {\tt cesam} pour sortie. Les routines d'analyse
 numérique et de physique sont sollicitées à différents niveaux de calcul.
}\label{fig:org}
\end{figure}

\section{Installation}\label{sec:impl}
\index{exe2k}\index{cshrc}\index{PGPLOT}\index{UNIX}\index{LINUX}
\index{C-shell}\index{genere\_cesam2k}
\index{des\_r.f}\index{des.f}\index{mod\_cesam.f}
On décrit l'installation sous {\tt UNIX/LINUX}. Il n'est pas exclus que
des difficultés d'ordre informatique puissent survenir lors
de l'installation. Chaque système ayant ses particularités et ses
chausse-trappes, l'assistance d'un expert est parfois salutaire.

\bigskip

%\noi {\bf Installation:}
% \end{document}

\begin{itemize}
 \item Détarer la distribution~:

  \centerline{\tt tar -xzvf CESAM2k.tar.gz}
Le sous-directory {\tt CESAM2k} est créé\footnote{Dans cette notice les numéros
de version et les indications de date sont volontairement ignorés.}. Il contient 5
sous-directory qu'il convient aussi de détater~:
\begin{tt}\begin{verbatim}
 EXPLOIT.tar.gz
 NOTICE.tar.gz
 SCRIPTS.tar.gz
 SOURCE.tar.gz
 SUN_STAR_DATA.tar.gz
 TESTS.tar.gz
\end{verbatim}\end{tt}

 \item Le contenu des sous-directory {\tt SUN\_STAR\_DATA} et {\tt SCRIPT} a
la vocation d'être utilisé en dehors  de la stricte
exploitation de  \cesam2k, il convient donc de leur
donner un accès étendu et ainsi de les disposer dans le {\tt HOME}.

\noi  Dans le fichier {\tt .bashrc}:
% \item Dans le fichier {\tt .bashrc}:
 \begin{enumerate}
 \item Ajouter les chemins de la bibliothèque
  et des exécutables, par exemple~:\par
  {\tt\noi PATH=\$PATH:$\sim$/SCRIPTS:$\sim$/SUN\_STAR\_DATA
:$\sim$/CESAM2k/EXPLOIT

\noi :$\sim$/CESAM2k/SOURCE:$\sim$/CESAM2k/NOTICE:$\sim$/CESAM2k/TESTS\\
\noi export PATH} \index{bashrc}

 \item Déclarer le nom du compilateur Exemple: FORTRAN=lf95, et celui du système
  OSnom=`uname -n`\footnote{Attention cotes inversées!}; ajouter ces noms dans une
  liste d'exportables, Exemple: export FORTRAN OSnom.
  \item Si ce n'a pas été effectué par l'équipe du système, installer le logiciel de
  dessin {\tt PGPLOT}\footnote{Avec son mode d'emploi, le logiciel
  {\tt PGPLOT} est téléchargeable via {\tt anonymous ftp} à l'adresse
  {\tt http://astro.caltech.edu/$\sim$tpj/pgplot/}.}; renseigner le chemin
  de sa bibliothèque ~:
  {\tt LD\_LIBRARY\_PATH=/usr/lib/pgplot5:\$LD\_LIBRARY\_PATH}.
  On donne au \paragr{sec:pgplot}
  un supplément d'informations concernant l'ins\-tal\-la\-tion de ce logiciel.
  \par
  \item A défaut, de ce logiciel de dessin, dans le sous-directory {\tt SOURCE}~:
 \begin{itemize}
  \item Supprimer les routines {\tt boite.f}, {\tt box.f}, {\tt des\_r.f},
   {\tt des\_m.f} de la liste des
  {\tt INCLUDE} du module {\tt mod\_numerique.f}.
  \item Dans la subroutine {\tt des.f}, ne conserver que
   {\tt CASE ('no\_des')} et, éventuellement, {\tt CASE DEFAULT}.
  \item Dans la subroutine {\tt sortie.f}, supprimer {\tt CALL pgend}.
 \end{itemize}

\medskip
\PB{La liste de ces corrections n'est peut être pas complète.}

 \end{enumerate}
\end{itemize}

\section{Adaptation de \cesam2k à l'environnement}\label{sec:adsce}\index{des\_m.f}
\index{des\_r.f}
Avant de créer les exécutables, il convient d'adapter des
paramètres à l'installation. se placer dans le sous-directory {\tt SOURCE}
{\tt cd ./CESAM2k/SOURCE}),
\begin{itemize}
 \item Dans la routine {\tt des\_m.f}, vers la ligne 105, adapter le nom du "device"~:
 {\tt device='/xw'}, éventuellement coder  {\tt device='?'} de façon à
 obtenir la liste des devices disponibles.
 \item Faire de même dans la routine {\tt des\_r.f}, vers la ligne 89.
 \item Dans ces routines {\tt des\_m.f} et {\tt des\_r.f} il conviendra, par la suite,
 d'adapter la hauteur et la largeur des cadres, de façon à optimiser leur
 centrage dans la fenêtre dont on dispose, ou encore de personnaliser le
 dessin \cf\paragr{sec:device}.
\end{itemize}

\section{Création des exécutables}\label{sec:mexec}
Dans les {\tt Makefile}s d'installation {\tt Make, Make\_expl, Make\_exe}, les
paramètres de compilation sont définis
pour les compilateurs {\em lf95, ifort, gfortran}, avec et sans debug. Les
instructions de link sont personnalisées suivant différentes machines identifiées par
la variable shell exportable {\em OSnom}.
Ces Makefiles sont dérivés d'une version initiale créée par Th. Corbard.
Si un compilateur différent est utilisé il convient d'ajouter ses règles de compilation
aux règles existantes. Les Makefiles utilisent les "{\sl implicit rules}" de
GNU Make version 4.0, il est donc impératif de respecter les "{\sl pattern rules}"
pour la dénomination des variables. Par exemple, "{\tt FFLAGS}" doit être le nom de la variable définissant les arguments de
compilation\footnote{Gnu Make offre la possibilité de redéfinir ces dénominations.}.

\noi Les exécutables d'exploitation du sous-directory {\tt EXPLOIT} sont créés
avec l'option 'debug'. Ils utilisent des modules de la {\tt SOURCE}\footnote{Pour
limiter le nombre de bibliothèques, les fichiers d'extension {\tt .mod} n'ont pas été
regroupés dans une librairie de modules, mais laissés dans {\tt SOURCE}.}.
Il convient d'abord de créer ces modules en version 'debug', ensuite les exécutables
de {\tt EXPLOIT} enfin, ceux de la {\tt SOURCE}, avec
optimiseur\footnote{Les instructions d'installations suivantes sont rappelées dans le
{\tt README\_installation} de la {\tt SOURCE}.}. \label{sec:Makefile}\index{Make}

\begin{enumerate}
\item Se placer dans le sous-directory {\tt SOURCE}  ({\tt cd ./CESAM2k/SOURCE})
\begin{quote}
  Sous {\tt SVN} saisir: {\tt svn update}, les mises à jour se mettent en place;
 \end{quote}
puis saisir: {\tt make -Bf Make DBG=2k-dbg}.
Le Makefile s'exécute, il y a création de la bibliothèque {\tt libcesam2k-dbg.a},
de l'exécutable {\tt cesam2k-dbg.out} et des modules (extension {\tt .mod}) avec
"debug".
\item Se placer dans le sous-directory {\tt EXPLOIT}: ({\tt cd ../EXPLOIT}) \begin{quote}
  Sous {\tt SVN} saisir: {\tt svn update}, les mises à jours se mettent en place;
 \end{quote}
 puis saisir: {\tt make -Bf Make\_expl DB=2k}. Le Makefile s'exécute,
 il y a création des exécutables d'exploitation.

\item Revenir dans le sous-directory {\tt SOURCE} ({\tt cd ../SOURCE}), saisir:
{\tt make -Bf Make DBG=2k}.
Le Makefile s'exécute, il y a création de la bibliothèque {\tt libcesam2k.a},
de l'exécutable {\tt cesam2k.out}. Les modules avec optimisation sont conservés
dans l'environnement.
\end{enumerate}











