Quick Install and Run Titan PCM

2026-01-14T10:50:02Z

Clément Petetin: /* Compiling the Titan PCM */

In this page we give a hopefully exhaustive enough overview of the necessary prerequisites and steps to download, compile and run a simple simulation with the GCM on a Linux computer.

Automating the process is not trivial as there are many subtle variants of Linux flavors and user account setups, so the script may fail in your case, but hopefully the information given in this page should help you solve the encountered problems.

== Prerequisites: Tools and Libraries ==
In order to use (i.e. compile and run) the GCM, one needs to have some tools and installed libraries at hand. We list below a (minimal) set that you should check that is available and/or that you'll need to first install on your machine. Note that we assume in this tutorial that you are on a Linux native-OS/cluster.

=== Fortran compiler ===
The GCM source code is in Fortran. One thus needs a Fortran compiler to build (compile) the executable.
The most easily available one (on Linux) is gfortran and examples discussed here will assume it is the one used.
You can check that you indeed have a gfortran compiler at hand with the following Bash command:
<syntaxhighlight lang="bash">
which gfortran
</syntaxhighlight>
which should return something like
<syntaxhighlight lang="bash">
/usr/bin/gfortran
</syntaxhighlight>

=== Subversion ===
The source code is managed using subversion (svn), which you'll need to download or update. Leaving aside the subtleties of svn and code organization for now, downloading the code amounts to doing the following:
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk --depth empty
cd trunk
svn update LMDZ.COMMON LMDZ.TITAN
</syntaxhighlight>

As a side note: the source code that will be fetched by svn can also be browsed online here: https://trac.lmd.jussieu.fr/Planeto

Note: if the command line above doesn't work, you may also try to replace 'http' by 'https'.

=== Git ===

Alternatively to svn, you can use [[Git usage|git to download the source code]].

=== FCM ===
The FCM (Flexible Configuration Management) tool is a suite of perl scripts to help building and managing codes. We use a slightly modified version which can be obtained using subversion (svn). Ideally you'll want to download it somewhere on your computer once in for all. To do this:
<syntaxhighlight lang="bash">
svn checkout https://forge.ipsl.jussieu.fr/fcm/svn/PATCHED/FCM_V1.2
</syntaxhighlight>
You'll then need to add the resulting FCM_V1.2/bin to your PATH environment variable so that the command "fcm" may be used from anywhere on your machine. e.g. by adding the following line in your .bashrc:
<syntaxhighlight lang="bash">
export PATH=$PATH:$HOME/FCM_V1.2/bin
</syntaxhighlight>
The assumption here is that the downloaded FCM_V1.2 directory is in your home ($HOME) directory. Adapt accordingly if not.

=== the NetCDF library ===
The GCM reads and writes input and output files in NetCDF format, therefore a NetCDF library is required. Most of the clusters propose a NetCDF library that you can load before using the model.

If this library is not available, you can install it by yourself on your system (check out [[the netCDF library]] page for more). You can use the following home-made "install_netcdf4_hdf5_seq.bash" script to do so. For this, ensure that you are in your home directory:
<syntaxhighlight lang="bash">
mkdir netcdf
cd netcdf
wget -nv --no-check-certificate http://www.lmd.jussieu.fr/~lmdz/pub/script_install/install_netcdf4_hdf5_seq.bash
chmod u=rwx install_netcdf4_hdf5_seq.bash
./install_netcdf4_hdf5_seq.bash > netcdf.log 2>&1
</syntaxhighlight>
Compiling the library and dependencies can take a while (>>15 minutes; be patient).
Once this is done, check file netcdf.log to verify that all went well.
You may want to also add its "bin" directory to your PATH environment variable by adding in your .bashrc a line of:
<syntaxhighlight lang="bash">
export PATH=$PATH:$HOME/netcdf/bin
</syntaxhighlight>
The assumption here is that you have run the "install_netcdf4_hdf5_seq.bash" script in a "netcdf" subdirectory of your home directory. Adapt accordingly if not.

As a side note: The NetCDF library provides a very simple command line tool (ncdump) to inspect the contents of NetCDF files, but you'll need more advanced visualization tools (e.g., Panoply, Python scripts, etc. - see further down this page in the "Checking the Results" section) for more advanced post-processing of the outputs.

