Dust Cycle in Mars PCM6

2023-11-02T15:42:16Z

Abierjon:

Beginning a page on the dust cycle in Mars PCM6. '''This is still work in progress for now !'''

À 14h, si le scénario du jour d'après donne une opacité de 5 alors que le jour actuel, le GCM a une opacité disons de 1 dans la colonne :

1. on calcule le dtau=5-1=4, puis ce que ça ferait comme quantité de poussière à 3µm à ajouter dans l'atmosphère

2. on injecte cette quantité de poussière nuancée par un coef Cinj pour prendre en compte que le saut de tau_scenario peut venir non pas d'injection locale mais de transports depuis les autres mailles. En pratique, Cinj=0.25, ce qui donne une injection de ~5e-8kg/m²/s

3. toute cette poussière est injectée de manière uniforme entre le 14h actuel et 14h du jour d'après sous forme de stormdust dans la 1ère couche par vdifc, qui la mélange déjà un peu sur plusieurs couches, avant qu'elle ne passe par les thermiques/l'ajustement convectif, la sédimentation (mais on empêche la stormdust de tomber au sol, elle reste dans la 1ère couche à la place), et 5 pas de temps de dynamique

4. une fois retourné au pas de temps physique suivant, on calcule la fraction sous-maille à partir du maximum de mass mixing ratio de stormdust dans toute la colonne (à part la 1ère couche (?) ), par rapport à un mixing ratio de référence mmr_ref=5e-4kg/kg que l'on considère représentatif d'une opacité de 10 (telle que mesurée dans une local dust storm par OMEGA)

5. enfin, on rentre dans la routine rocketduststorm, où on regarde si qqpart dans la colonne, le mmr de stormdust (non-concentré dans la fraction sous-maille) est supérieur à 10^(-4) fois celui du background dust. Si c'est le cas, on active le schéma dans la colonne, et on calcule l'écart de chauffage entre la fraction sous-maille et la maille totale, le transport vertical qui en résulte dans la fraction sous-maille, et le détraînement. Si ce n'est pas le cas (pas assez de stormdust nulle part dans la colonne) on détraîne tout

[[Category:Mars-Model]]

Dust Cycle in Mars PCM6

2023-11-02T15:40:37Z

Abierjon: Created page with "Beginning a page on the dust cycle in Mars PCM6. '''This is still work in progress for now !''' À 14h, si le scénario du jour d'après donne une opacité de 5 alors que le..."

Overview of the Mars PCM

2023-11-02T15:36:41Z

Abierjon:

== The Mars PCM ==
In a nutshell, the Mars Planetary Climate Model is a General Circulation Model (GCM) of the Martian atmosphere. It is in fact a suite of models which may be run in various configurations: with the historical lon-lat (LMDZ) dynamics, or the modern DYNAMICO (icosahedral grid) dynamics, or as a regional model using WRF (a limited area dynamical core), or even as a 1D (single column) model.

== Reference Versions of the Mars PCM ==
In practice the model is most often run using the legacy LMDZ lon-lat global dynamics for 3D simulations. However within this setup there are various configurations or versions of the model that can be used.

=== GCM version 5 ===
This is the version of the model that was used to generate Mars Climate Database version 5.3. In practice, the main features of these simulations are:
* a horizontal grid (longitudexlatitude) resolution of 64x48, with 49 vertical layers (when including the thermosphere)
* a dust cycle where column dust opacity is imposed via input dust scenarios.

=== GCM version 6 ===
This is the latest version of the model that was used to generate Mars Climate Database version 6.1. In practice, the main features of these simulations are:
* a horizontal grid (longitudexlatitude) resolution of 64x48, with 73 vertical layers (when including the thermosphere)
* a dust cycle where column dust opacity is not rescaled to but driven by dust scenarios, via injection of rocket dust storms and the use of mountain slope dust re-injection parametrization. A dedicated page on the dust cycle in version 6 can be found [[Dust_Cycle_in_Mars_PCM6|here]].

== Getting started ==
Most likely you will want to install and run the model, then you should start [[Quick_Install_and_Run_Mars_PCM|with this page]]. You can also check the User Manual provided with the source code (in the LMDZ.MARS directory), a copy is available online https://trac.lmd.jussieu.fr/Planeto/browser/trunk/LMDZ.MARS/user_manual.pdf, and also the [[Help_Mars_PCM|"Getting Help"]] page on this wiki.

