Planets - User contributions [en]

The XIOS Library

2026-04-30T09:57:07Z

Jmauxion:

The [https://forge.ipsl.jussieu.fr/ioserver/wiki XIOS] (Xml I/O Server) library is based on client-server principles where the server manages the outputs asynchronously from the client (the climate model) so that the bottleneck of writing data is alleviated.

== Installing the XIOS library ==

=== Prerequisites ===
There are a couple of prerequisites to installing and using the XIOS library:
# An MPI library must be available
# A NetCDF4-HDF5 library, preferably compiled with MPI enabled, must be available (see, e.g. dedicated section on [[The_netCDF_library]])
The rest of this page assume all prerequisites are met. People interested in building an appropriate NetCDF library on their Linux machine might be interested in the following installation script: https://web.lmd.jussieu.fr/~lmdz/pub/script_install/install_netcdf4_hdf5.bash (which might need some adaptations to work in your specific case).

=== Downloading and compiling the XIOS library ===
The XIOS source code is available for download using svn (subversion). To download it, go to your trunk repository and run the line e.g.:
<syntaxhighlight lang="bash">
svn co http://forge.ipsl.fr/ioserver/svn/XIOS/trunk XIOS
</syntaxhighlight>
* To compile the library, one must first have adequate architecture "arch" files at hand, just like for the GCM (see [[The_Target Architecture_("arch")_Files]]). In principle both ''arch.env'' and ''arch.path'' files could be the same as for the GCM; ''arch.fcm'' will of course differ, as XIOS source code is in C++ (along with a Fortran interface). If using a "known" machine (e.g. Occigen, Irene-Rome, Ciclad) then ready-to-use up-to-date arch files for that machine should be present in the ''arch'' directory. If not you will have to create your own (it is advised to use the existing ones as templates!)
* Assuming ''some_machine'' arch files (i.e. files ''arch-some_machine.env'', ''arch-some_machine.path'', ''arch-some_machine.fcm'') are present in the '''arch''' subdirectory, compiling the XIOS is done using the dedicated ''make_xios'' script, e.g.:
<syntaxhighlight lang="bash">
./make_xios --prod --arch some_machine --job 8
</syntaxhighlight>
If the compilation steps went well then the '''lib''' directory should contain file ''libxios.a'' and the '''bin''' directory should contain
<pre>
fcm_env.ksh generic_testcase.exe xios_server.exe
</pre>

=== XIOS documentation ===
Note that the downloaded XIOS distribution includes some documentation in the '''doc''' subdirectory:
<pre>
reference_xml.pdf XIOS_reference_guide.pdf XIOS_user_guide.pdf
</pre>
Definitely worth checking out!

== Compiling the GCM with the XIOS library ==

To compile with XIOS enabled, one must specify the option
<syntaxhighlight lang="bash">
-io xios
</syntaxhighlight>
to the [[The makelmdz fcm GCM Compilation Script|makelmdz_fcm]] script.

== XIOS output controls ==

All aspects of the outputs (name, units, file, post-processing operations, etc.) are controlled by dedicated XML files which are read at run-time. Samples of xml files are provided in the "deftank" directory.

=== In a nutshell ===
* the master file read by XIOS is ''iodef.xml''; and contains specific XIOS parameters such as ''using_server'' to dictate whether XIOS is run in client-server mode (true) or attached (false) mode, ''info_level'' to set the verbosity of XIOS messages (0: none, 100: very verbose), ''print_file'' to set whether XIOS messages will be sent to standard output (false) or dedicated xios_*.out and xios_*.err files (true).
<syntaxhighlight lang="xml">
<variable id="using_server" type="bool">false</variable>
<variable id="info_level" type="int">0</variable>
<variable id="print_file" type="bool"> false </variable>
</syntaxhighlight>
* It is common practice to have LMDZ-related definitions and outputs in separate XML files, e.g. ''context_lmdz.xml'' which are included in ''iodef.xml'' via the ''src'' attribute, e.g.
<syntaxhighlight lang="xml">
<context id="LMDZ" src="./context_lmdz_physics.xml"/>
</syntaxhighlight>
The ''context_lmdz_physics.xml'' file must then contain all fields/grid/file output definitions, which may be split into multiple XML files, for instance the definition of model variables (i.e. all fields that may be outputed) is often put in a separate file ''field_def_physics.xml'' which is referenced within ''context_lmdz_physics.xml'' as:
<syntaxhighlight lang="xml">
<field_definition src="./field_def_physics.xml" />
</syntaxhighlight>
Concerning output files, the current recommended practice is to use separate ''file_def_histsomething_lmdz.xml'' files, one for each ''histsomething.nc'' file to generate, and include these in ''context_lmdz.xml'' using the ''file_definition'' key. e.g.:
<syntaxhighlight lang="xml">

<file_definition src="./file_def_histins.xml"/>
<file_definition src="./file_def_specIR.xml"/>
</syntaxhighlight>

=== Some XIOS key concepts ===
==== calendars ====
The calendar is set via the Fortran source code (see '''xios_output_mod.F90''' in the physics). Without going into details here, note that it is flexible enough so that day length, year length, etc. may be defined by the user. However a strong limitation is that the calendar time step should be an integer number of seconds.

TODO: refer to specific stuff/settings for Mars, Generic, Venus cases...

==== axes, domains and grids ====
First a bit of XIOS nomenclature:
* an '''axis''' is 1D; e.g. pseudo-altitude or pseudo-pressure or sub-surface depth or wavelength or ...
* a '''domain''' is a horizontal 2D surface; e.g. the globe or some portion of it
* a '''grid''' is the combination of a domain and one axis (or more); e.g. the atmosphere or the sub-surface of a planet
Most of the '''axis''' and '''domain''' are defined in the code (since all the information is known there) and only referred to in the XML via dedicated '''id''' values, e.g.:
<syntaxhighlight lang="xml">
<axis_definition>
<axis id="presnivs"
standard_name="Pseudo-pressure of model vertical levels"
unit="Pa">
</axis>
<axis id="altitude"
standard_name="Pseudo-altitude of model vertical levels"
unit="km">
</axis>
</axis_definition>
</syntaxhighlight>
Likewise the global computational domain is defined in the code and known in the XML via its '''id'''(="dom_glo"):
<syntaxhighlight lang="xml">
<domain_definition>
<domain id="dom_glo" data_dim="2" />
</domain_definition>
</syntaxhighlight>
From there one may generate a grid, e.g.:
<syntaxhighlight lang="xml">
<grid_definition>

<grid id="grid_3d">
<domain id="dom_glo" />

<axis id="altitude" />
</grid>
</grid_definition>
</syntaxhighlight>
Note that '''grid_3d''' is defined in the XML file and thus may be changed by the user without having to modify the PCM source code. For instance by simply adding the following definitions:
<syntaxhighlight lang="xml">
<domain_definition>
...
<domain id="dom_128_96" ni_glo="128" nj_glo="96" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>
</domain_definition>
<grid_definition>
...
<grid id="my_grid_3d">
<domain id="dom_128_96" />
<axis id="altitude" />
</grid>
</grid_definition>
</syntaxhighlight>
Specifying to output variables on grid '''my_grid_3d''' will trigger XIOS interpolations so that the output fields are on a regular 128x96 longitudexlatitude grid.

One can also add some specifications on the longitude and latitude bounds of the domain to generate:
<syntaxhighlight lang="xml">
<domain_definition>
...
<domain id="dom_64_49" ni_glo="64" nj_glo="49" type="rectilinear" >
<generate_rectilinear_domain lat_start="90" lat_end="-90" lon_start="-180" lon_end="174.375" />
<interpolate_domain order="1"/>
</domain>
</domain_definition>
...
</syntaxhighlight>

==== field definitions ====
For XIOS a field is defined with and '''id''' and most be assigned to a reference '''grid''' (this is how XIOS knows a field is a simple scalar, or a surface or a volume, and thus to which computational grid it is related to).e.g.:
<syntaxhighlight lang="xml">
<field_definition prec="4">
<field_group id="fields_2D" domain_ref="dom_glo">
<field id="aire"
long_name="Mesh area"
unit="m2" />
<field id="phis"
long_name="Surface geopotential (gz)"
unit="m2/s2" />
<field id="tsol"
long_name="Surface Temperature"
unit="K" />
...

</field_group>

<field_group id="fields_3D" grid_ref="grid_3d">
<field id="temp"
long_name="Atmospheric temperature"
unit="K" />
<field id="pres"
long_name="Atmospheric pressure"
unit="Pa" />
...

</field_group>

</field_definition>
</syntaxhighlight>

It is vital that all the fields which are sent to XIOS via the code are declared in the XML file otherwise there will be a run-time error message of the likes of:
<pre>
In file "object_factory_impl.hpp", function "static std::shared_ptr<U> xios::CObjectFactory::GetObject(const std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char>> &) [with U = xios::CAxis]", line 78 -> [ id = weirdvar, U = field ] object was not found.
</pre>
In the message above XIOS received from the code a variable called "weirdvar" which is not defined in the XML... One must update the XML file with the proper definition (<field id="weirdvar" ... />).

==== output file definitions ====
It is by defining a '''file''' that the user specifies what the output file will be, which variables it will contain, etc. as illustrated with this simple Venusian example:
<syntaxhighlight lang="xml">
<file_definition>

<file id="Xins"
output_freq="1ts"
type="one_file"
enabled=".true.">


<field_group operation="instant"
freq_op="1ts">
<field field_ref="phis" operation="once" />
<field field_ref="aire" operation="once" />
<field field_ref="tsol" />
</field_group>


<field_group operation="instant"
freq_op="1ts">
<field field_ref="temp" />
<field field_ref="pres" />
</field_group>
</file>
</syntaxhighlight>
It is mandatory to have an '''operation''' attribute defined (this can be either done at the level of the definition of the variable or, as above at the level of the definition of the outputs); there is no default. If this attribute is missing you will get an error message of the likes of:
<pre>
In file "attribute_template_impl.hpp", function "virtual void xios::CAttributeTemplate<std::basic_string<char>>::checkEmpty() const [T = std::basic_string<char>]", line 78 -> On checking attribute with id=operation : data is not initialized
</pre>

=== Thorougher description with illustrative examples ===
TODO: PUT SOME SIMPLE ILLUSTRATIVE EXAMPLES HERE

See for example the following page: [[controling outputs in the dynamics with DYNAMICO]]

==== Specifying that the time axis should be labeled in days rather than seconds ====
The default for XIOS is to label temporal axes ("time_instant" and "time_counter") in seconds. But one may ask that they be labelled in days by setting the optional '''time_unit''' attribute of a file to '''days''', e.g.
<syntaxhighlight lang="xml">
<file id="my_output_file"
output_freq="1ts"
time_units="days">
...

</file>
</syntaxhighlight>

==== Force flushing and writing files every ### time steps ====
XIOS handles its buffers and only writes to output files when needed. This is quite efficient and worthwhile, except for instance when the model crashes as some data might then not be included in the output files. One may use the '''sync_freq''' (optional) attribute of a file to force XIOS to write to the file at some predefined frequency, e.g.
<syntaxhighlight lang="xml">
<file id="my_output_file"
output_freq="1ts"
sync_freq="1ts">
...

</file>
</syntaxhighlight>
Very useful when debugging.

==== Specifying an offset (in time) for the outputs ====
One may use the attribute '''record_offset''' of a file to impose that the outputs in the file begin after a certain number of time steps of the simulation (useful for instance when debugging). For instance if there are 192 time steps per day and the run is 10 days long but one only wants outputs for the last day and at every time step of that day then one should have a '''record_offset''' of -9*192=-1728 (note the ''-''; the value to specify is negative), e.g.:
<syntaxhighlight lang="xml">
<file id="my_output_file"
output_freq="1ts"
record_offset="-1728ts"
time_units="days">
<field_group operation="instant"
freq_op="1ts">
<field field_ref="my_variable" />
</field_group>
</file>
</syntaxhighlight>
The ''time_counter'' values in the file will be from 9.0052 (=9.+1./192.) to 10. (since here the time axis unit is requested to be in days)

An alternative way to have the first n timesteps of a time series excluded from the output is to specify a ''freq_offset'' attribute to the field. For instance, to follow up on the example above, to extract every time step of the final 10th day of simulation with 192 time steps par day one should specify a '''freq_offset''' of 9*192=1728, e.g.:
<syntaxhighlight lang="xml">
<file id="my_output_file"
output_freq="1ts"
time_units="days">
<field_group operation="instant"
freq_offset="1728ts"
freq_op="1ts">
<field field_ref="my_variable" />
</field_group>
</file>
</syntaxhighlight>
The main difference, compared to the previous example using the '''record_offset''' file attribute, is that the ''time_counter'' values in the file will this time be from 0.0052 (=1./192) to 1.0.

==== Saving or loading interpolation weights ====
With the XIOS library one can define output domains (grid) which are different from input domains (grids), and XIOS does the necessary interpolation.

This requires, once source and destination grids are known, to compute some interpolation weights (during the initialization step). For large grids, this can take some time. One can however tell XIOS to save the interpolation weights in a file and use that file (if it is present) rather than recompute them when a new simulation is ran.

In practice one must add extra keys to the "interpolate_domain" tag, e.g.:
<syntaxhighlight lang="xml">
<domain id="dom_256_192" type="rectilinear" ni_glo="256" nj_glo="192" >
<generate_rectilinear_domain/>
<interpolate_domain order="1" write_weight="true" mode="read_or_compute" />
</domain>
</syntaxhighlight>
This will automatically generate a NetCDF file containing the weights. Default file name will be something like xios_interpolation_weights_CONTEXT_INPUTDOMAIN_OUTPUTDOMAIN.nc , where CONTEXT, INPUTDOMAIN and OUTPUTDOMAIN are inherited from the context (i.e. definitions of these in the xml files).

One can specify the name of the file with the key "weight_filename", e.g.
<syntaxhighlight lang="xml">
<domain id="dom_256_192" type="rectilinear" ni_glo="256" nj_glo="192" >
<generate_rectilinear_domain/>
<interpolate_domain order="1" write_weight="true" mode="read_or_compute" weight_filename="xios_weights" />
</domain>
</syntaxhighlight>

==== Preserving extensive variables ====
It can also happen that for a given variable (extensive ones for instance) we want the interpolation not to be conservative. For example, a variable like the area of a mesh grid should not be interpolated between different domains. Since the interpolation is specific to a domain (and defined in the "domain id"), we have to create a new domain for all the variable that should be interpolated in another way. For the variable "Area" for example, the syntax is as follow :

* Create the new domain:
<syntaxhighlight lang="xml">
<domain id="dom_64_48_quantity_T" type="rectilinear" ni_glo="64" nj_glo="48" >
<generate_rectilinear_domain/>
<interpolate_domain quantity="true"/>
</domain>
</syntaxhighlight>

* Assign the variable to this domain:
Later in the context file, the variable should be outputted using this new domain (note that it still can be outputed in the same file as the other variables) :
<syntaxhighlight lang="xml">
<field_group domain_ref="dom_64_48_quantity_T">
<field_group operation="instant"
freq_op="1ts">
<field field_ref="area" operation="once" />
</field_group>
</field_group>
</syntaxhighlight>

=== Examples & adding outputs ===

See [[LMDZ XIOS outputs]] for more details on the outputs generated via XIOS for the LMDZ dynamics/physics.

If you use [[DYNAMICO]], check out the [[Controling outputs in the dynamics with DYNAMICO|DYNAMICO outputs]] page.

== Using the XIOS library in client-server mode ==
To run with XIOS in client-server mode requires the following:
* The client-server mode should be activated (in file ''iodef.xml''):
<syntaxhighlight lang="xml">
<variable id="using_server" type="bool">true</variable>
</syntaxhighlight>
* The '''xios_server.exe''' executable should be present alongside the GCM executable '''gcm_***.e''' and they should be run together in MPMD (Multiple Programs, Multiple Data) mode : some of the MPI processes being allocated to the GCM and the others to XIOS ; in practice much less are needed by XIOS than the GCM, this however also depends on the amount of outputs and postprocessing computations, e.g. temporal averaging and grid interpolations, that XIOS will have to do. For example if the MPI execution wrapper is ''mpirun'' and that 26 processes are to be used by the GCM ''gcm_64x52x20_phygeneric_para.e'' and 2 by XIOS (i.e. using overall 28 processes):
<syntaxhighlight lang="bash">
mpirun -np 26 gcm_64x52x20_phygeneric_para.e > gcm.out 2>&1 : -np 2 xios_server.exe
</syntaxhighlight>

[[Category:Generic-Model]]
[[Category:Mars-Model]]
[[Category:Venus-Model]]
[[Category:Titan-Model]]

Tool Box Mars PCM

2025-06-16T10:45:17Z

Jmauxion:

== Post-processing tools provided with the Mars PCM ==
First and foremost there are a number of postprocessing utilities (self-standing tools) which can be found in the
<pre>
LMDZ.MARS/util
</pre>
directory; you certainly want to first read the README file there.

Current contents of this directory is:
<pre>
aeroptical.def expandstartfi.F90 localtime.def solzenangle.F90
aeroptical.F90 extract.F90 localtime.F90 startarchive2icosa
aeropt_mod.F90 extract.points.def lslin.def streamfunction.F90
analyse_netcdf.py extract.profile.def lslin.F90 xvik
compile gencol.def README zrecast.auto.def
concatnc.def gencol.F90 simu_MCS.def zrecast.F90
concatnc.F90 hrecast.def simu_MCS.F90 zrecast.manual.def
display_netcdf.py hrecast.F90 solzenangle.def
</pre>
the ''compile'' script is an example of how to compile any of the utilities, which you will have to adapt to your needs (mostly concerns setting the right path to the NetCDF library). All the post-processing tools are meant to be run interactively (asking the user for some instructions), hence the ''*.def'' files as it is most of the time more convenient (once one knows the tools and questions it will ask) to redirect this list of answers to the standard input of the tool, e.g.
<syntaxhighlight lang="bash">
zrecast.e < zrecast.manual.def
</syntaxhighlight>

== Main programs (other than GCM) but included in the Mars PCM package ==
There are a few other main programs that are included with the GCM.

Advanced stuff: In practice these main programs are located under ''LMDZ.MARS/dynphy_lonlat/phymars/'' as they are at the interface between lon-lat dynamics and the Mars physics package (i.e. need to use both and thus can only be applied in that context).

=== start2archive ===
A main program to collect multiple <code>start.nc</code> and <code>startfi.nc</code> files from a series simulations and store them in a <code>start_archive.nc</code> file. For this one simply needs to run the <code>startarchive</code> program in the directory. It will automatically fetch code>start.nc</code> and <code>startfi.nc</code> files and generate <code>start_archive.nc</code>. If a <code>start_archive.nc</code> file is already present then the current <code>start.nc</code> and <code>startfi.nc</code> files are added to the <code>start_archive.nc</code> file (which can contain multiple initial states, as long as they are on the same grid and correspond to different dates.

=== newstart ===
A main program to:
* extract (and interpolate) <code>restart.nc</code> and <code>restartfi.nc</code> files from a <code>start_archive.nc</code> file or from a pair of <code>start.nc</code> and <code>startfi.nc</code> files. The subtle difference between the two setup is that grid interpolation (horizontal and/or vertical) is only possible if using a <code>start_archive.nc</code> input file
* modify values and fields contained in the initial condition file
* Compiling <code>newstart</code> is done using the [[The makelmdz fcm GCM Compilation Script|makelmdz_fcm]] utility. The program is then meant to be run interactively with the user providing options and choices when prompted.
* Once the program has run and finished without error, it will generate <code>restart.nc</code> and <code>restartfi.nc</code>

=== xvik ===
A post-processing utility to analyse the modeled CO2 cycle

== testphys1d ==
More than a pre- or post-processing tool, this is a 1D (single column) version of the PCM. More about it is on the dedicated page: [[Mars 1D testphys1d program]].

Note that there is also a separate "self-standing" 1D model, the "1D thermal model", which can be downloaded from this page: [http://www-planets.lmd.jussieu.fr/ http://www-planets.lmd.jussieu.fr/]. This is essentially a frozen version of ''testphys1d'' with some additional tweaks to make it more user-friendly.

== Visualizing the outputs ==
The GCM and most of the post-processing tools mentioned above produce NetCDF files, which one most likely will need to visualize.
There are a number of tools available (free or not). Here is a selection:
* Ncview is a very basic tool, mostly useful for a simple quick look.
* Panoply is a user-friendly tool for viewing NetCDF data, available here: https://www.giss.nasa.gov/tools/panoply/
* Ferret is another nice tool for viewing and processing NetCDF data, see their official page: https://ferret.pmel.noaa.gov/Ferret/ and also [[Some Ferret tips and pointers|this page]]
* Many also like to write up their own python scripts

== Maniuplating NetCDF files with external tools ==
In addition to the programs that come with the Mars PCM distribution, there are many public tools available that provide more general capabilities. Here are some selections that you may
find to be of value:
* NetCDF Operators (NCO): This toolbox is a combination of compiled programs and scripts for manipulating NetCDF files, including regridding and interpolating. This public domain tools was developed at the University of California - Irvine and appears to be actively maintained. Find it (along with documentation) at the official site: https://nco.sourceforge.net. A reasonable tutorial, though it is html based and a few years old (like playing an Atari console game), may be downloaded here: https://www.hydroshare.org/resource/4b5a903a02e64b078d5a581a010f45a4/

[[Category:Mars-Model]]
[[Category:Mars-1D]]