=== the IOIPSL library ===

The IOIPSL (Input/Output IPSL) library is designed to handle the reading of some input files used by the GCM (the *.def files which are described further below).

==== Automated IOIPSL install script ====
Scripts to download and install the IOIPSL library can be found in the "ioipsl" subdirectory of the "LMDZ.COMMON" library. Since here we assume we're working with gfortran, the relevant one is "install_ioipsl_gfortran.bash". If your PATH environment variable is already such that it includes the path to your NetCDF library distribution's bin directory (see previous section) then all you need to do is execute the script:
<syntaxhighlight lang="bash">
./install_ioipsl_gfortran.bash
</syntaxhighlight>
If all went well the script should end with:
<syntaxhighlight lang="bash">
OK: ioipsl library is in ...
</syntaxhighlight>

''(for further details about [[The_IOIPSL_Library|the IOIPSL library]] and installing it, follow the link and/or use the Search Box at the top of this page)''

=== The XIOS library ===
The Titan PCM uses the XIOS library to manage the outputs of the simulation. To install it, please refer to [[The_XIOS_Library|the XIOS libray]] page.

== GCM Input Datafiles and Datasets ==
In order to run, the GCM needs some inputs, such as initial conditions (values of state variables), external inputs (e.g. optical properties of aerosols) and simulation setup (e.g. specifications on how long to run, which parametrizations should be activated, etc.).

In the spirit of the illustrative example considered here, a set of necessary input data may be downloaded with:
<syntaxhighlight lang="bash">
wget -nv --no-check-certificate
https://web.lmd.jussieu.fr/~lmdz/planets/titan/bench_32x48x55.tar.gz
</syntaxhighlight>

The files needed to run are:
<syntaxhighlight lang="bash">
callphys.def gases.def start.nc startfi.nc traceur.def
datagcm/ run.def z2sig.def iodef.xml context_lmdz_physics.xml
</syntaxhighlight>
* Initial condition NetCDF files ''start.nc'' and ''startfi.nc''; the first containing initial condition values for the dynamics and the second initial condition values for the physics.
* A '''datadir''' directory containing external inputs (aerosol properties, stellar spectra, etc.)
* Some ASCII *.def files containing run parameters, namely:
# [[The_run.def_Input_File | run.def]] : "master def file" containing main run parameters. This file contains the number of days to run. For Titan years, weekly simulations of 11 days are used, except for the last two weeks which are 12 days long, so keep this in mind when setting your run files.
# [[The_callphys.def_Input_File | callphys.def]] : file containing flags and keys for the various physics parametrizations.
# [[The_z2sig.def_Input_File | z2sig.def]] : file describing the sought vertical discretization.
# [[The_traceur.def_Input_File | traceur.def]] : file specifying the tracer number and names.
# [[The_gases.def_Input_File | gases.def]] : file specifying the list of gases (main and trace) in the atmosphere.
# [[The_XIOS_Library#XIOS_output_controls|iodef.xml]] : master file read by XIOS containing specific XIOS parameters.
# [[The_XIOS_Library#XIOS_output_controls|context_lmdz_physics.xml ]]: file containing all fields/grid/file output definitions.

== Compiling the GCM ==
Now that all the prerequisites are fulfilled, it is (almost!) time to compile the GCM