[[Category:Mars-Model]]

Useful Examples

2023-11-02T15:27:16Z

Abierjon:

This page is to help and give some examples and guidelines to the editors of this wiki.

== Editing convention ==
*Name of the files: ''italic''

== To Edit Sidebar (as admin only!!!) ==
Go to [[MediaWiki:Sidebar]]

== To write some LateX ==
See e.g. [https://lmdz-forge.lmd.jussieu.fr/mediawiki/LMDZPedia/index.php/ExempleMaths LMDZPedia]
And check out this page in "edit" mode!

$$\newcommand{\Re}{\mathrm{Re}\,}
\newcommand{\pFq}[5]{{}_{#1}\mathrm{F}_{#2} \left( \genfrac{}{}{0pt}{}{#3}{#4} \bigg| {#5} \right)}$$

We consider, for various values of $$s$$, the $$n$$-dimensional integral
\begin{align}
\label{def:Wns}
W_n (s)
&:=
\int_{[0, 1]^n}
\left| \sum_{k = 1}^n \mathrm{e}^{2 \pi \mathrm{i} \, x_k} \right|^s \mathrm{d}\boldsymbol{x}
\end{align}
which occurs in the theory of uniform random walk integrals in the plane,
where at each step a unit-step is taken in a random direction. As such,
the integral \eqref{def:Wns} expresses the $$s$$-th moment of the distance
to the origin after $$n$$ steps.

By experimentation and some sketchy arguments we quickly conjectured and
strongly believed that, for $$k$$ a nonnegative integer
\begin{align}
\label{eq:W3k}
W_3(k) &= \Re \, \pFq32{\frac12, -\frac k2, -\frac k2}{1, 1}{4}.
\end{align}

Appropriately defined, \eqref{eq:W3k} also holds for negative odd integers.
The reason for \eqref{eq:W3k} was long a mystery, but it will be explained
at the end of the paper.

== Miscellaneous ==
* HTML like syntax works! e.g. comments with

<pre>

which you see because between "pre" tags
</pre>

* Some special features:
Link to the internal page with all special features: [[Special:Version]]

* Examples of Syntax Highlighting:
Some Fortran Code:
<syntaxhighlight lang="fortran" line>
program truc
implicit none
integer :: i
do i=1,10
write(*,*) "i=",i," for each hello planeto world"
end do
end program
</syntaxhighlight>

Some Python Code:
<syntaxhighlight lang="python" line>
import numpy
import matplotlib as plt
for i in range(0,5,1):
print('hello planeto world")
plt.show()
</syntaxhighlight>

Some bash code:
<syntaxhighlight lang="bash" line>
echo 'hello planeto world'
</syntaxhighlight>

You can also embed some <code>code box</code> within the text.

* This page sums up a lot of formatting commands you can use as editor : https://m.mediawiki.org/wiki/Help:Formatting

== How to create a new page ==
Option 1: Make a link to that page from a currently existing page, and when you click on that link (will be displayed in red as the system notices that it is a broken link) and the system will ask you if you want to create the page. A reminder on how to add (code-wise) a link to another MediaWiki page (try to follow CamelCase formatting, see option 2 below):
<pre>
[[Link_To_Some_Page|some descriptive text]]
</pre>
which will be rendered as:
[[Link_To_Some_Page|some descriptive text]]

Option 2: Look for it via the search bar! Advice: you should use CamelCase formating (with a "_" between words) as this page name will end up also being the title of the page (with the "_" replaced by spaces), e.g. The_Best_Page_Ever

== Link to the Generic PCM user manual ==

link to the one on the trac which is what is on svn and thus will always be up to date:
https://trac.lmd.jussieu.fr/Planeto/browser/trunk/LMDZ.GENERIC/ManualGCM_GENERIC.pdf

[[Category:FAQ]]

Using Adastra

2023-07-19T10:20:49Z

Abierjon:

This page provides a summary of examples and tools designed to help you get used with the Adastra environment.

== Getting access to the cluster ==
For people on the "Atmosphères Planétaires" GENCI project who need to open an account on Adastra, here is the procedure:

# Go to https://www.edari.fr/utilisateur and log in via Janus or create an account if you don't have a Janus login. If this doesn't work, you can create a new eDARI account. (Make sure your profile is fully up to date including nationality)
# Beware! If you are on 2 lab (LMD and LATMOS for example), you must register with your email address corresponding to your Janus account.
# Click on "se rattacher à un dossier ayant obtenu des resources" or "Attach yourself to an application file that has obtained resources"
# "Atmosphères Planétaires" project number to provide: A0140110391
# Ehouarn then receives an email to allow you to join the project. Once he has validated it, you receive a confirmation mail.
# Once approved, you have to request for an account, click on "CINES: créer une demande d'ouverture de compte"
# fill in the forms: name, contract end date, CINES, your lab information (LMD is the default)
# Access IP address 134.157.47.46 , FQDN (Fully Qualified Domain Name): ssh-out.lmd.jussieu.fr
# Add a second address : 134.157.176.129 , FQDN: ciclad.ipsl.upmc.fr
# click on option to have access to CCFR (only important if you have access to other GENCI machines)
# Security officer is Julien Lenseigne for LMD (his informations are all pre-filled, except phone: +33169335172)
# YOU MUST THEN VALIDATE THE REQUEST: click on the "Valider la saisie des informations"
# You then receive an automatic mail, but it's only to tell you to go to the next step: You must now download the pre-filled form from e-dari: find "télécharger la demande" and download the pdf. Sign it, and upload it on e-dari "déposer la demande de création de compte".
# Wait for your application to be preprocessed by the system...

== A couple of pointers ==

* Connecting to Adastra: For those who had an account on Occigen, we have retained group and login credentials from then; To connect to Adastra you need first go through the LMD gateway (hakim) or the IPSL (Ciclad/Spirit) gateway and then
<syntaxhighlight lang="bash">
ssh your_cines_login@adastra.cines.fr
</syntaxhighlight>
And then you will probably want to switch project using the myproject command, e.g. to switch to "lmd1167" (the old "Atmosphères Planétaires" GENCI project)
<syntaxhighlight lang="bash">
myproject -a lmd1167
</syntaxhighlight>
and to switch to "cin0391" (the 2023-2024 "Atmosphères Planétaires" GENCI project)
<syntaxhighlight lang="bash">
myproject -a cin0391
</syntaxhighlight>
WARNING: when you switch projects, you also switch HOME directory etc.

To get all the info about dedicated environment variables (e.g. paths to SCRATCH, STORE, etc.) you can use
<syntaxhighlight lang="bash">
myproject -c
</syntaxhighlight>

* To get all the information about project accounting (number of hours available and used by each member of the project) you need to connect to https://reser.cines.fr/ using your Adastra login and password

* Changing the password of your CINES account
When your password is close to expiring, CINES asks you to change it on this website : https://rosetta.cines.fr

Please note that you can access this website only if you are on a machine that you declared as a gateway for Adastra. At LMD, we have generally declared hakim.lmd.jussieu.fr (aka ssh-out) and ciclad.ipsl.jussieu.fr as gateway machines. Hakim doesn't have any browser installed, but you can launch <code>firefox</code> on Ciclad and connect to the rosetta website.
If that doesn't work, check out the page on [[How to launch your local browser through a gateway machine]] or contact mail svp@cines.fr

* Link to the Adastra technical documentation: https://dci.dci-gitlab.cines.fr/webextranet/

== Submitting jobs ==
It's done using SLURM; you need to write up a job script and submit it using '''sbatch'''
<syntaxhighlight lang="bash">
sbatch myjob
</syntaxhighlight>
You must specify in the header of the job which project ressources you are using ("cin0391" in our case):
<syntaxhighlight lang="bash">
#SBATCH --account=cin0391
</syntaxhighlight>

=== Example of an MPI job to launch a simulation ===
<syntaxhighlight lang="bash">
#!/bin/bash
#SBATCH --job-name=job_mpi
#SBATCH --account=cin0391
### GENOA nodes accommodate 96 cores
#SBATCH --constraint=GENOA
### Number of Nodes to use
#SBATCH --nodes=1
### Number of MPI tasks per node
#SBATCH --ntasks-per-node=48
### Number of OpenMP threads per MPI task
#SBATCH --cpus-per-task=1
#SBATCH --threads-per-core=1
###SBATCH --exclusive
#SBATCH --output=job_mpi_%A.out
#SBATCH --time=00:45:00

#source env modules:
source ../trunk/LMDZ.COMMON/arch.env
ulimit -s unlimited

srun --cpu-bind=threads --label gcm_96x96x78_phyvenus_para.e > gcm.out 2>&1

</syntaxhighlight>

=== Example of a mixed MPI/OpenMP job to launch a simulation ===
<syntaxhighlight lang="bash">
#!/bin/bash
#SBATCH --job-name=job_mpi_omp
#SBATCH --account=cin0391
### GENOA nodes accommodate 96 cores
#SBATCH --constraint=GENOA
### Number of Nodes to use
#SBATCH --nodes=1
### Number of MPI tasks per node
#SBATCH --ntasks-per-node=24
### Number of OpenMP threads per MPI task
#SBATCH --cpus-per-task=4
#SBATCH --threads-per-core=1
###SBATCH --exclusive
#SBATCH --output=job_mpi_omp_%A.out
#SBATCH --time=00:30:00

#source env modules:
source ../trunk/LMDZ.COMMON/arch.env
ulimit -s unlimited

### OMP_NUM_THREADS value must match "#SBATCH --cpus-per-task"
export OMP_NUM_THREADS=4
export OMP_STACKSIZE=400M

srun --cpu-bind=threads --label gcm_64x48x54_phymars_para.e > gcm.out 2>&1

</syntaxhighlight>

== Are you being disconnected when inactive? ==
If you are regularly being disconnected when a bit inactive on the supercomputer, adding these few lines in a ''config'' file in the .ssh/ repository of your logging machine (ex: ssh-out/ciclad) may help :
<syntaxhighlight lang="bash">
Host *
...
KeepAlive yes
TCPKeepAlive yes
ServerAliveInterval 15
</syntaxhighlight>

[[Category:FAQ]]

Using Irene Rome

2023-07-19T10:19:31Z

Abierjon:

This page provides a summary of examples and tools designed to help you get used with the Irene Rome environment. (as of July 2022)

== How to access the cluster ==

For people on the "Atmosphères Planétaires" GENCI project who need to open an account on Irene-Rome, here is the procedure:

* Log on to https://www-dcc.extra.cea.fr/CCFR/ and provide various information about yourself

A few tips:

- chose TGCC

- give your PROFESSIONAL phone number (and not your personal cell phone number)

- name of the project: Atmosphères Planétaires Numéro du Dossier: A0120110391

- Responsable scientifique du projet: M. Ehouarn MILLOUR , ehouarn.millour@lmd.ipsl.fr, 0144275286, Nationalité: Fr

- Responsable sécurité: M. Franck Guyon, franck.guyon@lmd.ipsl.fr, 0144275277, Nationalité: Fr. Note that this is assuming you have an account on LMD computers and/or the MESOIPSL cluster. Otherwise you must provide the information for the relevant person from your lab.

- IPs & machine names to connect to Irene: 134.157.47.46 (ssh-out.lmd.jussieu.fr) and 134.157.176.129 (ciclad.ipsl.upmc.fr). Note that this is assuming you have an account on LMD computers and/or the MESOIPSL cluster. Otherwise you must provide name & IP of your institute's gateway machine.

- Chose anything you want for the 8 character password

* And then get Ehouarn to sign the form and forward it to Franck for him to sign as well.

* Send the signed form to hotline.tgcc@cea.fr

== Some useful commands ==

* To access the disks of our project on Irene ("Atmosphères Planétaires" GENCI project), add the following line in your .bash_profile file:
(.bash_profile rather than .bashrc, because otherwise scp may not find your files when fetching them from $CCCWORKDIR on irene to your machine)

<syntaxhighlight lang="bash">
module switch dfldatadir/gen10391
</syntaxhighlight>

* To access your work directory (to run your simulations)

<syntaxhighlight lang="bash">
cd /ccc/work/cont003/gen10391/
</syntaxhighlight>

you can also access the work directory with:

<syntaxhighlight lang="bash">
cd $CCCWORKDIR
</syntaxhighlight>

* To access your store directory (to store big data files we are limited in inode number not in filesize! It is recommended to store files of at least 50M, preferably more, e.g. big tar files of 10G or more)
<syntaxhighlight lang="bash">
cd /ccc/work/cont003/gen10391/
</syntaxhighlight>

you can also access the store directory with:

<syntaxhighlight lang="bash">
cd $CCCSTOREDIR
</syntaxhighlight>

* To access the scratch directory
<syntaxhighlight lang="bash">
cd $CCCSCRATCHDIR
</syntaxhighlight>
IMPORTANT: the scratchdir is fast access, very big, BUT regularly automatically purged! If you use it do remember to backup stuff on the WORKDIR or STOREDIR.

The scratch purge policy (from machine.info):
<pre>
* Files not accessed for 60 days are automatically purged
* Symbolic links are not purged
* Directories that have been empty for more than 30 days are removed
</pre>
There is a dedicated command
<syntaxhighlight lang="bash">
ccc_will_purge
</syntaxhighlight>
which should return information about upcoming purge on your scratch space. Note that the database this command queries is only refreshed on a nightly basis, so it will incorrectly reflect changes you just made this very day.

One nice idea is to put this command in your .bashrc, so that it runs everytime you connect to Irene (you can add the ''-s'' option to avoid having long list of files displaying on your screen). If you do so, you have to encapsulate it in a conditional test to check if you're in interactive mode, otherwise it will prevent any rsync/scp between Irene and other machines (which are not in interactive and will thus block on the ccc_will_purge command) :
<syntaxhighlight lang="bash">
if [ -n "${PS1:-}" ]; then
ccc_will_purge -s
fi
</syntaxhighlight>

And a nice command (copyleft Antoine Martinez and Olivier from LATMOS) to update all the "Access" and "Change" stats of the files in your current directory (and sub-directories), without changing the "Modify" stat (so that you can still sort them by date of modification with 'ls -lt') :
<syntaxhighlight lang="bash">
cd $CCCSCRATCHDIR
find . -type f -exec touch -a {} \;
</syntaxhighlight>
This will prevent your files on the scratchdir to be purged for another 60 days.

* To access Irene Interactive Documentation:
<syntaxhighlight lang="bash">
machine.info
</syntaxhighlight>

NB: you can also access the online documentation here: http://www-hpc.cea.fr/tgcc-public/en/html/toc/fulldoc/Introduction.html

* To display infos about project accounting:
<syntaxhighlight lang="bash">
ccc_myproject
</syntaxhighlight>

* To know about user and group disk quota
<syntaxhighlight lang="bash">
ccc_quota -a
</syntaxhighlight>

* To know about how long your passwd will be active:
<syntaxhighlight lang="bash">
ccc_password_expiration
</syntaxhighlight>

* To change passwd:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>

== Example of a job to run a GCM simulation ==

=== Mixed openMP / MPI ===

<syntaxhighlight lang="bash">
#!/bin/bash
# Partition to run on:
#MSUB -q rome
# project to run on
#MSUB -A gen10391
# disks to use
#MSUB -m scratch,work,store
# Job name
#MSUB -r run_gcm
# Job standard output:
#MSUB -o run_gcm.%I
# Job standard error:
#MSUB -e run_gcm.%I
# number of OpenMP threads c
#MSUB -c 2
# number of MPI tasks n
#MSUB -n 16
# number of nodes to use N
#MSUB -N 1
# max job run time T (in seconds)
#MSUB -T 3600
# request exculsive use of the node (128 cores)
##MSUB -x

source ../trunk/LMDZ.COMMON/arch.env
export OMP_STACKSIZE=400M
export OMP_NUM_THREADS=2

ccc_mprun -l gcm_32x32x15_phystd_para.e > gcm.out 2>&1

</syntaxhighlight>

=== Pure MPI + long run ===

The most important parameter for mpi-only runs is ''-n''
providing the total number of CPUs
(ideally a multiple of 128, which is the number of CPUs per core).

Runs longer than 1 day are not possible unless
selecting a quality-of-service (QoS) "long"

<syntaxhighlight lang="bash">
#!/bin/bash

# Partition to run on:
#MSUB -q rome
# project to run on
#MSUB -A gen10391
# disks to use
#MSUB -m scratch,work,store
# Job name
#MSUB -r run_wrf
# Job standard output:
#MSUB -o run_wrf.%I
# Job standard error:
#MSUB -e run_wrf.%I
# number of MPI tasks n (total)
#MSUB -n 256
# max job run time T (in seconds)
#MSUB -T 345600
# select quality-of-service
# - test < 30min
# - normal < 1d (default)
# - long < 3d
#MSUB -Q long

#############################

# load the modules used to compile
source arch.env

# clean the logs
rm -rf rsl.*

# create initial state
# -- this is done on a single proc
ideal.exe
mv rsl.error.0000 ideal_rsl.error.0000
mv rsl.out.0000 ideal_rsl.out.0000

# main launch
ccc_mprun -l wrf.exe

</syntaxhighlight>

=== Priority Short Job ===
If you have a job that requires less than 30 minutes of user time (<code>#MSUB -T 1800</code> or less) and no more than 2 nodes, you can launch your job with a "test" quality-of-service (QoS).
This will double the priority of your job in the queue compared to the "normal" or "long" QoS.

<syntaxhighlight lang="bash">
#!/bin/bash
...
# select quality-of-service
# - test < 30min
# - normal < 1d (default)
# - long < 3d
#MSUB -Q test

...

</syntaxhighlight>

== Main submission commands ==

* To launch the job script ''run_gcm.job'':
<syntaxhighlight lang="bash">
ccc_msub run_gcm.job
</syntaxhighlight>
* To display information about your jobs:
<syntaxhighlight lang="bash">
ccc_mpp -u $USER
</syntaxhighlight>
* To kill job number ''jobid''
<syntaxhighlight lang="bash">
ccc_mdel jobid
</syntaxhighlight>
* To display infos about a job (works both while it is running or after it has finished):
<syntaxhighlight lang="bash">
ccc_macct jobid
</syntaxhighlight>
* To display infos about project accounting:
<syntaxhighlight lang="bash">
ccc_myproject
</syntaxhighlight>
* To display infos about limits (quality-of-service QoS):
<syntaxhighlight lang="bash">
ccc_mqinfo
</syntaxhighlight>
* To display infos about partitions:
<syntaxhighlight lang="bash">
ccc_mpinfo
</syntaxhighlight>

== File transfert from Occigen ==
One should use ccfr:
<syntaxhighlight lang="bash">
module load ccfr
</syntaxhighlight>
A list of available machines is given by
<syntaxhighlight lang="bash">
ccfr_ssh -v
</syntaxhighlight>
To log on to Occigen (from Irene):
<syntaxhighlight lang="bash">
ccfr_ssh occigenlogin@cines
</syntaxhighlight>

To copy a file (typically a big tar file):
<syntaxhighlight lang="bash">
ccfr_cp occigenlogin@cines:remote_dir local_dir
</syntaxhighlight>
This command will fail if you try copying over a directory, with a weird error message of the likes of:
<pre>
rsync: write failed on "/ccc/work/...." Disk quota exceeded (122)
</pre>
If copying over directories (via rsync) then you should modify the related rights (which must be "s" for the group on Irene) using dedicated options:
<syntaxhighlight lang="bash">
rsync --chmod=Dg+s --chown=:gen10391 source_on_distant_machine target_on_Irene
</syntaxhighlight>

== Worth knowing about ==
* The command wget is disabled on Irene, scripts using it will fail...
* Only "https" is allowed. This is important for instance when downloading code (via svn, git). Moreover for svn checkouts one has to provide their svn username and password.
*If you encounter a quota issue on Irene, first check if indeed you (or the group's) quota is exceeded:

<syntaxhighlight lang="bash">
ccc_quota
</syntaxhighlight>

In case you get an error message about your quota when copying data over to Irene, it might be because the rights on directories are not well set; please use the following command on your directory before sending the data to Irene:
<syntaxhighlight lang="bash">
chmod -R g+s NAME_OF_DIR
</syntaxhighlight>

== Are you being disconnected when inactive? ==
If you are regularly being disconnected when a bit inactive on the supercomputer, adding these few lines in a ''config'' file in the .ssh/ repository of your logging machine (ex: ssh-out/ciclad) may help :
<syntaxhighlight lang="bash">
Host *
...
KeepAlive yes
TCPKeepAlive yes
ServerAliveInterval 15
</syntaxhighlight>

[[Category:FAQ]]

2023-01-05T10:58:00Z

Abierjon:

== How to create a new module/subroutine ==

Subroutines should be integrated inside a module.
A good writing habit is to add the line "IMPLICIT NONE", in the beginning of the module and subroutine.

First you can define all the variable that belongs to the module and could be used at another place.
A good thing is also to create a subroutine that allocate and initialise module variables.
If the variable is only modified inside the module it should be taged as protected.
If the variable belongs only to the module it can be specified to be private.

You can now start the definition of the subroutine.
Start by variable and function from other module if necessary.
Comment the purpose of the subroutine directly.
Declare the variables, first the one pass in arguments.
Use the intent to specify the status of the variable inside the subroutine.
Continue with the local and saved variables.
Then you can define local variables.
Remember to comment all of them, you can specify the dimension if the variable is an allocatable variable as well as the units and everything that seems appropriate.

You can finally write the code.

<syntaxhighlight lang="Fortran" line>
MODULE aquarium_mod

IMPLICIT NONE

INTEGER :: water ! Define what is the variable, the dimension, units (°) etc...
REAL,SAVE,ALLOCATABLE,DIMENSION(:) :: kre1 ! Another comment

CONTAINS

SUBROUTINE aquarium(kre, grass, other_things
& really_anything)

use another_module_mod, only: fct, variable

!=======================================================================
! subject:
! --------
! What is the subroutine doing
!
! author: Someone smart
! ------
! update: Someone smarter, march 2012:
! - I change something here
!
!=======================================================================

IMPLICIT NONE

!-----------------------------------------------------------------------
!=======================================================================
! Declarations :
!=======================================================================
!
! Input/Output
! ------------
REAL, INTENT(IN) :: something(ngrid,nlayer) ! 2D tabular used as an input only (W/m^2)
REAL, INTENT(OUT) :: kre(ngrid) ! 1D tabular output by the subroutine
REAL, INTENT(INOUT) :: grass(ngrid,nlayer) ! Variable that is modified by the subroutine
! it is an input and output
LOGICAL, INTENT(IN) :: really_anything ! Boolean variable

! Local saved variables
! ---------------------
INTEGER, PARAMETER :: nb_kre = 4 ! Number of kre
INTEGER, SAVE :: rock ! Another variable
LOGICAL, SAVE :: firstcall=.true. ! Another variable

! Local variables
! ---------------
REAL tabular(ngrid) ! Local var
INTEGER i ! Loop var

!=======================================================================
! Beginning of the code
!=======================================================================

IF (firstcall) THEN
! initialize rock
rock = 2
! identify where are the kre
DO i=1,nb_kre
kre(i)=i
if (kre(i).gt.rock) then
write(*,*) "the Kre ", i, "is behind the rock"
else if (mod(kre(i),2).eq.0) then
grass(:,nlayer-1)=grass(:,nlayer-1)-grass(:,nlayer) ! every two kre are eating grass in a very complex way
endif !(kre(i).gt.rock)

ENDDO !end of the loop nb_kre
ENDIF !end firstcall

END SUBROUTINE aquarium

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

SUBROUTINE ini_aquarium(ngrid)
!=======================================================================
! Initialise module's variable
!=======================================================================
IMPLICIT NONE
INTEGER, INTENT(IN) :: ngrid

allocate(kre1(ngrid+1))

END SUBROUTINE ini_aquarium

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

SUBROUTINE end_aquarium
!=======================================================================
! Deallocate module's variable
!=======================================================================

IMPLICIT NONE

IF (allocated(kre1)) deallocate(kre1)

END SUBROUTINE end_aquarium

END MODULE aquarium_mod

</syntaxhighlight>

== How to pass variable to subroutine (by argument or by module) ==

Define when we should use argument and when to use modules
Proposition :
- if the variable is not going to change throughout the run (between two calls of the subroutine) => module variable
- else => subroutine argument

== Naming variables convention ==

What is the naming convention.
In vdifc_mod for exemple.

== Loop index convention ==

Index name for loops through:
* '''physical grid''' : ig (max ngrid)
* ''' vertical levels''' : l (max nlayer)
* '''tracer''' : iq (max nq)
* '''subslopes''' : islope (max nslope)
iaer=1,naerkind

== Efficient loop coding ==

The more outside loop should correcpond to the last index of an array.

Example:
<syntaxhighlight lang="Fortran">
DO l=1,nlayer
DO ig=1,ngrid
array(ig,l)=l*ig
ENDDO
ENDDO
</syntaxhighlight>

== How to use the Intent ==

Argument of a function can come in 3 different way: IN, OUT, INOUT.

== How to comment code ==

* '''In english'''
* '''As much as possible'''
* '''Variable definition''' : explain what it is, the dimension, the units etc...
* '''Subroutine''' : Explain what it does, who wrote it, who modify it and why if it is a big change
* '''Loops''' : if the enddo is far away you can comment to which index it correspond to.
* '''Chapter your code''' : you can add section to your code to make it clearer.

== General guide ==

* Create .F90 instead of .F
* Delete unused argument in a function call if you see one
* Delete unused variables
* Choose meaningful names of variables
* Don't hesitate to comment at much as possible, a code is never too commented
* Delete unused commented code lines

Guide for good coding

2023-01-05T10:55:27Z