=== Prior to a first compilation: setting up the target architecture files ===
Compiling the model is done using a dedicated Bash script ''makelmdz_fcm'' located in the '''LMDZ.COMMON''' directory. This script however relies on ''architecture files''. These files contain information on which compiler to use, what compilation options to use, where relevant libraries are located etc. In practice, one must thus create these ASCII text files in the '''arch/''' subdirectory of '''LMDZ.COMMON'''. The naming convention is rather straightforward, when the script ''makelmdz_fcm'' is run with the option '''-arch somename''', it will look for files ''arch/arch-somename.env'', ''arch/arch-somename.path'' and ''arch/arch-somename.fcm''. Leaving aside a detailed description for later (see [[The_Target_Architecture_("arch")_Files|this page]]), here we mention that:
* the ''arch*.env'' is an optional file containing ''environment'' information, such as setting up environment variables or loading modules on some machines, e.g.
<syntaxhighlight lang="bash">
export NETCDF_HOME=/path/to/the/netcdf/distribution
</syntaxhighlight>
A more realistic (but more specific) example of a '''arch*.env''' file using "recent" module commands, adapted for compilation and visualisation on a given supercomputer, would look more like the following:
<syntaxhighlight lang="bash">
module purge
module load GCC/10.3.0 OpenMPI/4.1.1
module load netCDF-Fortran/4.5.3
export NETCDF_INCDIR="/opt/ebsofts/netCDF-Fortran/4.5.3-gompi-2021a/include"
export NETCDFF_LIBDIR="/opt/ebsofts/netCDF-Fortran/4.5.3-gompi-2021a/lib"
</syntaxhighlight>
Note that the last two lines above specify paths to the '''include''' and '''lib''' directories used on this system and will certainly vary from system to system. Likewise, the exact module versions will most likely need to be adapted in your specific '''arch*.env''' file.
* the '''arch*.path''' is a mandatory file containing information relative to external libraries such as NetCDF and IOIPSL, e.g.
<syntaxhighlight lang="bash">
ROOT=$PWD

NETCDF_LIBDIR="-L${NETCDF_HOME}/lib"
NETCDF_LIB="-lnetcdf -lnetcdff"
NETCDF_INCDIR="-I${NETCDF_HOME}/include"

IOIPSL_INCDIR="-I$ROOT/../IOIPSL/inc"
IOIPSL_LIBDIR="-L$ROOT/../IOIPSL/lib"
IOIPSL_LIB="-lioipsl"
</syntaxhighlight>
Each library is referenced by a fixed identifier (NETCDF, IOIPSL, XIOS, ...) and 3 trailing strings: '''_LIBDIR''', for the path to the library, '''_LIB''', for the library name(s), and '''_INCDIR''' for the path to the library's ''include'' directory.

* the '''arch*.fcm''' is a mandatory file containing information relative to the compiler and compilation options, e.g.
<syntaxhighlight lang="bash">
%COMPILER gfortran
%LINK gfortran
%AR ar
%MAKE make
%FPP_FLAGS -P -traditional
%FPP_DEF NC_DOUBLE
%BASE_FFLAGS -c -fdefault-real-8 -fdefault-double-8 -ffree-line-length-none -fno-align-commons
%PROD_FFLAGS -O3
%DEV_FFLAGS -O
%DEBUG_FFLAGS -ffpe-trap=invalid,zero,overflow -fbounds-check -g3 -O0 -fstack-protector-all -finit-real=snan -fbacktrace
%MPI_FFLAGS
%OMP_FFLAGS
%BASE_LD
%MPI_LD
%OMP_LD
</syntaxhighlight>
Again, not going into a detailed description (follow [[The_Target_Architecture_("arch")_Files|this link]] for that), just note here that each line corresponds to a keyword (starting with "%") followed by the relevant options. Here, we mention a few of the main ones:
* %COMPILER: The compiler to use (here, gfortran)
* %BASE_FFLAGS: compiler options (always included)
* %PROD_FFLAGS: compilation flags to include if makelmdz_fcm is run with the "-prod" option
* %DEBUG_FFLAGS: compilation flags to include if makelmdz_fcm is run with the "-debug" option
* %BASE_LD: flags to add at the linking step of the compilation

Note that if you are using a recent version of gfortran (10 or more), you have to add an extra option in the %BASE_FFLAGS, that is '''-fallow-argument-mismatch'''

=== Compiling the Titan PCM ===
To compile the GCM at the sought resolution (in LMDZ.COMMON).
<syntaxhighlight lang="bash">

./makelmdz_fcm -arch local -parallel mpi -io xios -d 32x48x55 -b 23x23 -s 1 -p titan gcm

</syntaxhighlight>
Here, we assume that you have generated the '''arch-local.*''' files as per what is suggested in the previous section, and that you will run in parallel using MPI.
The options for ''makelmdz_fcm'' used here imply:
* '''-p titan''': the GCM will use the "titan" physics package (i.e. the titan physics)
* '''-d 32x48x55''': the GCM grid will be 32x48 in longitude x latitude, with 55 vertical levels.
* '''-b 23x23''': the physics radiative transfer will be done using 23 bands in the IR and 23 in the visible.
* '''-io xios''': the GCM will use the XIOS library to write the output file.
For a glimpse at all the possible ''makelmdz_fcm'' options and their meanings, run:
<syntaxhighlight lang="bash">
./makelmdz_fcm -h
</syntaxhighlight>
and/or check the dedicated [[The_makelmdz_fcm_GCM_Compilation_Script|makelmdz_fcm page]].

Upon successful compilation, the executable '''gcm_32x48x55_phytitan_b23x23_para.e''' should be generated in the '''bin''' subdirectory.

To compile more efficiently in parallel, you may add “-j 8” to the compilation line.

=== Known issues ===

* Output frequency: not possible to have 24 outputs per Titan day (the model needs an integer number of seconds).

* The debug mode has problems in 1D, and in 3D with some optical diagnostics and microphysics schemes.

* If the compilation fails, it might be due to the options used in the arch file.
For example, if you are using gfortran prior to 10, you could get an error such as:
<pre>
gfortran: error: unrecognized command line option ‘-fallow-argument-mismatch’; did you mean ‘-Wno-argument-mismatch’?
</pre>
This can be solved by removing the option '''-fallow-argument-mismatch''' from the arch.fcm file.

* If you are using a recent version of gfortran (10 of beyond) without the option '''-fallow-argument-mismatch''', the compilation will probably fail ith the error:
<pre>
136 | . idim_index,nvarid)
| 2
......
211 | ierr = NF_DEF_VAR (nid, "aire", NF_DOUBLE, 2, id,nvarid)
| 1
Error: Rank mismatch between actual argument at (1) and actual argument at (2) (scalar and rank-1)
fcm_internal compile failed (256)
</pre>
Add the compilation option in the arch file to solve the issue.

== Running the GCM ==
To run your first simulation, you need to first copy (or move) the executable '''gcm_32x48x55_phytitan_b23x23_para.e''' to the directory containing the initial conditions and parameter files, e.g. '''bench_titan_32x48x55_b23x23''' and run it.
This is usually a two-step process: the (optional) first step is to source the environment architecture file (the very same that was used to compile the model), e.g.,:
<syntaxhighlight lang="bash">
source ../LMDZ.COMMON/arch.env
</syntaxhighlight>
The second step is to execute the model, e.g.,:
<syntaxhighlight lang="bash">
./ gcm_32x48x55_phytitan_b23x23_para.e > gcm.out 2>&1
</syntaxhighlight>

With this command line, the (text) outputs messages are redirected into a text file, '''gcm.out'''. It is convenient to keep this file for later inspection (e.g., to track a bug). If there is no redirection (only '''./gcm_32x48x55_phytitan_b23x23_para.e'''), then the outputs will be directly on the screen.

== Checking the Results of a Simulation ==
Once the simulation is finished, you'll know that all went well ("everything is cool") if the last few lines of the standard text output reads:
<pre>
in abort_gcm
Stopping in leapfrog
Reason = Simulation finished
Everything is cool
</pre>

If not, start looking for an error message and a way to fix the problem...

Apart from the standard text output messages from the GCM, which are mostly for monitoring and checking the simulation progress, the user will more likely be interested in checking the contents of the NetCDF output file produced by the GCM with proper xios options, as it contains values of the main model variables (atmospheric temperature, winds, etc.).

Side note: There are a variety of freely available software that can be used to visualise the NetCDF output file, such as Panoply, Ferret, Ncview, Grads, Python, etc. (see more details in the [[Tool_Box | Tool Box section]])

== Taking Things to the Next Level ==
The short tutorial presented in this page is meant to be useful to get an overview of what is required to install and run the GCM, in addition to checking the results of a simulation. Moving on to a more intensive and problem-specific usage will require diving into additional topics and aspects such as:
* Selecting the appropriate inputs and run parameters for a given study.
* Post-processing and analysis of model outputs.
All these points and much more are detailed in the many pages of this site (do check out the menu on the left and dare use intensively the site's search engine)!

[[Category:Titan-Model]]
[[Category:Titan-LMDZ]]

Planets - User contributions [en]

Quick Install and Run Titan PCM