Planets - User contributions [en]

Convective adjustment scheme in the generic PCM

2025-04-30T09:26:35Z

Jleconte:

'''IMPORTANT''': This page concerns the convadj routine in the Generic physics package (by the way the latest version may be checked here on the trac: https://trac.lmd.jussieu.fr/Planeto/browser/trunk/LMDZ.GENERIC/libf/phystd/convadj.F

== Overview of the convadj routine ==
The dry convective adjustment is simply a scheme which accounts for the fact that a thermally unstable profile will rapidly be mixed by unresolved (sub-grid-scale) vertical motion and brought back to being stable. This process will not only affect the temperature of the parcel but also tracers and winds (as the convective motion also transports momentum).

It can be turned on with the convadj=.True. keyword.

== Description of assumptions and computations ==
* Estimation of whether a profile is thermally unstable is done by checking the sign of the vertical gradient of potential temperature $$\partial \theta / \partial z$$ (negative when unstable)
* Unstable regions are brought back to being adiabatic, i.e. such that : $$\partial \theta / \partial z = 0$$, while conserving the enthalpy of the column
* based on the "intensity" of the instability, estimated from the relative enthaply exchange necessary to restore the adiabaticity of the profile, related momentum mixing is evaluated and converted to tendencies on the horizontal winds of the air parcel. This momentum transfer evaluation is also used to estimate tracer transfer.

== Mean molecular weight effect ==
If you have a condensing generic tracer and the virtual_theta_correction keyword is True, then the instability of the column is inferred from the gradient of the virtual potential temperature to account for the mean molecular weight effect.

== References ==
See Hourdin et al. JAS 1993 https://doi.org/10.1175/1520-0469(1993)050%3C3625:MVATAS%3E2.0.CO;2

[[Category:Generic-Model]]

Physics of the Generic PCM

2025-04-30T09:15:34Z

Jleconte: /* Thermal plume (thermcell_mod.F90) */

This page describes the various physical parametrizations of the Generic PCM and the chronology of their call through the physical iteration. This chronology is important because some variables need to be updated by certain processes before others (examples).
During one physical iteration, the code passes through multiple sub-routines each encapsulating a parametrization. The sub-routines usually take as arguments:
*the dynamical values of the state variables
*the dynamical tendencies of the state variables
*any additional relevant variable
*any additional relevant tendency
and it returns in general tendencies (of the state variables as well as of any other relevant variable).

Work in progress. Need to add links.

=Initialization=
==First call==
Some initializations only need to be done at the very first iteration (e.g. examples).
==Each call==
Some other initializations need to be done at each iteration (e.g. examples).

=Radiative transfer=
==Correlated-k==
The main radiative transfer solver of the Generic PCM implements the correlated-k method, which provides a flexible and quick way to solve radiative transfer equations, particularly suited for GCMs. More informations here.
==Newtonian relaxation==
Newton was a very relaxed physicist, still inspiring us today.
==No atmosphere==
If you have no atmosphere, why do you need a GCM?

=Vertical diffusion=
Compute the vertical diffusion due to turbulence in the planetary boundary layer
==vdifc==
The "old" vertical diffusion routine.
==turbdiff==
The new (and improved!) vertical diffusion routine

=Convection=

Convective mixing in an atmosphere column involves non-resolved, sub-grid processes. To treat convectively unstable regions, there are two mutually exclusive options (convadj.F90 and thermcell_mod.F90). These processes are parameterized using the following routines:

==Dry convection (convadj.F90)==

This is the simplest and most robust parametrization for dry convective adjustment without free parameters. More info [[Convective_adjustment_scheme_in_the_generic_PCM|here]].

==Thermal plume (thermcell_mod.F90)==
This module implements a more accurate and sophisticated parametrization of convection, although it involves several free parameters that need to be tuned for each planet. More info [[Thermal_plume_model_Generic_PCM|here]].

==Non-orographic gravity waves: (''nonoro_gwd_ran_mod.F90'') ==

Parametrization of the momentum flux deposition due to a discrete number of gravity waves randomly generated by setting their waves characteristics (set as Gaussian distribution).

More info [[Non orographic gravity waves drag|here]].

=CO2 condensation=
Inheriting from the Mars PCM where it is the background species, CO2 condensation is treated as a dedicated step in the Generic PCM's physics. Does that only concern CO2 as a background gas? Or does it work also if CO2 is a non-background variable gas? In any case more info here.

=Tracers=
Many things can be advected by tracers in the Generic PCM, like chemical species or aerosols. Physical processes involving tracers are parameterized using the following routines:

==Volcano==
This routine parameterizes a source of tracers corresponding to volcanic eruption. More information here.

==Water/ice==
Water aerosols (liquid or solid) are created (resp. consumed) by condensation (resp. vaporization or sublimation), consuming (resp. releasing) latent heat in the atmosphere. In the Generic PCM, the (atmospheric part of the) water cycle is handled by various routines, as explained here.

==Photochemistry==
Chemistry can turn molecules into other molecules, by the action of temperature (thermochemistry) or UV light (photochemistry). This is handled by the photochemistry routine, described [[Photochemistry|here]].

==Generic condensation==
On Earth, only water condenses in the atmosphere, but on other planets (which the Generic PCM aims at simulating), many other chemicals can undergo state change. To take that into account, the Generic PCM has a flexible scheme to deal with any arbitrary species, as desbribed [[Radiative_Generic_Condensable_Specie|here]].

==Sedimentation==
What goes up must come down, as explained [[Sedimentation_of_tracers_in_the_generic_PCM|here]].

==Updates==
This section essentially takes care that the condensation of a major species (e.g. water vapor in steam-rich atmospheres) affects other species, as described here.

==Slab ocean==
This routine solves for big fish eating small fish, as described [[Slab_ocean_model|here]].

==Surface==
The surface part of the water cycle is handled here, as the hydrology page describes.

=Heat Conduction in the Subsurface=
The conduction of heat in the subsurface is solved as described [[Soil_Thermal_Conduction_in_the_Generic_PCM|here]].

=Diagnostics/write outputs=
Nothing very physical here, just writting the outputs! By the way, if you want to know how to output new variables in the [[diagfi.nc]] or [[XIOS]] file, check out [[Outputs|this page]].

Physics of the Generic PCM

2025-04-30T09:12:43Z

Jleconte: /* Dry convection (convadj.F90) */

This page describes the various physical parametrizations of the Generic PCM and the chronology of their call through the physical iteration. This chronology is important because some variables need to be updated by certain processes before others (examples).
During one physical iteration, the code passes through multiple sub-routines each encapsulating a parametrization. The sub-routines usually take as arguments:
*the dynamical values of the state variables
*the dynamical tendencies of the state variables
*any additional relevant variable
*any additional relevant tendency
and it returns in general tendencies (of the state variables as well as of any other relevant variable).

Work in progress. Need to add links.

=Initialization=
==First call==
Some initializations only need to be done at the very first iteration (e.g. examples).
==Each call==
Some other initializations need to be done at each iteration (e.g. examples).

=Radiative transfer=
==Correlated-k==
The main radiative transfer solver of the Generic PCM implements the correlated-k method, which provides a flexible and quick way to solve radiative transfer equations, particularly suited for GCMs. More informations here.
==Newtonian relaxation==
Newton was a very relaxed physicist, still inspiring us today.
==No atmosphere==
If you have no atmosphere, why do you need a GCM?

=Vertical diffusion=
Compute the vertical diffusion due to turbulence in the planetary boundary layer
==vdifc==
The "old" vertical diffusion routine.
==turbdiff==
The new (and improved!) vertical diffusion routine

=Convection=

Convective mixing in an atmosphere column involves non-resolved, sub-grid processes. To treat convectively unstable regions, there are two mutually exclusive options (convadj.F90 and thermcell_mod.F90). These processes are parameterized using the following routines:

==Dry convection (convadj.F90)==

This is the simplest and most robust parametrization for dry convective adjustment without free parameters. More info [[Convective_adjustment_scheme_in_the_generic_PCM|here]].

==Thermal plume (thermcell_mod.F90)==
This module implements a more accurate and sophisticated parametrization of convection. More info [[Thermal_plume_model_Generic_PCM|here]].

==Non-orographic gravity waves: (''nonoro_gwd_ran_mod.F90'') ==

Parametrization of the momentum flux deposition due to a discrete number of gravity waves randomly generated by setting their waves characteristics (set as Gaussian distribution).

More info [[Non orographic gravity waves drag|here]].

=CO2 condensation=
Inheriting from the Mars PCM where it is the background species, CO2 condensation is treated as a dedicated step in the Generic PCM's physics. Does that only concern CO2 as a background gas? Or does it work also if CO2 is a non-background variable gas? In any case more info here.

=Tracers=
Many things can be advected by tracers in the Generic PCM, like chemical species or aerosols. Physical processes involving tracers are parameterized using the following routines:

==Volcano==
This routine parameterizes a source of tracers corresponding to volcanic eruption. More information here.

==Water/ice==
Water aerosols (liquid or solid) are created (resp. consumed) by condensation (resp. vaporization or sublimation), consuming (resp. releasing) latent heat in the atmosphere. In the Generic PCM, the (atmospheric part of the) water cycle is handled by various routines, as explained here.

==Photochemistry==
Chemistry can turn molecules into other molecules, by the action of temperature (thermochemistry) or UV light (photochemistry). This is handled by the photochemistry routine, described [[Photochemistry|here]].

==Generic condensation==
On Earth, only water condenses in the atmosphere, but on other planets (which the Generic PCM aims at simulating), many other chemicals can undergo state change. To take that into account, the Generic PCM has a flexible scheme to deal with any arbitrary species, as desbribed [[Radiative_Generic_Condensable_Specie|here]].

==Sedimentation==
What goes up must come down, as explained [[Sedimentation_of_tracers_in_the_generic_PCM|here]].

==Updates==
This section essentially takes care that the condensation of a major species (e.g. water vapor in steam-rich atmospheres) affects other species, as described here.

==Slab ocean==
This routine solves for big fish eating small fish, as described [[Slab_ocean_model|here]].

==Surface==
The surface part of the water cycle is handled here, as the hydrology page describes.

=Heat Conduction in the Subsurface=
The conduction of heat in the subsurface is solved as described [[Soil_Thermal_Conduction_in_the_Generic_PCM|here]].

=Diagnostics/write outputs=
Nothing very physical here, just writting the outputs! By the way, if you want to know how to output new variables in the [[diagfi.nc]] or [[XIOS]] file, check out [[Outputs|this page]].

Physics of the Generic PCM

2025-04-30T09:09:23Z

Jleconte:

This page describes the various physical parametrizations of the Generic PCM and the chronology of their call through the physical iteration. This chronology is important because some variables need to be updated by certain processes before others (examples).
During one physical iteration, the code passes through multiple sub-routines each encapsulating a parametrization. The sub-routines usually take as arguments:
*the dynamical values of the state variables
*the dynamical tendencies of the state variables
*any additional relevant variable
*any additional relevant tendency
and it returns in general tendencies (of the state variables as well as of any other relevant variable).

Work in progress. Need to add links.

=Initialization=
==First call==
Some initializations only need to be done at the very first iteration (e.g. examples).
==Each call==
Some other initializations need to be done at each iteration (e.g. examples).

=Radiative transfer=
==Correlated-k==
The main radiative transfer solver of the Generic PCM implements the correlated-k method, which provides a flexible and quick way to solve radiative transfer equations, particularly suited for GCMs. More informations here.
==Newtonian relaxation==
Newton was a very relaxed physicist, still inspiring us today.
==No atmosphere==
If you have no atmosphere, why do you need a GCM?

=Vertical diffusion=
Compute the vertical diffusion due to turbulence in the planetary boundary layer
==vdifc==
The "old" vertical diffusion routine.
==turbdiff==
The new (and improved!) vertical diffusion routine

=Convection=

Convective mixing in an atmosphere column involves non-resolved, sub-grid processes. To treat convectively unstable regions, there are two mutually exclusive options (convadj.F90 and thermcell_mod.F90). These processes are parameterized using the following routines:

==Dry convection (convadj.F90)==
More info [[Convective_adjustment_scheme_in_the_generic_PCM|here]].

==Thermal plume (thermcell_mod.F90)==
This module implements a more accurate and sophisticated parametrization of convection. More info [[Thermal_plume_model_Generic_PCM|here]].

==Non-orographic gravity waves: (''nonoro_gwd_ran_mod.F90'') ==

Parametrization of the momentum flux deposition due to a discrete number of gravity waves randomly generated by setting their waves characteristics (set as Gaussian distribution).

More info [[Non orographic gravity waves drag|here]].

=CO2 condensation=
Inheriting from the Mars PCM where it is the background species, CO2 condensation is treated as a dedicated step in the Generic PCM's physics. Does that only concern CO2 as a background gas? Or does it work also if CO2 is a non-background variable gas? In any case more info here.

=Tracers=
Many things can be advected by tracers in the Generic PCM, like chemical species or aerosols. Physical processes involving tracers are parameterized using the following routines:

==Volcano==
This routine parameterizes a source of tracers corresponding to volcanic eruption. More information here.

==Water/ice==
Water aerosols (liquid or solid) are created (resp. consumed) by condensation (resp. vaporization or sublimation), consuming (resp. releasing) latent heat in the atmosphere. In the Generic PCM, the (atmospheric part of the) water cycle is handled by various routines, as explained here.

==Photochemistry==
Chemistry can turn molecules into other molecules, by the action of temperature (thermochemistry) or UV light (photochemistry). This is handled by the photochemistry routine, described [[Photochemistry|here]].

==Generic condensation==
On Earth, only water condenses in the atmosphere, but on other planets (which the Generic PCM aims at simulating), many other chemicals can undergo state change. To take that into account, the Generic PCM has a flexible scheme to deal with any arbitrary species, as desbribed [[Radiative_Generic_Condensable_Specie|here]].

==Sedimentation==
What goes up must come down, as explained [[Sedimentation_of_tracers_in_the_generic_PCM|here]].

==Updates==
This section essentially takes care that the condensation of a major species (e.g. water vapor in steam-rich atmospheres) affects other species, as described here.

==Slab ocean==
This routine solves for big fish eating small fish, as described [[Slab_ocean_model|here]].

==Surface==
The surface part of the water cycle is handled here, as the hydrology page describes.

=Heat Conduction in the Subsurface=
The conduction of heat in the subsurface is solved as described [[Soil_Thermal_Conduction_in_the_Generic_PCM|here]].

=Diagnostics/write outputs=
Nothing very physical here, just writting the outputs! By the way, if you want to know how to output new variables in the [[diagfi.nc]] or [[XIOS]] file, check out [[Outputs|this page]].

The start.nc and startfi.nc input files

2024-10-16T09:58:41Z

Jleconte:

== GCM initial condition files ==

To run, the GCM requires initial conditions (i.e. values of state variables at a given instant). These are provided as two NetCDF files, '''start.nc''' (which contains state variables for the dynamics) and '''startfi.nc''' (state variables for the physics). As these files contain information about fields at given grid points, they must be ''at the same resolution'' as the GCM; in other words, the GCM does not do any interpolation of initial conditions which must thus be provided on the exact same grid that the model uses.

== start.nc file Contents ==
A dump of the header of a typical '''start.nc''' (obtained via '''ncdump -h start.nc''') will show contents of the likes of:
<pre>
netcdf start {
dimensions:
index = 100 ;
rlonu = 33 ;
latitude = 33 ;
longitude = 33 ;
rlatv = 32 ;
altitude = 15 ;
interlayer = 16 ;
Time = UNLIMITED ; // (1 currently)
variables:
float controle(index) ;
controle:title = "Parametres de controle" ;
float rlonu(rlonu) ;
rlonu:title = "Longitudes des points U" ;
float rlatu(latitude) ;
rlatu:title = "Latitudes des points U" ;
float rlonv(longitude) ;
rlonv:title = "Longitudes des points V" ;
float rlatv(rlatv) ;
rlatv:title = "Latitudes des points V" ;
float ap(interlayer) ;
ap:title = "Coef A: hybrid pressure levels" ;
float bp(interlayer) ;
bp:title = "Coef B: hybrid sigma levels" ;
float aps(altitude) ;
aps:title = "Coef AS: hybrid pressure at midlayers" ;
float bps(altitude) ;
bps:title = "Coef BS: hybrid sigma at midlayers" ;
float presnivs(altitude) ;
float latitude(latitude) ;
latitude:units = "degrees_north" ;
latitude:long_name = "North latitude" ;
float longitude(longitude) ;
longitude:long_name = "East longitude" ;
longitude:units = "degrees_east" ;
float altitude(altitude) ;
altitude:long_name = "pseudo-alt" ;
altitude:units = "km" ;
altitude:positive = "up" ;
float cu(latitude, rlonu) ;
cu:title = "Coefficient de passage pour U" ;
float cv(rlatv, longitude) ;
cv:title = "Coefficient de passage pour V" ;
float aire(latitude, longitude) ;
aire:title = "Aires de chaque maille" ;
float phisinit(latitude, longitude) ;
phisinit:title = "Geopotentiel au sol" ;
float Time(Time) ;
Time:title = "Temps de simulation" ;
Time:units = "days since 1-01-01 00:00:00" ;
float ucov(Time, altitude, latitude, rlonu) ;
ucov:title = "Vitesse U" ;
float vcov(Time, altitude, rlatv, longitude) ;
vcov:title = "Vitesse V" ;
float teta(Time, altitude, latitude, longitude) ;
teta:title = "Temperature" ;
float co2_ice(Time, altitude, latitude, longitude) ;
co2_ice:title = "Traceur co2_ice" ;
float h2o_ice(Time, altitude, latitude, longitude) ;
h2o_ice:title = "Traceur h2o_ice" ;
float h2o_vap(Time, altitude, latitude, longitude) ;
h2o_vap:title = "Traceur h2o_vap" ;
float masse(Time, altitude, latitude, longitude) ;
masse:title = "C est quoi ?" ;
float ps(Time, latitude, longitude) ;
ps:title = "Pression au sol" ;

// global attributes:
:title = "Dynamic start file" ;
}
</pre>

=== controle ===
The variable "controle" lists a set of parameters.
The first three parameters are always:
* 1 : im (physical points)
* 2 : jm (nb of layers)
* 3 : lllm

Then there is either for the generic/mars/pluto model:
* 4 : day_ref
or for earth/titan:
* 4 : day_ini
* 5 : annee_ref

Then idecal is set to 4 in the generic/mars/pluto model and 5 for earth/titan.

The list follows as such:
* idecal+1 : rad (planet radius)
* idecal+2 : omeg (angular speed)
* idecal+3 : g (surface gravity)
* idecal+4 : cpp (heat capacity at constant pressure)
* idecal+5 : rcp (R/cp of the dry gas, used to compute R and mu from cpp)
* idecal+6 : daysec (seconds in a day)
* idecal+7 : dtvr (seconds in a dynamic step?)
* idecal+8 : etot0 (energie)
* idecal+9 : ptot0
* idecal+10 : ztot0 (enstrophie?)
* idecal+11 : stot0 (entropie?)
* idecal+12 : ang0
* idecal+13 : pa (transition pressure between sigma and p coordinates in hybrid coordinates. Used in computation of ap and bp)
* idecal+14 : preff (used in ap(l)+bp(l)*preff)
* idecal+15 : clon
* idecal+16 : clat
* idecal+17 : grossismx
* idecal+18 : grossismy

=== Other parameters ===
TODO: EXPLAIN SOME MAIN VARIABLES/DIMENSIONS

== startfi.nc File Contents ==
A dump of the header of a typical '''startfi.nc''' (obtained via '''ncdump -h startfi.nc''') will show contents of the likes of:
<pre>
netcdf startfi {
dimensions:
index = 100 ;
physical_points = 994 ;
subsurface_layers = 18 ;
nlayer_plus_1 = 16 ;
number_of_advected_fields = 3 ;
nlayer = 15 ;
variables:
float controle(index) ;
controle:title = "Control parameters" ;
float soildepth(subsurface_layers) ;
soildepth:title = "Soil mid-layer depth" ;
float longitude(physical_points) ;
longitude:title = "Longitudes of physics grid" ;
float latitude(physical_points) ;
latitude:title = "Latitudes of physics grid" ;
float area(physical_points) ;
area:title = "Mesh area" ;
float phisfi(physical_points) ;
phisfi:title = "Geopotential at the surface" ;
float albedodat(physical_points) ;
albedodat:title = "Albedo of bare ground" ;
float ZMEA(physical_points) ;
ZMEA:title = "Relief: mean relief" ;
float ZSTD(physical_points) ;
ZSTD:title = "Relief: standard deviation" ;
float ZSIG(physical_points) ;
ZSIG:title = "Relief: sigma parameter" ;
float ZGAM(physical_points) ;
ZGAM:title = "Relief: gamma parameter" ;
float ZTHE(physical_points) ;
ZTHE:title = "Relief: theta parameter" ;
float inertiedat(subsurface_layers, physical_points) ;
inertiedat:title = "Soil thermal inertia" ;
float tsurf(physical_points) ;
tsurf:title = "Surface temperature" ;
float tsoil(subsurface_layers, physical_points) ;
tsoil:title = "Soil temperature" ;
float emis(physical_points) ;
emis:title = "Surface emissivity" ;
float q2(nlayer_plus_1, physical_points) ;
q2:title = "pbl wind variance" ;
float cloudfrac(nlayer, physical_points) ;
cloudfrac:title = "Cloud fraction" ;
float totcloudfrac(physical_points) ;
totcloudfrac:title = "Total fraction" ;
float hice(physical_points) ;
hice:title = "Height of oceanic ice" ;
float co2_ice(physical_points) ;
co2_ice:title = "tracer on surface" ;
float h2o_ice(physical_points) ;
h2o_ice:title = "tracer on surface" ;
float h2o_vap(physical_points) ;
h2o_vap:title = "tracer on surface" ;

// global attributes:
:title = "Physics start file" ;
}
</pre>

TODO: EXPLAIN SOME MAIN VARIABLES/DIMENSIONS/GRID STRUCTURE

[[Category:Inputs]]
[[Category:WhatIs]]
[[Category:Generic-LMDZ]]

Advanced Use of the GCM

2023-12-20T10:37:04Z

Jleconte:

== Running in parallel ==

For large simulation (long run, high resolution etc...), the computational cost can be huge and hence the run time very long.
To overcome this issue, the model can be run in parallel. This however requires a few extra steps (compared to compiling and running the serial version of the code).
For all the details see [[Parallelism | the dedicated page]].

== Disambiguation between ifort, mpif90, etc. ==

For users not used to compilers and/or compiling and running codes in parallel, namely in MPI mode, there is often some confusion which hopefully the following paragraph might help clarify:
* the compiler (typically gfortran, ifort, pgfortran, etc.) is the required tool to compile the Fortran source code and generate an executable. It is strongly recommended that libraries used by a program are also compiled using the same compiler. Thus if you plan to use different compilers to compile the model, note that you should also have at hand versions of the libraries it uses also compiled with these compilers.
* the MPI (Message Passing Interface) library is a library used to solve problems using multiple processes by enabling message-passing between the otherwise independent processes. There are a number of available MPI libraries out there, e.g. OpenMPI, MPICH or IntelMPI to name a few (you can check out the [[Building an MPI library]] page for some information about installing an MPI library). The important point here is that on a given machine the MPI library is related to a given compiler and that it provides related wrappers to compile and run with. Typically (but not always) the compiler wrapper is '''mpif90''' and the execution wrapper is '''mpirun'''. If you want to know which compiler is wrapped in the '''mpif90''' compiler wrapper, check out the output of:
<pre>
mpif90 --version
</pre>
* In addition a second type of parallelism, shared memory parallelism known as OpenMP, is also implemented in the code. In contradistinction to MPI, OpenMP does not require an external library but is instead implemented as a compiler feature. At run time one must then specify some dedicated environment variables (such as OMP_NUM_THREADS and OMP_STACKSIZE) to specify the number of threads to use per process.
* In practice one should favor compiling and running with both MPI and OPenMP enabled.
* For much more detailed information about compiling and running in parallel, check out the [[Parallelism | the page dedicated to Parallelism]].

== A word about the IOIPSL and XIOS libraries ==
* The IOIPSL (Input Output IPSL) library is a library that has developed by the IPSL community to handle input and outputs of (mostly terrestrial) climate models. For the Generic PCM only a small part of this library is actually used, related to reading and processing the input [[The_run.def_Input_File | run.def]] file. For more details check out the [[The IOIPSL Library]] page.
* 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 in a parallel environment is alleviated. All aspects of the outputs (name, units, file, post-processing operations, etc.) are then controlled by dedicated XML files which are read at run-time. Using XIOS is currently optional (and requires compiling the GCM with the XIOS library). More about the XIOS library, how to install and use it, etc. [[The XIOS Library| here]].

== Playing with the output files ==

=== Changing the output temporal resolution and time duration ===

* To change the total time of a simulation, you need to open the 'For all the details see [[The_run.def_Input_File | run.def]]. file and change the variable 'nday':

<pre>
nday = 1000 # this means the simulation will run for 1000 days ; and that the associated output files will also be computed for a total duration of 1000 days
</pre>

Note: in the example, they are not necessarily 1000 Earth days, because it depends on the definition of the day duration that has been taken in the start files.

* To change the temporal resolution of the output files, you need to open the [[The_run.def_Input_File | run.def]] file and change the variable 'ecritphy':

<pre>
ecritphy = 200 # this means the simulation will write variables in the output files every 200 time steps of the simulation.
</pre>

Note: The output temporal resolution of the output files then depends also on the number of timestep per day ('day_step' variable in [[The_run.def_Input_File | run.def]] file). In this example:

<pre>
nday = 1000
daystep = 800
ecritphy = 200
</pre>

The output file will provide results every 0.25 days (800/200), and for a total duration of 1000 days (so 4000 time values in total).

=== Changing the output variable ===

To select the variable provided in the output file diagfi.nc, you simply need to add the list of variables needed in the [[The_diagfi.def_Input_File | diagfi.def]].

Note for experts: Some technical variables need to be de-commented in 'physiq_mod.F90' file to be written in the output files.

=== Spectral outputs ===

It is possible to provide spectral outputs such as the OLR (Outgoing Longwave Radiation, i.e. the thermal emission of the planet at the top of the atmosphere), the OSR (Outgoing Stellar Radiation, i.e. the light reflected by the planet at the top of the atmosphere), or the GSR (Ground Stellar Radiation, i.e. the light emitted by the star that reaches the surface of the planet).

For this, you need to activate the option 'specOLR' in the [[The_callphys.def_Input_File | callphys.def]] file, as follows:

<pre>
specOLR = .true.
</pre>

The simulations will then create diagspec_VI.nc and diagspec_IR.nc files (along with the standard diagfi.nc file), which contain the spectra of OLR, OSR, GSR, etc.

Note: The resolution of the spectra is defined by that of the correlated-k (opacity) files used for the simulation.

=== Statistical outputs ===

TBD (explain how to compute stats.nc files as well as what is inside)

== How to Change Vertical and Horizontal Resolutions ==

=== When you are using the regular longitude/latitude horizontal grid ===
To run at a different grid resolution than available initial conditions files, one needs to use the tools ''newstart.e'' and ''start2archive.e''

For example, to create initial states at grid resolution 32×24×25 from NetCDF files start and startfi at grid resolution 64×48×32 :

* Create file ''start_archive.nc'' with ''start2archive.e'' compiled at grid resolution 64×48×32 using old file ''z2sig.def'' used previously
* Create files ''restart.nc'' and ''restartfi.nc'' with ''newstart.e'' compiled at grid resolution 32×24×25, using a new file ''z2sig.def'' (more details below on the choice of the ''z2sig.def'').
* While executing ''newstart.e'', you need to choose the answer '0 - from a file start_archive' and then press enter to all other requests.

==== What you need to ''know'' about the ''z2sig.def'' file ====

For a model with Nlay layers, the [[The_z2sig.def_Input_File | z2sig.def]] file must contain at least Nlay+1 lines (the other not being read).

The first line is a scale height ($$H$$). The following lines are the target pseudo-altitudes for the model from the bottom up ($$z_i$$).
The units do not matter as long as you use the same ones for both.

The model will use these altitudes to compute a target pressure grid ($$p_i$$ ) as follows:
\begin{align}
\label{def:pseudoalt}
p_i &= p_s \exp(-z_i/H),
\end{align}
where $$p_s$$ is the surface pressure.

As you can see, the scale height and pseudo altitudes enter the equation only through their ratio. So they do not have to to be the real scale-height and altitudes of the atmosphere you are simulating.
So you can use the same [[The_z2sig.def_Input_File | z2sig.def]].def for different planets.

There is no hard rule to follow to determine the altitude/pressure levels you should use. As a rule of thumb, layers should be thiner near the surface to properly resolve the surface boundary layer. Then they should gradually increase in size over a couple scale heights and transition to constant thickness above that. Of course, some specific applications may require thinner layers in some specific parts of the atmospheres.

A little trick for those who prefer to think in terms of (log)pressure: if you use $$H= 1/\ln 10 \approx 0.43429448$$, then $$z_i=x$$ corresponds to a pressure difference with the surface of exactly x pressure decades (i.e. at $$z=1$$, $$p=0.1p_s$$). This is particularly useful for giant-planet applications.



'''WE SHOULD WRITE A PAGE (LINK HERE) ABOUT HYBRID VERTICAL COORDINATES'''

=== When you are using the DYNAMICO icosahedral horizontal grid ===

The horizontal resolution for the DYNAMICO dynamical core is managed from several setting files, online during the execution.
To this purpose, each part of the GCM managing the in/output fields ('''ICOSAGCM''', '''ICOSA_LMDZ''', '''XIOS''') requires to know the input and output grids:

'''1. ''context_lmdz_physics.xml'':'''

You can find several grid setup already defined:

<syntaxhighlight lang="xml" line>
<domain_definition>
<domain id="dom_96_95" ni_glo="96" nj_glo="95" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_144_142" ni_glo="144" nj_glo="142" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_512_360" ni_glo="512" nj_glo="360" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_720_360" ni_glo="720" nj_glo="360" type="rectilinear">
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_out" domain_ref="dom_720_360"/>
</domain_definition>
</syntaxhighlight>

In this example, the output grid for the physics fields is defined by

<syntaxhighlight lang="xml">
<domain id="dom_out" domain_ref="dom_720_360"/>
</syntaxhighlight>

which is an half-degree horizontal resolution. To change this resolution, you have to change name of the '''domain_ref''' grid, for instance:

<syntaxhighlight lang="xml">
<domain id="dom_out" domain_ref="dom_96_95"/>
</syntaxhighlight>

'''2. ''run_icosa.def'': setting file to execute a simulation'''

In this file, regarding of the horizontal resolution intended, you have to set the number of subdivision on the main triangle.
For reminder, each hexagonal mesh is divided in several main triangles and each main triangles are divided in suitable number of sub-triangles according the horizontal resolution

<syntaxhighlight lang="bash" line>
#nbp --> number of subdivision on a main triangle: integer (default=40)
# nbp = sqrt((nbr_lat x nbr_lon)/10)
# nbp: 20 40 80 160
# T-edge length (km): 500 250 120 60
# Example: nbp(128x96) = 35 -> 40
# nbp(256x192)= 70 -> 80
# nbp(360x720)= 160 -> 160
nbp = 160
</syntaxhighlight>

If you have chosen the 96_95 output grid in ''context_lmdz_physics.xml'', you have to calculate $$nbp = \sqrt(96x95) / 10 = 10$$ and in this case

<syntaxhighlight lang="bash">
nbp = 20
</syntaxhighlight>

After the number of subdivision of the main triangle, you have to define the number subdivision over each direction. At this stage you need to be careful as the number of subdivisions on each direction:
* needs to be set according to the number of subdivisions on the main triangle '''nbp'''
* will determine the number of processors on which the GCM will be most effective

<syntaxhighlight lang="bash" line>
## sub splitting of main rhombus : integer (default=1)
#nsplit_i=1
#nsplit_j=1
#omp_level_size=1
###############################################################
## There must be less MPIxOpenMP processes than the 10 x nsplit_i x nsplit_j tiles
## typically for pure MPI runs, let nproc = 10 x nsplit_i x nsplit_j
## it is better to have nbp/nsplit_i > 10 and nbp/nplit_j > 10
###############################################################
#### 40 noeuds de 24 processeurs = 960 procs
nsplit_i=12
nsplit_j=8

#### 50 noeuds de 24 processeurs = 1200 procs
#nsplit_i=10
#nsplit_j=12
</syntaxhighlight>

With the same example as above, the 96_95 output grid requires:
$$nsplit_i < 2$$ and $$nsplit_j < 2$$
We advise you to select:

<syntaxhighlight lang="bash">
## sub splitting of main rhombus : integer (default=1)
nsplit_i=1
nsplit_j=1
</syntaxhighlight>

and using 10 processors.

== How to Change the Topography (or remove it) ==

The generic model can use in principle any type of surface topography, provided that the topographic data file is available in the right format, and put in the right place. The information content on the surface topography is contained in the ''startfi.nc'', and we do have developed tools (see below) to modify the ''startfi.nc'' to account for a new surface topography.

To change the surface topography of a simulation, we recommend to follow the procedure detailed below:

* Create file ''start_archive.nc'' with ''start2archive.e'' compiled at the same (horizontal and vertical) resolution than the ''start.nc'' and ''startfi.nc'' files.
* Create files ''restart.nc'' and ''restartfi.nc'' with ''newstart.e'' compiled again at the same (horizontal and vertical) resolution.
* While executing ''newstart.e'', you need to choose the answer '0 - from a file start_archive' and then press enter to all other requests.
* At some point, the script ''newstart.e'' asks you to chose the surface topography you want from the list of files available in your 'datagcm/surface_data/' directory.

We do have a repository of for Venus, Earth and Mars through time available at https://web.lmd.jussieu.fr/~lmdz/planets/LMDZ.GENERIC/datagcm/surface_data/. You can download the surface topography files and place them in your 'datagcm/surface_data/' directory.

We also offer a tutorial to design new topography maps here: https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/Building_Surface_Topography_Files

----

Special note: To remove the topography, you can simply add the following tag in callphys.def:

<pre>
nosurf = .true.
</pre>

== How to Change the Stellar Spectrum ==

To simulate the effect of the star's radiation on a given planetary atmosphere, it is necessary to accurately represent the stellar spectrum (spectral shape and total bolometric flux) at the top of this atmosphere. In the model, we have set up two different options to model the stellar spectra of any star.

=== Black Body Stellar Spectra ===

First, it is possible to simply use a black body. In this case, the stellar spectrum depends only on the effective temperature of the star which is provided to the model.

For this, you need to activate the option 'stelbbody' in the [[The_callphys.def_Input_File | callphys.def]] file, as follows:

<pre>
stelbbody = .true.
</pre>

and then add, also in the [[The_callphys.def_Input_File | callphys.def]] file, the following line:

<pre>
stelTbb = 3500.0
</pre>

to specify the effective temperature of the host star. (in this example, we have chosen a M-star with an effective temperature of 3500K)

=== Pre-Tabulated spectra ===

Second, the model can read a file containing any pre-computed stellar spectrum. Traditionally, we have used synthetic spectra from the PHOENIX database, that we adapt to the Generic PCM by decreasing the spectral resolution (use 10000 points with a fixed spectral resolution of 0.001 micron) and by adapting the units (in W/m2/micron). This is the option that is generally preferred to better represent the effect of the star (whose real spectrum can strongly deviate from the black body approximation).

For this, you need to make sure the option 'stelbbody' in the [[The_callphys.def_Input_File | callphys.def]] file is equal to .false. (it not specified, by default stelbbody is assumed to be .false.).

Then you need to add in the [[The_callphys.def_Input_File | callphys.def]] file, the following line:

<pre>
startype = 1
</pre>

and change the value of startype depending on the star you want to model. (here 1 means we use the solar spectrum)

To know which stellar spectra are available, you need to open the file LMDZ.GENERIC/libf/phystd/ave_stelspec.F90 and adapt the value of startype accordingly. You also need to make sure the spectra are available in your /datadir/stellar_spectra (or /datagcm/stellar_spectra) directory.

To calculate the true stellar spectrum at the top of the atmosphere, the Generic PCM renormalizes the stellar spectrum by the bolometric flux at 1 Astronomical Unit (AU) provided by the user, which it then converts into the true stellar spectrum by using the star-planet distance.

To specify the flux at 1 AU, you need to add in the [[The_callphys.def_Input_File | callphys.def]] file, the following line:

<pre>
Fat1AU = 1366.0
</pre>

(here 1366W/m2 corresponds to the flux at 1AU for the Sun)

1st NOTE: We will improve this second part (Martin and Mathilde) by the end of 2022.

2nd NOTE: The Generic PCM eventually has the capability to run without any stellar flux. To do that, you can simply put Fat1AU = 0. (@LUCAS_TEINTURIER, could you check that?)

== How to Change the Opacity Tables ==

To change the opacity tables (generated "offline" for a given set of pressures, temperatures, a given composition and a specific spectral decomposition), follow these steps:

* copy your directory containing your opacity tables in .... It has to contain... [[Building_Opacity_Tables | you need to build opacity tables]]
* change corrkdir = ... in [[The_callphys.def_Input_File | callphys.def]] with the name of that directory.
* change gases.def: it has to be consistent with Q.dat. A special case concerns...
* change -b option when compiling the model with makelmdz_fcm: it has to correspond to the number of bands (in the IR x in the visible) of the new opacity tables. For instance, compile with -b 38x26 if you used 38 bands in the infrared and 26 in the visible to generate the opacity tables.

== How to Manage Tracers ==

Tracers are managed thanks to the [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_traceur.def_Input_File ''traceur.def''] file.

Specific treatment of some tracers (e.g., water vapor cycle) can be added directly in the model and an option added in [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_callphys.def_Input_File ''callphys.def''] file.

== Use the Z of LMDZ : Zoomed version ==

Do we need this? Has anyone already made use of the zoom module?

[[Category:Generic-Model]]

Advanced Use of the GCM

2023-12-20T10:36:13Z

Jleconte:

== Running in parallel ==

For large simulation (long run, high resolution etc...), the computational cost can be huge and hence the run time very long.
To overcome this issue, the model can be run in parallel. This however requires a few extra steps (compared to compiling and running the serial version of the code).
For all the details see [[Parallelism | the dedicated page]].

== Disambiguation between ifort, mpif90, etc. ==

For users not used to compilers and/or compiling and running codes in parallel, namely in MPI mode, there is often some confusion which hopefully the following paragraph might help clarify:
* the compiler (typically gfortran, ifort, pgfortran, etc.) is the required tool to compile the Fortran source code and generate an executable. It is strongly recommended that libraries used by a program are also compiled using the same compiler. Thus if you plan to use different compilers to compile the model, note that you should also have at hand versions of the libraries it uses also compiled with these compilers.
* the MPI (Message Passing Interface) library is a library used to solve problems using multiple processes by enabling message-passing between the otherwise independent processes. There are a number of available MPI libraries out there, e.g. OpenMPI, MPICH or IntelMPI to name a few (you can check out the [[Building an MPI library]] page for some information about installing an MPI library). The important point here is that on a given machine the MPI library is related to a given compiler and that it provides related wrappers to compile and run with. Typically (but not always) the compiler wrapper is '''mpif90''' and the execution wrapper is '''mpirun'''. If you want to know which compiler is wrapped in the '''mpif90''' compiler wrapper, check out the output of:
<pre>
mpif90 --version
</pre>
* In addition a second type of parallelism, shared memory parallelism known as OpenMP, is also implemented in the code. In contradistinction to MPI, OpenMP does not require an external library but is instead implemented as a compiler feature. At run time one must then specify some dedicated environment variables (such as OMP_NUM_THREADS and OMP_STACKSIZE) to specify the number of threads to use per process.
* In practice one should favor compiling and running with both MPI and OPenMP enabled.
* For much more detailed information about compiling and running in parallel, check out the [[Parallelism | the page dedicated to Parallelism]].

== A word about the IOIPSL and XIOS libraries ==
* The IOIPSL (Input Output IPSL) library is a library that has developed by the IPSL community to handle input and outputs of (mostly terrestrial) climate models. For the Generic PCM only a small part of this library is actually used, related to reading and processing the input [[The_run.def_Input_File | run.def]] file. For more details check out the [[The IOIPSL Library]] page.
* 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 in a parallel environment is alleviated. All aspects of the outputs (name, units, file, post-processing operations, etc.) are then controlled by dedicated XML files which are read at run-time. Using XIOS is currently optional (and requires compiling the GCM with the XIOS library). More about the XIOS library, how to install and use it, etc. [[The XIOS Library| here]].

== Playing with the output files ==

=== Changing the output temporal resolution and time duration ===

* To change the total time of a simulation, you need to open the 'For all the details see [[The_run.def_Input_File | run.def]]. file and change the variable 'nday':

<pre>
nday = 1000 # this means the simulation will run for 1000 days ; and that the associated output files will also be computed for a total duration of 1000 days
</pre>

Note: in the example, they are not necessarily 1000 Earth days, because it depends on the definition of the day duration that has been taken in the start files.

* To change the temporal resolution of the output files, you need to open the [[The_run.def_Input_File | run.def]] file and change the variable 'ecritphy':

<pre>
ecritphy = 200 # this means the simulation will write variables in the output files every 200 time steps of the simulation.
</pre>

Note: The output temporal resolution of the output files then depends also on the number of timestep per day ('day_step' variable in [[The_run.def_Input_File | run.def]] file). In this example:

<pre>
nday = 1000
daystep = 800
ecritphy = 200
</pre>

The output file will provide results every 0.25 days (800/200), and for a total duration of 1000 days (so 4000 time values in total).

=== Changing the output variable ===

To select the variable provided in the output file diagfi.nc, you simply need to add the list of variables needed in the [[The_diagfi.def_Input_File | diagfi.def]].

Note for experts: Some technical variables need to be de-commented in 'physiq_mod.F90' file to be written in the output files.

=== Spectral outputs ===

It is possible to provide spectral outputs such as the OLR (Outgoing Longwave Radiation, i.e. the thermal emission of the planet at the top of the atmosphere), the OSR (Outgoing Stellar Radiation, i.e. the light reflected by the planet at the top of the atmosphere), or the GSR (Ground Stellar Radiation, i.e. the light emitted by the star that reaches the surface of the planet).

For this, you need to activate the option 'specOLR' in the [[The_callphys.def_Input_File | callphys.def]] file, as follows:

<pre>
specOLR = .true.
</pre>

The simulations will then create diagspec_VI.nc and diagspec_IR.nc files (along with the standard diagfi.nc file), which contain the spectra of OLR, OSR, GSR, etc.

Note: The resolution of the spectra is defined by that of the correlated-k (opacity) files used for the simulation.

=== Statistical outputs ===

TBD (explain how to compute stats.nc files as well as what is inside)

== How to Change Vertical and Horizontal Resolutions ==

=== When you are using the regular longitude/latitude horizontal grid ===
To run at a different grid resolution than available initial conditions files, one needs to use the tools ''newstart.e'' and ''start2archive.e''

For example, to create initial states at grid resolution 32×24×25 from NetCDF files start and startfi at grid resolution 64×48×32 :

* Create file ''start_archive.nc'' with ''start2archive.e'' compiled at grid resolution 64×48×32 using old file ''z2sig.def'' used previously
* Create files ''restart.nc'' and ''restartfi.nc'' with ''newstart.e'' compiled at grid resolution 32×24×25, using a new file ''z2sig.def'' (more details below on the choice of the ''z2sig.def'').
* While executing ''newstart.e'', you need to choose the answer '0 - from a file start_archive' and then press enter to all other requests.

==== What you need to ''know'' about the ''z2sig.def'' file ====

For a model with Nlay layers, the [[The_z2sig.def_Input_File | z2sig.def]] file must contain at least Nlay+1 lines (the other not being read).

The first line is a scale height ($$H$$). The following lines are the target pseudo-altitudes for the model from the bottom up ($$z_i$$).
The units do not matter as long as you use the same ones for both.

The model will use these altitudes to compute a target pressure grid ($$p_i$$ ) as follows:
\begin{align}
\label{def:pseudoalt}
p_i &= p_s \exp(-z_i/H),
\end{align}
where $$p_s$$ is the surface pressure.

As you can see, the scale height and pseudo altitudes enter the equation only through their ratio. So they do not have to to be the real scale-height and altitudes of the atmosphere you are simulating.
So you can use the same [[The_z2sig.def_Input_File | z2sig.def]].def for different planets.

There is no hard rule to follow to determine the altitude/pressure levels you should use. As a rule of thumb, layers should be thiner near the surface to properly resolve the surface boundary layer. Then they should gradually increase in size over a couple scale heights and transition to constant thickness above that. Of course, some specific applications may require thinner layers in some specific parts of the atmospheres.

A little trick for those who prefer to think in terms of (log)pressure: if you use $$H= 1/\ln 10 \approx 0.43429448$$, then $$z_i=x$$ corresponds to a pressure difference with the surface of exactly x pressure decades (i.e. at $$z=1$$, $$p=0.1p_s$$. This is particularly useful for giant-planet applications.



'''WE SHOULD WRITE A PAGE (LINK HERE) ABOUT HYBRID VERTICAL COORDINATES'''

=== When you are using the DYNAMICO icosahedral horizontal grid ===

The horizontal resolution for the DYNAMICO dynamical core is managed from several setting files, online during the execution.
To this purpose, each part of the GCM managing the in/output fields ('''ICOSAGCM''', '''ICOSA_LMDZ''', '''XIOS''') requires to know the input and output grids:

'''1. ''context_lmdz_physics.xml'':'''

You can find several grid setup already defined:

<syntaxhighlight lang="xml" line>
<domain_definition>
<domain id="dom_96_95" ni_glo="96" nj_glo="95" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_144_142" ni_glo="144" nj_glo="142" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_512_360" ni_glo="512" nj_glo="360" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_720_360" ni_glo="720" nj_glo="360" type="rectilinear">
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_out" domain_ref="dom_720_360"/>
</domain_definition>
</syntaxhighlight>

In this example, the output grid for the physics fields is defined by

<syntaxhighlight lang="xml">
<domain id="dom_out" domain_ref="dom_720_360"/>
</syntaxhighlight>

which is an half-degree horizontal resolution. To change this resolution, you have to change name of the '''domain_ref''' grid, for instance:

<syntaxhighlight lang="xml">
<domain id="dom_out" domain_ref="dom_96_95"/>
</syntaxhighlight>

'''2. ''run_icosa.def'': setting file to execute a simulation'''

In this file, regarding of the horizontal resolution intended, you have to set the number of subdivision on the main triangle.
For reminder, each hexagonal mesh is divided in several main triangles and each main triangles are divided in suitable number of sub-triangles according the horizontal resolution

<syntaxhighlight lang="bash" line>
#nbp --> number of subdivision on a main triangle: integer (default=40)
# nbp = sqrt((nbr_lat x nbr_lon)/10)
# nbp: 20 40 80 160
# T-edge length (km): 500 250 120 60
# Example: nbp(128x96) = 35 -> 40
# nbp(256x192)= 70 -> 80
# nbp(360x720)= 160 -> 160
nbp = 160
</syntaxhighlight>

If you have chosen the 96_95 output grid in ''context_lmdz_physics.xml'', you have to calculate $$nbp = \sqrt(96x95) / 10 = 10$$ and in this case

<syntaxhighlight lang="bash">
nbp = 20
</syntaxhighlight>

After the number of subdivision of the main triangle, you have to define the number subdivision over each direction. At this stage you need to be careful as the number of subdivisions on each direction:
* needs to be set according to the number of subdivisions on the main triangle '''nbp'''
* will determine the number of processors on which the GCM will be most effective

<syntaxhighlight lang="bash" line>
## sub splitting of main rhombus : integer (default=1)
#nsplit_i=1
#nsplit_j=1
#omp_level_size=1
###############################################################
## There must be less MPIxOpenMP processes than the 10 x nsplit_i x nsplit_j tiles
## typically for pure MPI runs, let nproc = 10 x nsplit_i x nsplit_j
## it is better to have nbp/nsplit_i > 10 and nbp/nplit_j > 10
###############################################################
#### 40 noeuds de 24 processeurs = 960 procs
nsplit_i=12
nsplit_j=8

#### 50 noeuds de 24 processeurs = 1200 procs
#nsplit_i=10
#nsplit_j=12
</syntaxhighlight>

With the same example as above, the 96_95 output grid requires:
$$nsplit_i < 2$$ and $$nsplit_j < 2$$
We advise you to select:

<syntaxhighlight lang="bash">
## sub splitting of main rhombus : integer (default=1)
nsplit_i=1
nsplit_j=1
</syntaxhighlight>

and using 10 processors.

== How to Change the Topography (or remove it) ==

The generic model can use in principle any type of surface topography, provided that the topographic data file is available in the right format, and put in the right place. The information content on the surface topography is contained in the ''startfi.nc'', and we do have developed tools (see below) to modify the ''startfi.nc'' to account for a new surface topography.

To change the surface topography of a simulation, we recommend to follow the procedure detailed below:

* Create file ''start_archive.nc'' with ''start2archive.e'' compiled at the same (horizontal and vertical) resolution than the ''start.nc'' and ''startfi.nc'' files.
* Create files ''restart.nc'' and ''restartfi.nc'' with ''newstart.e'' compiled again at the same (horizontal and vertical) resolution.
* While executing ''newstart.e'', you need to choose the answer '0 - from a file start_archive' and then press enter to all other requests.
* At some point, the script ''newstart.e'' asks you to chose the surface topography you want from the list of files available in your 'datagcm/surface_data/' directory.

We do have a repository of for Venus, Earth and Mars through time available at https://web.lmd.jussieu.fr/~lmdz/planets/LMDZ.GENERIC/datagcm/surface_data/. You can download the surface topography files and place them in your 'datagcm/surface_data/' directory.

We also offer a tutorial to design new topography maps here: https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/Building_Surface_Topography_Files

----

Special note: To remove the topography, you can simply add the following tag in callphys.def:

<pre>
nosurf = .true.
</pre>

== How to Change the Stellar Spectrum ==

To simulate the effect of the star's radiation on a given planetary atmosphere, it is necessary to accurately represent the stellar spectrum (spectral shape and total bolometric flux) at the top of this atmosphere. In the model, we have set up two different options to model the stellar spectra of any star.

=== Black Body Stellar Spectra ===

First, it is possible to simply use a black body. In this case, the stellar spectrum depends only on the effective temperature of the star which is provided to the model.

For this, you need to activate the option 'stelbbody' in the [[The_callphys.def_Input_File | callphys.def]] file, as follows:

<pre>
stelbbody = .true.
</pre>

and then add, also in the [[The_callphys.def_Input_File | callphys.def]] file, the following line:

<pre>
stelTbb = 3500.0
</pre>

to specify the effective temperature of the host star. (in this example, we have chosen a M-star with an effective temperature of 3500K)

=== Pre-Tabulated spectra ===

Second, the model can read a file containing any pre-computed stellar spectrum. Traditionally, we have used synthetic spectra from the PHOENIX database, that we adapt to the Generic PCM by decreasing the spectral resolution (use 10000 points with a fixed spectral resolution of 0.001 micron) and by adapting the units (in W/m2/micron). This is the option that is generally preferred to better represent the effect of the star (whose real spectrum can strongly deviate from the black body approximation).

For this, you need to make sure the option 'stelbbody' in the [[The_callphys.def_Input_File | callphys.def]] file is equal to .false. (it not specified, by default stelbbody is assumed to be .false.).

Then you need to add in the [[The_callphys.def_Input_File | callphys.def]] file, the following line:

<pre>
startype = 1
</pre>

and change the value of startype depending on the star you want to model. (here 1 means we use the solar spectrum)

To know which stellar spectra are available, you need to open the file LMDZ.GENERIC/libf/phystd/ave_stelspec.F90 and adapt the value of startype accordingly. You also need to make sure the spectra are available in your /datadir/stellar_spectra (or /datagcm/stellar_spectra) directory.

To calculate the true stellar spectrum at the top of the atmosphere, the Generic PCM renormalizes the stellar spectrum by the bolometric flux at 1 Astronomical Unit (AU) provided by the user, which it then converts into the true stellar spectrum by using the star-planet distance.

To specify the flux at 1 AU, you need to add in the [[The_callphys.def_Input_File | callphys.def]] file, the following line:

<pre>
Fat1AU = 1366.0
</pre>

(here 1366W/m2 corresponds to the flux at 1AU for the Sun)

1st NOTE: We will improve this second part (Martin and Mathilde) by the end of 2022.

2nd NOTE: The Generic PCM eventually has the capability to run without any stellar flux. To do that, you can simply put Fat1AU = 0. (@LUCAS_TEINTURIER, could you check that?)

== How to Change the Opacity Tables ==

To change the opacity tables (generated "offline" for a given set of pressures, temperatures, a given composition and a specific spectral decomposition), follow these steps:

* copy your directory containing your opacity tables in .... It has to contain... [[Building_Opacity_Tables | you need to build opacity tables]]
* change corrkdir = ... in [[The_callphys.def_Input_File | callphys.def]] with the name of that directory.
* change gases.def: it has to be consistent with Q.dat. A special case concerns...
* change -b option when compiling the model with makelmdz_fcm: it has to correspond to the number of bands (in the IR x in the visible) of the new opacity tables. For instance, compile with -b 38x26 if you used 38 bands in the infrared and 26 in the visible to generate the opacity tables.

== How to Manage Tracers ==

Tracers are managed thanks to the [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_traceur.def_Input_File ''traceur.def''] file.

Specific treatment of some tracers (e.g., water vapor cycle) can be added directly in the model and an option added in [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_callphys.def_Input_File ''callphys.def''] file.

== Use the Z of LMDZ : Zoomed version ==

Do we need this? Has anyone already made use of the zoom module?

[[Category:Generic-Model]]

Overview of the Generic PCM

2022-09-01T07:31:58Z

Jleconte: /* Our team of developers (by alphabetical order) */

== What is a GCM ==

A Global Climate Model (GCM) like the Generic PCM calculates the temporal evolution of the different variables (temperature, pressure, mass, mixing ratio of tracers/gas/clouds, winds, etc.) that control or describe the planetary meteorology and climate at different points of a 3D “grid” that covers the entire atmosphere.

To do that, the model solves 3D hydrodynamic equations that describe how atmospheric winds are created by various physical forcings (radiative heating/cooling, etc.) and how these winds transport and redistribute the various atmospheric fields (temperature, tracers, etc.). However, it can be shown that to a good level of approximation, the various forcings can be computed using only local conditions in a column of atmosphere, whereas long-range couplings between various points of the planet are mediated through atmospheric transport.

[[File:Didi-eps-converted-to-1.png|thumb|Physics / Dynamics interface]]

For these reasons, the 3D model is split in two components:

* '''a 3D dynamical core''' abble to integrate in time the general equations for atmospheric circulation when the various local forcings are known. This component (including source code) is common to all terrestrial-type atmospheres, and applicable in certain cases to the upper atmospheres of gas giant planets.
* '''a physical package''' that is specific to the planet in question (as it takes into account dedicated parametrizations representative of ongoing physical processes) and which computes atmospheric processes in each atmospheric column (which are sub-grid-scale from the point of view of the dynamical core).

In practice, we have several '''dynamical cores''' available with the model: LMDZ (global longitude/latitude grid), DYNAMICO (icosaedric grid), and WRF (rectangular box for local/regional studies)

From an initial state, the model calculates the temporal evolution of these variables, one timestep after another:
* At instant t, variables Xt (temperature for example) are known at every grid point of the atmosphere.
* The physical model calculates the local time derivatives of the various variables -- called the tendencies -- ((δX/δt)1, (δX/δt)2, etc.) due to each physical phenomenon: for example, heating due to absorption of solar radiation and infrared cooling, mixing due to turbulence in the planetary boundary layer, condensation/evaporation of water vapor, etc. These tendencies are calculated via parameterization of the processes involved that try to capture the physical behavior of the atmopshere at the subgrid scale.
* These tendencies are passed to the dynamical core that integrates the model forward in time to the next time step, t + δt, by solving the hydrodynamical equations.
* This new state can be used to recompute the tendencies for the next time step and so on.

== Philosophy of the Generic PCM ==

The accuracy and predictive power of any GCM is often dictated by the choice made for the physical phenomena that are included and for the way they are parametrized. To be accurate, many Earth-centric climate models use very complex parametrizations that are heavily tuned on Earth observations. Such parametrizations can, however, behave very poorly far from the parameter space where they have been validated, thus reducing their predictive power for exotic atmospheres.

As the goal of the Generic PCM is to model the climate of very different planets with the same model, a particular emphasis has been put on using simple parametrizations based as much as possible on ab-initio physical equations and conservation principles to avoid unphysical behaviors in extreme regimes.

== GCM inputs and outputs ==

[[File:Inout-eps-converted-to-1.png|thumb|input/output data]]

The input files are the files needed to initialize the model (state of the atmosphere at instant t0 as well as a dataset of boundary conditions). The output files are “historical files”, archives of the atmospheric flow history as simulated by the model: the “diagfi files”, the “stats files”, the daily averages, and so on. The "parameter files" are the files describing the physical parameters of the planet, as well as the physical parameterizations used in the model. The figure (on the right) shows the main architecture of the Generic PCM.

==== start and startfi files ====

GCM simulations needs a list of initial conditions/parameters to be run. This includes, for example, the initial temperature field, wind field, cloud field, position of water reservoirs on the surface, etc.

In the Generic PCM, initial conditions/parameters are stored in two files named "start.nc" and "startfi.nc". At each new run, the GCM reads these two files to set up the proper set of initial conditions.

==== start vs restart files ====

At the end of each GCM simulation, the Generic PCM produces several output files, and notably two files named "restart.nc" and "restartfi.nc".

These two files store all the final conditions of the model, which includes, for example, the initial temperature field, wind field, cloud field, position of water reservoirs on the surface, etc.

These "restart.nc" and "restartfi.nc" have the exact same architecture than the "start.nc" and "startfi.nc" files, and can thus be used as initial conditions for a new Generic PCM simulation.

==== parameter (.def) files ====

The parameter files (listed below) are files required by the Generic PCM to run.

List of needed .def files:
<ul>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_callphys.def_Input_File ''callphys.def'']: Physical parameters used in the simulation</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_run.def_Input_File ''run.def'']: Numerical parameters used in the simulation</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_gases.def_Input_File ''gases.def'']: List of gases in the simulations</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_traceur.def_Input_File ''traceur.def'']: Numerical tracers in the simulations</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_z2sig.def_Input_File ''z2sig.def'']: Pseudo-altitudes (in km) at which the user wants to set the vertical levels</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_diagfi.def_Input_File ''diagfi.def''] (optionnal): List of wanted outputs</li>
</ul>

==== input data ====

The Generic PCM requires several inputs in order to run. This includes, for instance:
* opacity tables
* aerosols optical properties
* stellar spectrum

These data can be modified/adapted by the users depending on the planet to be simulated.

==== output files ====

At the end of each GCM simulation, the Generic PCM produces several output files, and notably a file named "diagfi.nc". This file is an archive of the atmospheric/surface fields (temperatures, winds, clouds, etc.) along the GCM simulation. This is the file that contains most of the information needed to analyze/understand the content of a GCM simulation.

nb: The Generic PCM can also produce extra output files, such as the "diagspec.nc" files (that keep track of the spectral radiative fluxes in the GCM), the "stats.nc" (that keep track of statistical information along the GCM simulation), etc.

== Our team of developers (by alphabetical order) ==

'''Active contributors'''

*Deborah Bardet
*Benjamin Charnay (permanent, LESIA)
*Guillaume Chaverot
*François Forget (permanent, LMD)
*Gabriella Gilli
*Sandrine Guerlet (permanent, LMD)
*Yassin Jaziri
*Sébastien Lebonnois (permanent, LMD)
*Jeremy Leconte (permanent, LAB)
*Gwenael Milcareck
*Ehouarn Millour (permanent, LMD)
*Diogo Quirino
*Aymeric Spiga (permanent, LMD)
*Lucas Teinturier
*Martin Turbet (permanent, LMD)
*Romain Vandemeulebrouck

'''Past contributors and/or collaborators'''

*Tanguy Bertrand
*Alexandre Boissinot
*Emeline Bolmont
*Antony Delavois
*Thomas Dubos
*Vincent Eymet
*Frédéric Hourdin
*Franck Lefèvre
*Maxence Lefèvre
*Laura Kerber
*Franck Selsis
*Jan Vatant d'Olonne
*Margaux Vals
*Robin Wordsworth

Overview of the Generic PCM

2022-09-01T07:31:23Z

Jleconte: /* Our team of developers (by alphabetical order) */

== What is a GCM ==

A Global Climate Model (GCM) like the Generic PCM calculates the temporal evolution of the different variables (temperature, pressure, mass, mixing ratio of tracers/gas/clouds, winds, etc.) that control or describe the planetary meteorology and climate at different points of a 3D “grid” that covers the entire atmosphere.

To do that, the model solves 3D hydrodynamic equations that describe how atmospheric winds are created by various physical forcings (radiative heating/cooling, etc.) and how these winds transport and redistribute the various atmospheric fields (temperature, tracers, etc.). However, it can be shown that to a good level of approximation, the various forcings can be computed using only local conditions in a column of atmosphere, whereas long-range couplings between various points of the planet are mediated through atmospheric transport.

[[File:Didi-eps-converted-to-1.png|thumb|Physics / Dynamics interface]]

For these reasons, the 3D model is split in two components:

* '''a 3D dynamical core''' abble to integrate in time the general equations for atmospheric circulation when the various local forcings are known. This component (including source code) is common to all terrestrial-type atmospheres, and applicable in certain cases to the upper atmospheres of gas giant planets.
* '''a physical package''' that is specific to the planet in question (as it takes into account dedicated parametrizations representative of ongoing physical processes) and which computes atmospheric processes in each atmospheric column (which are sub-grid-scale from the point of view of the dynamical core).

In practice, we have several '''dynamical cores''' available with the model: LMDZ (global longitude/latitude grid), DYNAMICO (icosaedric grid), and WRF (rectangular box for local/regional studies)

From an initial state, the model calculates the temporal evolution of these variables, one timestep after another:
* At instant t, variables Xt (temperature for example) are known at every grid point of the atmosphere.
* The physical model calculates the local time derivatives of the various variables -- called the tendencies -- ((δX/δt)1, (δX/δt)2, etc.) due to each physical phenomenon: for example, heating due to absorption of solar radiation and infrared cooling, mixing due to turbulence in the planetary boundary layer, condensation/evaporation of water vapor, etc. These tendencies are calculated via parameterization of the processes involved that try to capture the physical behavior of the atmopshere at the subgrid scale.
* These tendencies are passed to the dynamical core that integrates the model forward in time to the next time step, t + δt, by solving the hydrodynamical equations.
* This new state can be used to recompute the tendencies for the next time step and so on.

== Philosophy of the Generic PCM ==

The accuracy and predictive power of any GCM is often dictated by the choice made for the physical phenomena that are included and for the way they are parametrized. To be accurate, many Earth-centric climate models use very complex parametrizations that are heavily tuned on Earth observations. Such parametrizations can, however, behave very poorly far from the parameter space where they have been validated, thus reducing their predictive power for exotic atmospheres.

As the goal of the Generic PCM is to model the climate of very different planets with the same model, a particular emphasis has been put on using simple parametrizations based as much as possible on ab-initio physical equations and conservation principles to avoid unphysical behaviors in extreme regimes.

== GCM inputs and outputs ==

[[File:Inout-eps-converted-to-1.png|thumb|input/output data]]

The input files are the files needed to initialize the model (state of the atmosphere at instant t0 as well as a dataset of boundary conditions). The output files are “historical files”, archives of the atmospheric flow history as simulated by the model: the “diagfi files”, the “stats files”, the daily averages, and so on. The "parameter files" are the files describing the physical parameters of the planet, as well as the physical parameterizations used in the model. The figure (on the right) shows the main architecture of the Generic PCM.

==== start and startfi files ====

GCM simulations needs a list of initial conditions/parameters to be run. This includes, for example, the initial temperature field, wind field, cloud field, position of water reservoirs on the surface, etc.

In the Generic PCM, initial conditions/parameters are stored in two files named "start.nc" and "startfi.nc". At each new run, the GCM reads these two files to set up the proper set of initial conditions.

==== start vs restart files ====

At the end of each GCM simulation, the Generic PCM produces several output files, and notably two files named "restart.nc" and "restartfi.nc".

These two files store all the final conditions of the model, which includes, for example, the initial temperature field, wind field, cloud field, position of water reservoirs on the surface, etc.

These "restart.nc" and "restartfi.nc" have the exact same architecture than the "start.nc" and "startfi.nc" files, and can thus be used as initial conditions for a new Generic PCM simulation.

==== parameter (.def) files ====

The parameter files (listed below) are files required by the Generic PCM to run.

List of needed .def files:
<ul>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_callphys.def_Input_File ''callphys.def'']: Physical parameters used in the simulation</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_run.def_Input_File ''run.def'']: Numerical parameters used in the simulation</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_gases.def_Input_File ''gases.def'']: List of gases in the simulations</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_traceur.def_Input_File ''traceur.def'']: Numerical tracers in the simulations</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_z2sig.def_Input_File ''z2sig.def'']: Pseudo-altitudes (in km) at which the user wants to set the vertical levels</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_diagfi.def_Input_File ''diagfi.def''] (optionnal): List of wanted outputs</li>
</ul>

==== input data ====

The Generic PCM requires several inputs in order to run. This includes, for instance:
* opacity tables
* aerosols optical properties
* stellar spectrum

These data can be modified/adapted by the users depending on the planet to be simulated.

==== output files ====

At the end of each GCM simulation, the Generic PCM produces several output files, and notably a file named "diagfi.nc". This file is an archive of the atmospheric/surface fields (temperatures, winds, clouds, etc.) along the GCM simulation. This is the file that contains most of the information needed to analyze/understand the content of a GCM simulation.

nb: The Generic PCM can also produce extra output files, such as the "diagspec.nc" files (that keep track of the spectral radiative fluxes in the GCM), the "stats.nc" (that keep track of statistical information along the GCM simulation), etc.

== Our team of developers (by alphabetical order) ==

'''Active contributors'''

*Deborah Bardet
*Benjamin Charnay (permanent, LESIA)
*Guillaume Chaverot
*François Forget (permanent, LMD)
*Gabriella Gilli
*Sandrine Guerlet (permanent, LMD)
*Yassin Jaziri
*Jeremy Leconte (permanent, LAB)
*Sébastien Lebonnois (permanent, LMD)
*Gwenael Milcareck
*Ehouarn Millour (permanent, LMD)
*Diogo Quirino
*Aymeric Spiga (permanent, LMD)
*Lucas Teinturier
*Martin Turbet (permanent, LMD)
*Romain Vandemeulebrouck

'''Past contributors and/or collaborators'''

*Tanguy Bertrand
*Alexandre Boissinot
*Emeline Bolmont
*Antony Delavois
*Thomas Dubos
*Vincent Eymet
*Frédéric Hourdin
*Franck Lefèvre
*Maxence Lefèvre
*Laura Kerber
*Franck Selsis
*Jan Vatant d'Olonne
*Margaux Vals
*Robin Wordsworth

Overview of the Generic PCM

2022-09-01T07:30:23Z

Jleconte:

== What is a GCM ==

A Global Climate Model (GCM) like the Generic PCM calculates the temporal evolution of the different variables (temperature, pressure, mass, mixing ratio of tracers/gas/clouds, winds, etc.) that control or describe the planetary meteorology and climate at different points of a 3D “grid” that covers the entire atmosphere.

To do that, the model solves 3D hydrodynamic equations that describe how atmospheric winds are created by various physical forcings (radiative heating/cooling, etc.) and how these winds transport and redistribute the various atmospheric fields (temperature, tracers, etc.). However, it can be shown that to a good level of approximation, the various forcings can be computed using only local conditions in a column of atmosphere, whereas long-range couplings between various points of the planet are mediated through atmospheric transport.

[[File:Didi-eps-converted-to-1.png|thumb|Physics / Dynamics interface]]

For these reasons, the 3D model is split in two components:

* '''a 3D dynamical core''' abble to integrate in time the general equations for atmospheric circulation when the various local forcings are known. This component (including source code) is common to all terrestrial-type atmospheres, and applicable in certain cases to the upper atmospheres of gas giant planets.
* '''a physical package''' that is specific to the planet in question (as it takes into account dedicated parametrizations representative of ongoing physical processes) and which computes atmospheric processes in each atmospheric column (which are sub-grid-scale from the point of view of the dynamical core).

In practice, we have several '''dynamical cores''' available with the model: LMDZ (global longitude/latitude grid), DYNAMICO (icosaedric grid), and WRF (rectangular box for local/regional studies)

From an initial state, the model calculates the temporal evolution of these variables, one timestep after another:
* At instant t, variables Xt (temperature for example) are known at every grid point of the atmosphere.
* The physical model calculates the local time derivatives of the various variables -- called the tendencies -- ((δX/δt)1, (δX/δt)2, etc.) due to each physical phenomenon: for example, heating due to absorption of solar radiation and infrared cooling, mixing due to turbulence in the planetary boundary layer, condensation/evaporation of water vapor, etc. These tendencies are calculated via parameterization of the processes involved that try to capture the physical behavior of the atmopshere at the subgrid scale.
* These tendencies are passed to the dynamical core that integrates the model forward in time to the next time step, t + δt, by solving the hydrodynamical equations.
* This new state can be used to recompute the tendencies for the next time step and so on.

== Philosophy of the Generic PCM ==

The accuracy and predictive power of any GCM is often dictated by the choice made for the physical phenomena that are included and for the way they are parametrized. To be accurate, many Earth-centric climate models use very complex parametrizations that are heavily tuned on Earth observations. Such parametrizations can, however, behave very poorly far from the parameter space where they have been validated, thus reducing their predictive power for exotic atmospheres.

As the goal of the Generic PCM is to model the climate of very different planets with the same model, a particular emphasis has been put on using simple parametrizations based as much as possible on ab-initio physical equations and conservation principles to avoid unphysical behaviors in extreme regimes.

== GCM inputs and outputs ==

[[File:Inout-eps-converted-to-1.png|thumb|input/output data]]

The input files are the files needed to initialize the model (state of the atmosphere at instant t0 as well as a dataset of boundary conditions). The output files are “historical files”, archives of the atmospheric flow history as simulated by the model: the “diagfi files”, the “stats files”, the daily averages, and so on. The "parameter files" are the files describing the physical parameters of the planet, as well as the physical parameterizations used in the model. The figure (on the right) shows the main architecture of the Generic PCM.

==== start and startfi files ====

GCM simulations needs a list of initial conditions/parameters to be run. This includes, for example, the initial temperature field, wind field, cloud field, position of water reservoirs on the surface, etc.

In the Generic PCM, initial conditions/parameters are stored in two files named "start.nc" and "startfi.nc". At each new run, the GCM reads these two files to set up the proper set of initial conditions.

==== start vs restart files ====

At the end of each GCM simulation, the Generic PCM produces several output files, and notably two files named "restart.nc" and "restartfi.nc".

These two files store all the final conditions of the model, which includes, for example, the initial temperature field, wind field, cloud field, position of water reservoirs on the surface, etc.

These "restart.nc" and "restartfi.nc" have the exact same architecture than the "start.nc" and "startfi.nc" files, and can thus be used as initial conditions for a new Generic PCM simulation.

==== parameter (.def) files ====

The parameter files (listed below) are files required by the Generic PCM to run.

List of needed .def files:
<ul>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_callphys.def_Input_File ''callphys.def'']: Physical parameters used in the simulation</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_run.def_Input_File ''run.def'']: Numerical parameters used in the simulation</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_gases.def_Input_File ''gases.def'']: List of gases in the simulations</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_traceur.def_Input_File ''traceur.def'']: Numerical tracers in the simulations</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_z2sig.def_Input_File ''z2sig.def'']: Pseudo-altitudes (in km) at which the user wants to set the vertical levels</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_diagfi.def_Input_File ''diagfi.def''] (optionnal): List of wanted outputs</li>
</ul>

==== input data ====

The Generic PCM requires several inputs in order to run. This includes, for instance:
* opacity tables
* aerosols optical properties
* stellar spectrum

These data can be modified/adapted by the users depending on the planet to be simulated.

==== output files ====

At the end of each GCM simulation, the Generic PCM produces several output files, and notably a file named "diagfi.nc". This file is an archive of the atmospheric/surface fields (temperatures, winds, clouds, etc.) along the GCM simulation. This is the file that contains most of the information needed to analyze/understand the content of a GCM simulation.

nb: The Generic PCM can also produce extra output files, such as the "diagspec.nc" files (that keep track of the spectral radiative fluxes in the GCM), the "stats.nc" (that keep track of statistical information along the GCM simulation), etc.

== Our team of developers (by alphabetical order) ==

'''Active contributors'''

*Benjamin Charnay (permanent, LESIA)
*Guillaume Chaverot
*Deborah Bardet
*François Forget (permanent, LMD)
*Gabriella Gilli
*Sandrine Guerlet (permanent, LMD)
*Yassin Jaziri
*Jeremy Leconte (permanent, LAB)
*Sébastien Lebonnois (permanent, LMD)
*Gwenael Milcareck
*Ehouarn Millour (permanent, LMD)
*Diogo Quirino
*Aymeric Spiga (permanent, LMD)
*Lucas Teinturier
*Martin Turbet (permanent, LMD)
*Romain Vandemeulebrouck

'''Past contributors and/or collaborators'''

*Tanguy Bertrand
*Alexandre Boissinot
*Emeline Bolmont
*Antony Delavois
*Thomas Dubos
*Vincent Eymet
*Frédéric Hourdin
*Franck Lefèvre
*Maxence Lefèvre
*Laura Kerber
*Franck Selsis
*Jan Vatant d'Olonne
*Margaux Vals
*Robin Wordsworth

Overview of the Generic PCM

2022-08-31T15:43:08Z

Jleconte:

== What is a GCM? ==

Our Global Climate Model (GCM) calculates the temporal evolution of the different variables (temperature, pressure, mass, mixing ratio of tracers/gas/clouds, winds, etc.) that control or describe the planetary meteorology and climate at different points of a 3D “grid” that covers the entire atmosphere.

From an initial state, the model calculates the temporal evolution of these variables, one timestep after another:
* At instant t, variables Xt (temperature for example) are known at every grid point of the atmosphere.
* We calculate the evolution (the tendencies) (δX/δt)1, (δX/δt)2, etc.) due to each physical phenomenon, calculated via the parameterization thereof (e.g., heating due to absorption of solar radiation, mixing due to turbulence in the planetary boundary layer, etc.).
* In order to move on to the next time step, t + δt, we can calculate Xt+δt from Xt and (δX/δt). This is formally known as the time integration of the variables. (For example, Xt+δt = Xt + (δX/δt)1δt + (δX/δt)2δt + ...)

The main task of the model is to calculate these tendencies (δX/δt) arising from the different parameterized phenomena.

TO BE MODIFIED (AND COMPLETED) by Jeremy

[[File:Didi-eps-converted-to-1.png|thumb|Physics / Dynamics interface]]

== Physical vs dynamical core ==

In practice, the 3D model is split in two components:

* '''a dynamical core''' containing the numerical solution of the general equations for atmospheric circulation. This component (including source code) is common to all terrestrial-type atmospheres, and applicable in certain cases to the upper atmospheres of gas giant planets.
* '''a physical package''' that is specific to the planet in question (as it takes into account dedicated parametrizations representative of ongoing physical processes) and which computes atmospheric processes in each atmospheric column (which are sub-grid-scale from the point of view of the dynamical core).

In practice, we do have several '''dynamical cores''' available with the model: LMDZ (global longitude/latitude grid), DYNAMICO (icosaedric grid) and WRF (rectangular box for local/regional studies)

TO BE MODIFIED (AND COMPLETED) by Aymeric

== What is a GCM (alternative version by JL) ==

A Global Climate Model (GCM) like the Generic PCM calculates the temporal evolution of the different variables (temperature, pressure, mass, mixing ratio of tracers/gas/clouds, winds, etc.) that control or describe the planetary meteorology and climate at different points of a 3D “grid” that covers the entire atmosphere.

To do that, the model solves 3D hydrodynamic equations that describe how atmospheric winds are created by various physical forcings (radiative heating/cooling, etc.) and how these winds transport and redistribute the various atmospheric fields (temperature, tracers, etc.). However, it can be shown that to a good level of approximation, the various forcings can be computed using only local conditions in a column of atmosphere, whereas long-range couplings between various points of the planet are mediated through atmospheric transport.

[[File:Didi-eps-converted-to-1.png|thumb|Physics / Dynamics interface]]

For these reasons, the 3D model is split in two components:

* '''a 3D dynamical core''' abble to integrate in time the general equations for atmospheric circulation when the various local forcings are known. This component (including source code) is common to all terrestrial-type atmospheres, and applicable in certain cases to the upper atmospheres of gas giant planets.
* '''a physical package''' that is specific to the planet in question (as it takes into account dedicated parametrizations representative of ongoing physical processes) and which computes atmospheric processes in each atmospheric column (which are sub-grid-scale from the point of view of the dynamical core).

In practice, we have several '''dynamical cores''' available with the model: LMDZ (global longitude/latitude grid), DYNAMICO (icosaedric grid), and WRF (rectangular box for local/regional studies)

From an initial state, the model calculates the temporal evolution of these variables, one timestep after another:
* At instant t, variables Xt (temperature for example) are known at every grid point of the atmosphere.
* The physical model calculates the local time derivatives of the various variables -- called the tendencies -- ((δX/δt)1, (δX/δt)2, etc.) due to each physical phenomenon: for example, heating due to absorption of solar radiation and infrared cooling, mixing due to turbulence in the planetary boundary layer, condensation/evaporation of water vapor, etc. These tendencies are calculated via parameterization of the processes involved that try to capture the physical behavior of the atmopshere at the subgrid scale.
* These tendencies are passed to the dynamical core that integrates the model forward in time to the next time step, t + δt, by solving the hydrodynamical equations.
* This new state can be used to recompute the tendencies for the next time step and so on.

== Philosophy of the Generic PCM ==

The accuracy and predictive power of any GCM is often dictated by the choice made for the physical phenomena that are included and for the way they are parametrized. To be accurate, many Earth-centric climate models use very complex parametrization that are heavily tuned on Earth observations. Such parametrization can, however, behave very poorly far from the parameter space where they have been validated, thus reducing their predictive power for exotic atmospheres.

As the goal of the Generic PCM is to model the climate of very different planets with the same model, a particular emphasis has been put on using simple parametrizations based as much as possible on ab-initio physical equations and conservation principles to avoid unphysical behaviors in extreme regimes.

== GCM inputs and outputs ==

[[File:Inout-eps-converted-to-1.png|thumb|input/output data]]

The input files are the files needed to initialize the model (state of the atmosphere at instant t0 as well as a dataset of boundary conditions). The output files are “historical files”, archives of the atmospheric flow history as simulated by the model, the “diagfi files”, the “stats files”, the daily averages, and so on.

TO BE COMPLETED

==== start and startfi files ====

TO BE COMPLETED

==== start vs restart files ====

TO BE COMPLETED

==== .def files ====

List of needed .def files:
<ul>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_callphys.def_Input_File ''callphys.def'']: Physical parameters</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_run.def_Input_File ''run.def'']: Numerical parameters</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_gases.def_Input_File ''gases.def'']: List of gases</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_traceur.def_Input_File ''traceur.def'']: Numerical traceurs in the atmosphere</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_z2sig.def_Input_File ''z2sig.def'']: Pseudo-altitudes (in km) at which the user wants to set the vertical levels</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_diagfi.def_Input_File ''diagfi.def''] (optionnal): List of wanted outputs</li>
</ul>

==== input data ====

TO BE COMPLETED

==== output files ====

diagfi.nc
diagspec_IR.nc / diagspec_VI.nc
stats.nc
etc.

TO BE COMPLETED

== Our team of developers ==

TO BE COMPLETED

Overview of the Generic PCM

2022-08-31T15:42:50Z

Jleconte:

== What is a GCM? ==

Our Global Climate Model (GCM) calculates the temporal evolution of the different variables (temperature, pressure, mass, mixing ratio of tracers/gas/clouds, winds, etc.) that control or describe the planetary meteorology and climate at different points of a 3D “grid” that covers the entire atmosphere.

From an initial state, the model calculates the temporal evolution of these variables, one timestep after another:
* At instant t, variables Xt (temperature for example) are known at every grid point of the atmosphere.
* We calculate the evolution (the tendencies) (δX/δt)1, (δX/δt)2, etc.) due to each physical phenomenon, calculated via the parameterization thereof (e.g., heating due to absorption of solar radiation, mixing due to turbulence in the planetary boundary layer, etc.).
* In order to move on to the next time step, t + δt, we can calculate Xt+δt from Xt and (δX/δt). This is formally known as the time integration of the variables. (For example, Xt+δt = Xt + (δX/δt)1δt + (δX/δt)2δt + ...)

The main task of the model is to calculate these tendencies (δX/δt) arising from the different parameterized phenomena.

TO BE MODIFIED (AND COMPLETED) by Jeremy

[[File:Didi-eps-converted-to-1.png|thumb|Physics / Dynamics interface]]

== Physical vs dynamical core ==

In practice, the 3D model is split in two components:

* '''a dynamical core''' containing the numerical solution of the general equations for atmospheric circulation. This component (including source code) is common to all terrestrial-type atmospheres, and applicable in certain cases to the upper atmospheres of gas giant planets.
* '''a physical package''' that is specific to the planet in question (as it takes into account dedicated parametrizations representative of ongoing physical processes) and which computes atmospheric processes in each atmospheric column (which are sub-grid-scale from the point of view of the dynamical core).

In practice, we do have several '''dynamical cores''' available with the model: LMDZ (global longitude/latitude grid), DYNAMICO (icosaedric grid) and WRF (rectangular box for local/regional studies)

TO BE MODIFIED (AND COMPLETED) by Aymeric

== What is a GCM (alternative version by JL) ==

A Global Climate Model (GCM) like the Generic PCM calculates the temporal evolution of the different variables (temperature, pressure, mass, mixing ratio of tracers/gas/clouds, winds, etc.) that control or describe the planetary meteorology and climate at different points of a 3D “grid” that covers the entire atmosphere.

To do that, the model solves 3D hydrodynamic equations that describe how atmospheric winds are created by various physical forcings (radiative heating/cooling, etc.) and how these winds transport and redistribute the various atmospheric fields (temperature, tracers, etc.). However, it can be shown that to a good level of approximation, the various forcings can be computed using only local conditions in a column of atmosphere, whereas long-range couplings between various points of the planet are mediated through atmospheric transport.

For these reasons, the 3D model is split in two components:

[[File:Didi-eps-converted-to-1.png|thumb|Physics / Dynamics interface]]

* '''a 3D dynamical core''' abble to integrate in time the general equations for atmospheric circulation when the various local forcings are known. This component (including source code) is common to all terrestrial-type atmospheres, and applicable in certain cases to the upper atmospheres of gas giant planets.
* '''a physical package''' that is specific to the planet in question (as it takes into account dedicated parametrizations representative of ongoing physical processes) and which computes atmospheric processes in each atmospheric column (which are sub-grid-scale from the point of view of the dynamical core).

In practice, we have several '''dynamical cores''' available with the model: LMDZ (global longitude/latitude grid), DYNAMICO (icosaedric grid), and WRF (rectangular box for local/regional studies)

From an initial state, the model calculates the temporal evolution of these variables, one timestep after another:
* At instant t, variables Xt (temperature for example) are known at every grid point of the atmosphere.
* The physical model calculates the local time derivatives of the various variables -- called the tendencies -- ((δX/δt)1, (δX/δt)2, etc.) due to each physical phenomenon: for example, heating due to absorption of solar radiation and infrared cooling, mixing due to turbulence in the planetary boundary layer, condensation/evaporation of water vapor, etc. These tendencies are calculated via parameterization of the processes involved that try to capture the physical behavior of the atmopshere at the subgrid scale.
* These tendencies are passed to the dynamical core that integrates the model forward in time to the next time step, t + δt, by solving the hydrodynamical equations.
* This new state can be used to recompute the tendencies for the next time step and so on.

== Philosophy of the Generic PCM ==

The accuracy and predictive power of any GCM is often dictated by the choice made for the physical phenomena that are included and for the way they are parametrized. To be accurate, many Earth-centric climate models use very complex parametrization that are heavily tuned on Earth observations. Such parametrization can, however, behave very poorly far from the parameter space where they have been validated, thus reducing their predictive power for exotic atmospheres.

As the goal of the Generic PCM is to model the climate of very different planets with the same model, a particular emphasis has been put on using simple parametrizations based as much as possible on ab-initio physical equations and conservation principles to avoid unphysical behaviors in extreme regimes.

== GCM inputs and outputs ==

[[File:Inout-eps-converted-to-1.png|thumb|input/output data]]

The input files are the files needed to initialize the model (state of the atmosphere at instant t0 as well as a dataset of boundary conditions). The output files are “historical files”, archives of the atmospheric flow history as simulated by the model, the “diagfi files”, the “stats files”, the daily averages, and so on.

TO BE COMPLETED

==== start and startfi files ====

TO BE COMPLETED

==== start vs restart files ====

TO BE COMPLETED

==== .def files ====

List of needed .def files:
<ul>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_callphys.def_Input_File ''callphys.def'']: Physical parameters</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_run.def_Input_File ''run.def'']: Numerical parameters</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_gases.def_Input_File ''gases.def'']: List of gases</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_traceur.def_Input_File ''traceur.def'']: Numerical traceurs in the atmosphere</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_z2sig.def_Input_File ''z2sig.def'']: Pseudo-altitudes (in km) at which the user wants to set the vertical levels</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_diagfi.def_Input_File ''diagfi.def''] (optionnal): List of wanted outputs</li>
</ul>

==== input data ====

TO BE COMPLETED

==== output files ====

diagfi.nc
diagspec_IR.nc / diagspec_VI.nc
stats.nc
etc.

TO BE COMPLETED

== Our team of developers ==

TO BE COMPLETED

Overview of the Generic PCM

2022-08-31T15:39:54Z

Jleconte:

== What is a GCM? ==

Our Global Climate Model (GCM) calculates the temporal evolution of the different variables (temperature, pressure, mass, mixing ratio of tracers/gas/clouds, winds, etc.) that control or describe the planetary meteorology and climate at different points of a 3D “grid” that covers the entire atmosphere.

From an initial state, the model calculates the temporal evolution of these variables, one timestep after another:
* At instant t, variables Xt (temperature for example) are known at every grid point of the atmosphere.
* We calculate the evolution (the tendencies) (δX/δt)1, (δX/δt)2, etc.) due to each physical phenomenon, calculated via the parameterization thereof (e.g., heating due to absorption of solar radiation, mixing due to turbulence in the planetary boundary layer, etc.).
* In order to move on to the next time step, t + δt, we can calculate Xt+δt from Xt and (δX/δt). This is formally known as the time integration of the variables. (For example, Xt+δt = Xt + (δX/δt)1δt + (δX/δt)2δt + ...)

The main task of the model is to calculate these tendencies (δX/δt) arising from the different parameterized phenomena.

TO BE MODIFIED (AND COMPLETED) by Jeremy

[[File:Didi-eps-converted-to-1.png|thumb|Physics / Dynamics interface]]

== Physical vs dynamical core ==

In practice, the 3D model is split in two components:

* '''a dynamical core''' containing the numerical solution of the general equations for atmospheric circulation. This component (including source code) is common to all terrestrial-type atmospheres, and applicable in certain cases to the upper atmospheres of gas giant planets.
* '''a physical package''' that is specific to the planet in question (as it takes into account dedicated parametrizations representative of ongoing physical processes) and which computes atmospheric processes in each atmospheric column (which are sub-grid-scale from the point of view of the dynamical core).

In practice, we do have several '''dynamical cores''' available with the model: LMDZ (global longitude/latitude grid), DYNAMICO (icosaedric grid) and WRF (rectangular box for local/regional studies)

TO BE MODIFIED (AND COMPLETED) by Aymeric

== What is a GCM (alternative version by JL) ==

A Global Climate Model (GCM) like the Generic PCM calculates the temporal evolution of the different variables (temperature, pressure, mass, mixing ratio of tracers/gas/clouds, winds, etc.) that control or describe the planetary meteorology and climate at different points of a 3D “grid” that covers the entire atmosphere.

To do that, the model solves 3D hydrodynamic equations that describe how atmospheric winds are created by various physical forcings (radiative heating/cooling, etc.) and how these winds transport and redistribute the various atmospheric fields (temperature, tracers, etc.). However, it can be shown that to a good level of approximation, the various forcings can be computed using only local conditions in a column of atmosphere, whereas long-range couplings between various points of the planet are mediated through atmospheric transport.

For these reasons, the 3D model is split in two components:

* '''a 3D dynamical core''' abble to integrate in time the general equations for atmospheric circulation when the various local forcings are known. This component (including source code) is common to all terrestrial-type atmospheres, and applicable in certain cases to the upper atmospheres of gas giant planets.
* '''a physical package''' that is specific to the planet in question (as it takes into account dedicated parametrizations representative of ongoing physical processes) and which computes atmospheric processes in each atmospheric column (which are sub-grid-scale from the point of view of the dynamical core).

[[File:Didi-eps-converted-to-1.png|thumb|Physics / Dynamics interface]]

In practice, we have several '''dynamical cores''' available with the model: LMDZ (global longitude/latitude grid), DYNAMICO (icosaedric grid), and WRF (rectangular box for local/regional studies)

From an initial state, the model calculates the temporal evolution of these variables, one timestep after another:
* At instant t, variables Xt (temperature for example) are known at every grid point of the atmosphere.
* The physical model calculates the local time derivatives of the various variables -- called the tendencies -- ((δX/δt)1, (δX/δt)2, etc.) due to each physical phenomenon: for example, heating due to absorption of solar radiation and infrared cooling, mixing due to turbulence in the planetary boundary layer, condensation/evaporation of water vapor, etc. These tendencies are calculated via parameterization of the processes involved that try to capture the physical behavior of the atmopshere at the subgrid scale.
* These tendencies are passed to the dynamical core that integrates the model forward in time to the next time step, t + δt, by solving the hydrodynamical equations.
* This new state can be used to recompute the tendencies for the next time step and so on.

== Philosophy of the Generic PCM ==

The accuracy and predictive power of any GCM is often dictated by the choice made for the physical phenomena that are included and for the way they are parametrized. To be accurate, many Earth-centric climate models use very complex parametrization that are heavily tuned on Earth observations. Such parametrization can, however, behave very poorly far from the parameter space where they have been validated, thus reducing their predictive power for exotic atmospheres.

As the goal of the Generic PCM is to model the climate of very different planets with the same model, a particular emphasis has been put on using simple parametrizations based as much as possible on ab-initio physical equations and conservation principles to avoid unphysical behaviors in extreme regimes.

== GCM inputs and outputs ==

[[File:Inout-eps-converted-to-1.png|thumb|input/output data]]

The input files are the files needed to initialize the model (state of the atmosphere at instant t0 as well as a dataset of boundary conditions). The output files are “historical files”, archives of the atmospheric flow history as simulated by the model, the “diagfi files”, the “stats files”, the daily averages, and so on.

TO BE COMPLETED

==== start and startfi files ====

TO BE COMPLETED

==== start vs restart files ====

TO BE COMPLETED

==== .def files ====

List of needed .def files:
<ul>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_callphys.def_Input_File ''callphys.def'']: Physical parameters</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_run.def_Input_File ''run.def'']: Numerical parameters</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_gases.def_Input_File ''gases.def'']: List of gases</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_traceur.def_Input_File ''traceur.def'']: Numerical traceurs in the atmosphere</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_z2sig.def_Input_File ''z2sig.def'']: Pseudo-altitudes (in km) at which the user wants to set the vertical levels</li>
<li> [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_diagfi.def_Input_File ''diagfi.def''] (optionnal): List of wanted outputs</li>
</ul>

==== input data ====

TO BE COMPLETED

==== output files ====

diagfi.nc
diagspec_IR.nc / diagspec_VI.nc
stats.nc
etc.

TO BE COMPLETED

== Our team of developers ==

TO BE COMPLETED

Advanced Use of the GCM

2022-06-22T10:54:37Z

Jleconte:

== Running in parallel ==

For large simulation (long run, high resolution etc...), the waiting time can becomes very long.
To overcome this issue, the model can works in parallel.
It first needs to be compiled in parallel mode and then be run with a specific command.
For all the details see the dedicated page [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/Parallelism Parallelism]

== Distinctions beween ifort, mpi, etc. ==

TO BE COMPLETED by Ehouarn ?

== Distinction between using IOIPSL or XIOS ==

TO BE COMPLETED by Ehouarn ?

== How to Change Vertical and Horizontal Resolutions ==

=== When you are using the regular longitude/latitude horizontal grid ===
To run at a different grid resolution than available initial conditions files, one needs to use the tools ''newstart.e'' and ''start2archive.e''

For example, to create initial states at grid resolution 32×24×25 from NetCDF files start and startfi at grid resolution 64×48×32 :

* Create file ''start_archive.nc'' with ''start2archive.e'' compiled at grid resolution 64×48×32 using old file ''z2sig.def'' used previously
* Create files ''restart.nc'' and ''restartfi.nc'' with ''newstart.e'' compiled at grid resolution 32×24×25, using a new file ''z2sig.def'' (more details below on the choice of the ''z2sig.def'').
* While executing ''newstart.e'', you need to choose the answer '0 - from a file start_archive' and then press enter to all other requests.

==== What you need to ''know'' about the ''z2sig.def'' file ====

For a model with Nlay layers, the z2sig.def file must contain at least Nlay+1 lines (the other not being read).

The first line is a scale height ($$H$$). The following lines are the target pseudo-altitudes for the model from the bottom up ($$z_i$$).
The units do not matter as long as you use the same ones for both.

The model will use these altitudes to compute a target pressure grid ($$p_i$$ ) as follows:
\begin{align}
\label{def:pseudoalt}
p_i &= p_s \exp(-z_i/H),
\end{align}
where $$p_s$$ is the surface pressure.

As you can see, the scale height and pseudo altitudes enter the equation only through their ratio. So they do not have to to be the real scale-height and altitudes of the atmosphere you are simulating.
So you can use the same z2sig.def for different planets.

There is no hard rule to follow to determine the altitude/pressure levels you should use. As a rule of thumb, layers should be thiner near the surface to properly resolve the surface boundary layer. Then they should gradually increase in size over a couple scale heights and transition to constant thickness above that. Of course, some specific applications may require thinner layers in some specific parts of the atmospheres.

A little trick for those who prefer to think in terms of (log)pressure: if you use $$H= - \ln 0.1 \approx 2.30259$$, then $$z_i=x$$ corresponds to a pressure difference with the surface of exactly x pressure decades. This is particularly useful for giant-planet applications.



=== When you are using the DYNAMICO icosahedral horizontal grid ===

The horizontal resolution for the DYNAMICO dynamical core is managed from several setting files, online during the execution.
To this purpose, each part of the GCM managing the in/output fields ('''ICOSAGCM''', '''ICOSA_LMDZ''', '''XIOS''') requires to know the input and output grids:

'''1. ''context_lmdz_physics.xml'':'''

You can find several grid setup already defined:

<syntaxhighlight lang="xml" line>
<domain_definition>
<domain id="dom_96_95" ni_glo="96" nj_glo="95" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_144_142" ni_glo="144" nj_glo="142" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_512_360" ni_glo="512" nj_glo="360" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_720_360" ni_glo="720" nj_glo="360" type="rectilinear">
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_out" domain_ref="dom_720_360"/>
</domain_definition>
</syntaxhighlight>

In this example, the output grid for the physics fields is defined by

<syntaxhighlight lang="xml">
<domain id="dom_out" domain_ref="dom_720_360"/>
</syntaxhighlight>

which is an half-degree horizontal resolution. To change this resolution, you have to change name of the '''domain_ref''' grid, for instance:

<syntaxhighlight lang="xml">
<domain id="dom_out" domain_ref="dom_96_95"/>
</syntaxhighlight>

'''2. ''run_icosa.def'': setting file to execute a simulation'''

In this file, regarding of the horizontal resolution intended, you have to set the number of subdivision on the main triangle.
For reminder, each hexagonal mesh is divided in several main triangles and each main triangles are divided in suitable number of sub-triangles according the horizontal resolution

<syntaxhighlight lang="bash" line>
#nbp --> number of subdivision on a main triangle: integer (default=40)
# nbp = sqrt((nbr_lat x nbr_lon)/10)
# nbp: 20 40 80 160
# T-edge length (km): 500 250 120 60
# Example: nbp(128x96) = 35 -> 40
# nbp(256x192)= 70 -> 80
# nbp(360x720)= 160 -> 160
nbp = 160
</syntaxhighlight>

If you have chosen the 96_95 output grid in ''context_lmdz_physics.xml'', you have to calculate $$nbp = \sqrt(96x95) / 10 = 10$$ and in this case

<syntaxhighlight lang="bash">
nbp = 20
</syntaxhighlight>

After the number of subdivision of the main triangle, you have to define the number subdivision over each direction. At this stage you need to be careful as the number of subdivisions on each direction:
* needs to be set according to the number of subdivisions on the main triangle '''nbp'''
* will determine the number of processors on which the GCM will be most effective

<syntaxhighlight lang="bash" line>
## sub splitting of main rhombus : integer (default=1)
#nsplit_i=1
#nsplit_j=1
#omp_level_size=1
###############################################################
## There must be less MPIxOpenMP processes than the 10 x nsplit_i x nsplit_j tiles
## typically for pure MPI runs, let nproc = 10 x nsplit_i x nsplit_j
## it is better to have nbp/nsplit_i > 10 and nbp/nplit_j > 10
###############################################################
#### 40 noeuds de 24 processeurs = 960 procs
nsplit_i=12
nsplit_j=8

#### 50 noeuds de 24 processeurs = 1200 procs
#nsplit_i=10
#nsplit_j=12
</syntaxhighlight>

With the same example as above, the 96_95 output grid requires:
$$nsplit_i < 2$$ and $$nsplit_j < 2$$
We advise you to select:

<syntaxhighlight lang="bash">
## sub splitting of main rhombus : integer (default=1)
nsplit_i=1
nsplit_j=1
</syntaxhighlight>

and using 10 processors.

== How to Change the Topography (or remove it) ==

The generic model can use in principle any type of surface topography, provided that the topographic data file is available in the right format, and put in the right place. The information content on the surface topography is contained in the ''startfi.nc'', and we do have developed tools (see below) to modify the ''startfi.nc'' to account for a new surface topography.

To change the surface topography of a simulation, we recommend to follow the procedure detailed below:

* Create file ''start_archive.nc'' with ''start2archive.e'' compiled at the same (horizontal and vertical) resolution than the ''start.nc'' and ''startfi.nc'' files.
* Create files ''restart.nc'' and ''restartfi.nc'' with ''newstart.e'' compiled again at the same (horizontal and vertical) resolution.
* While executing ''newstart.e'', you need to choose the answer '0 - from a file start_archive' and then press enter to all other requests.
* At some point, the script ''newstart.e'' asks you to chose the surface topography you want from the list of files available in your 'datagcm/surface_data/' directory.

We do have a repository of for Venus, Earth and Mars through time available at https://web.lmd.jussieu.fr/~lmdz/planets/LMDZ.GENERIC/datagcm/surface_data/. You can download the surface topography files and place them in your 'datagcm/surface_data/' directory.

----

Special note: How to remove the topography?

TBD by Gwenael?

== How to Change the Opacity Tables ==

TO BE COMPLETED by Sandrine ?

== How to Manage Tracers ==

Tracers are managed thanks to the [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_traceur.def_Input_File ''traceur.def''] file.

Specific treatment of some tracers (e.g., water vapor cycle) can be added directly in the model and an option added in [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_callphys.def_Input_File ''callphys.def''] file.

Advanced Use of the GCM

2022-06-22T10:49:09Z

Jleconte:

== Running in parallel ==

For large simulation (long run, high resolution etc...), the waiting time can becomes very long.
To overcome this issue, the model can works in parallel.
It first needs to be compiled in parallel mode and then be run with a specific command.
For all the details see the dedicated page [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/Parallelism Parallelism]

== Distinctions beween ifort, mpi, etc. ==

TO BE COMPLETED by Ehouarn ?

== Distinction between using IOIPSL or XIOS ==

TO BE COMPLETED by Ehouarn ?

== How to Change Vertical and Horizontal Resolutions ==

=== When you are using the regular longitude/latitude horizontal grid ===
To run at a different grid resolution than available initial conditions files, one needs to use the tools ''newstart.e'' and ''start2archive.e''

For example, to create initial states at grid resolution 32×24×25 from NetCDF files start and startfi at grid resolution 64×48×32 :

* Create file ''start_archive.nc'' with ''start2archive.e'' compiled at grid resolution 64×48×32 using old file ''z2sig.def'' used previously
* Create files ''restart.nc'' and ''restartfi.nc'' with ''newstart.e'' compiled at grid resolution 32×24×25, using a new file ''z2sig.def'' (more details below on the choice of the ''z2sig.def'').
* While executing ''newstart.e'', you need to choose the answer '0 - from a file start_archive' and then press enter to all other requests.

==== What you need to ''know'' about the ''z2sig.def'' file ====

For a model with Nlay layers, the z2sig.def file must contain at least Nlay+1 lines (the other not being read).

The first line is a scale height ($$H$$). The following lines are the target pseudo-altitudes for the model from the bottom up ($$z_i$$).
The units do not matter as long as you use the same ones for both.

The model will use these altitudes to compute a target pressure grid ($$p_i$$ ) as follows:
\begin{align}
\label{def:pseudoalt}
p_i &= p_s \exp(-z_i/H),
\end{align}
where $$p_s$$ is the surface pressure.

As you can see, the scale height and pseudo altitudes enter the equation only through their ratio. So they do not have to to be the real scale-height and altitudes of the atmosphere you are simulating.
So you can use the same z2sig.def for different planets.

There is no hard rule to follow to determine the altitude/pressure levels you should use. As a rule of thumb, layers should be thiner near the surface to properly resolve the surface boundary layer. Then they should gradually increase in size over a couple scale heights and transition to constant thickness above that. Of course, some specific applications may require thinner layers in some specific parts of the atmospheres.



=== When you are using the DYNAMICO icosahedral horizontal grid ===

The horizontal resolution for the DYNAMICO dynamical core is managed from several setting files, online during the execution.
To this purpose, each part of the GCM managing the in/output fields ('''ICOSAGCM''', '''ICOSA_LMDZ''', '''XIOS''') requires to know the input and output grids:

'''1. ''context_lmdz_physics.xml'':'''

You can find several grid setup already defined:

<syntaxhighlight lang="xml" line>
<domain_definition>
<domain id="dom_96_95" ni_glo="96" nj_glo="95" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_144_142" ni_glo="144" nj_glo="142" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_512_360" ni_glo="512" nj_glo="360" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_720_360" ni_glo="720" nj_glo="360" type="rectilinear">
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_out" domain_ref="dom_720_360"/>
</domain_definition>
</syntaxhighlight>

In this example, the output grid for the physics fields is defined by

<syntaxhighlight lang="xml">
<domain id="dom_out" domain_ref="dom_720_360"/>
</syntaxhighlight>

which is an half-degree horizontal resolution. To change this resolution, you have to change name of the '''domain_ref''' grid, for instance:

<syntaxhighlight lang="xml">
<domain id="dom_out" domain_ref="dom_96_95"/>
</syntaxhighlight>

'''2. ''run_icosa.def'': setting file to execute a simulation'''

In this file, regarding of the horizontal resolution intended, you have to set the number of subdivision on the main triangle.
For reminder, each hexagonal mesh is divided in several main triangles and each main triangles are divided in suitable number of sub-triangles according the horizontal resolution

<syntaxhighlight lang="bash" line>
#nbp --> number of subdivision on a main triangle: integer (default=40)
# nbp = sqrt((nbr_lat x nbr_lon)/10)
# nbp: 20 40 80 160
# T-edge length (km): 500 250 120 60
# Example: nbp(128x96) = 35 -> 40
# nbp(256x192)= 70 -> 80
# nbp(360x720)= 160 -> 160
nbp = 160
</syntaxhighlight>

If you have chosen the 96_95 output grid in ''context_lmdz_physics.xml'', you have to calculate $$nbp = \sqrt(96x95) / 10 = 10$$ and in this case

<syntaxhighlight lang="bash">
nbp = 20
</syntaxhighlight>

After the number of subdivision of the main triangle, you have to define the number subdivision over each direction. At this stage you need to be careful as the number of subdivisions on each direction:
* needs to be set according to the number of subdivisions on the main triangle '''nbp'''
* will determine the number of processors on which the GCM will be most effective

<syntaxhighlight lang="bash" line>
## sub splitting of main rhombus : integer (default=1)
#nsplit_i=1
#nsplit_j=1
#omp_level_size=1
###############################################################
## There must be less MPIxOpenMP processes than the 10 x nsplit_i x nsplit_j tiles
## typically for pure MPI runs, let nproc = 10 x nsplit_i x nsplit_j
## it is better to have nbp/nsplit_i > 10 and nbp/nplit_j > 10
###############################################################
#### 40 noeuds de 24 processeurs = 960 procs
nsplit_i=12
nsplit_j=8

#### 50 noeuds de 24 processeurs = 1200 procs
#nsplit_i=10
#nsplit_j=12
</syntaxhighlight>

With the same example as above, the 96_95 output grid requires:
$$nsplit_i < 2$$ and $$nsplit_j < 2$$
We advise you to select:

<syntaxhighlight lang="bash">
## sub splitting of main rhombus : integer (default=1)
nsplit_i=1
nsplit_j=1
</syntaxhighlight>

and using 10 processors.

== How to Change the Topography (or remove it) ==

The generic model can use in principle any type of surface topography, provided that the topographic data file is available in the right format, and put in the right place. The information content on the surface topography is contained in the ''startfi.nc'', and we do have developed tools (see below) to modify the ''startfi.nc'' to account for a new surface topography.

To change the surface topography of a simulation, we recommend to follow the procedure detailed below:

* Create file ''start_archive.nc'' with ''start2archive.e'' compiled at the same (horizontal and vertical) resolution than the ''start.nc'' and ''startfi.nc'' files.
* Create files ''restart.nc'' and ''restartfi.nc'' with ''newstart.e'' compiled again at the same (horizontal and vertical) resolution.
* While executing ''newstart.e'', you need to choose the answer '0 - from a file start_archive' and then press enter to all other requests.
* At some point, the script ''newstart.e'' asks you to chose the surface topography you want from the list of files available in your 'datagcm/surface_data/' directory.

We do have a repository of for Venus, Earth and Mars through time available at https://web.lmd.jussieu.fr/~lmdz/planets/LMDZ.GENERIC/datagcm/surface_data/. You can download the surface topography files and place them in your 'datagcm/surface_data/' directory.

----

Special note: How to remove the topography?

TBD by Gwenael?

== How to Change the Opacity Tables ==

TO BE COMPLETED by Sandrine ?

== How to Manage Tracers ==

Tracers are managed thanks to the [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_traceur.def_Input_File ''traceur.def''] file.

Specific treatment of some tracers (e.g., water vapor cycle) can be added directly in the model and an option added in [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_callphys.def_Input_File ''callphys.def''] file.

Advanced Use of the GCM

2022-06-22T10:35:24Z

Jleconte: /* What you need to know about the z2sig.def file (change of vertical resolution only) */

== Running in parallel ==

For large simulation (long run, high resolution etc...), the waiting time can becomes very long.
To overcome this issue, the model can works in parallel.
It first needs to be compiled in parallel mode and then be run with a specific command.
For all the details see the dedicated page [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/Parallelism Parallelism]

== Distinctions beween ifort, mpi, etc. ==

TO BE COMPLETED by Ehouarn ?

== Distinction between using IOIPSL or XIOS ==

TO BE COMPLETED by Ehouarn ?

== How to Change Vertical and Horizontal Resolutions ==

=== When you are using the regular longitude/latitude horizontal grid ===
To run at a different grid resolution than available initial conditions files, one needs to use the tools ''newstart.e'' and ''start2archive.e''

For example, to create initial states at grid resolution 32×24×25 from NetCDF files start and startfi at grid resolution 64×48×32 :

* Create file ''start_archive.nc'' with ''start2archive.e'' compiled at grid resolution 64×48×32 using old file ''z2sig.def'' used previously
* Create files ''restart.nc'' and ''restartfi.nc'' with ''newstart.e'' compiled at grid resolution 32×24×25, using a new file ''z2sig.def'' (more details below on the choice of the ''z2sig.def'').
* While executing ''newstart.e'', you need to choose the answer '0 - from a file start_archive' and then press enter to all other requests.

==== What you need to ''know'' about the ''z2sig.def'' file ====

For a model with Nlay layers, the z2sig.def file must contain at least Nlay+1 lines (the other not being read).

The first line is a scale height ($$H$$. The following lines are the target pseudo-altitudes for the model from the bottom up ($$z_i$$).
The units do not matter as long as you use the same ones for both.

The model will use these altitudes to compute a target pressure grid ($$p_i$$ ) as follows:
\begin{align}
\label{def:pseudoalt}
p_i &= p_s \exp(-z_i/H)
\end{align}

The scale height and pseudo altitudes do not have to It does not have to be the real scale height of the panet, you can choose the one you want (and the unit you want).

TO BE COMPLETED by Jeremy



=== When you are using the DYNAMICO icosahedral horizontal grid ===

The horizontal resolution for the DYNAMICO dynamical core is managed from several setting files, online during the execution.
To this purpose, each part of the GCM managing the in/output fields ('''ICOSAGCM''', '''ICOSA_LMDZ''', '''XIOS''') requires to know the input and output grids:

'''1. ''context_lmdz_physics.xml'':'''

You can find several grid setup already defined:

<syntaxhighlight lang="xml" line>
<domain_definition>
<domain id="dom_96_95" ni_glo="96" nj_glo="95" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_144_142" ni_glo="144" nj_glo="142" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_512_360" ni_glo="512" nj_glo="360" type="rectilinear" >
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_720_360" ni_glo="720" nj_glo="360" type="rectilinear">
<generate_rectilinear_domain/>
<interpolate_domain order="1"/>
</domain>

<domain id="dom_out" domain_ref="dom_720_360"/>
</domain_definition>
</syntaxhighlight>

In this example, the output grid for the physics fields is defined by

<syntaxhighlight lang="xml">
<domain id="dom_out" domain_ref="dom_720_360"/>
</syntaxhighlight>

which is an half-degree horizontal resolution. To change this resolution, you have to change name of the '''domain_ref''' grid, for instance:

<syntaxhighlight lang="xml">
<domain id="dom_out" domain_ref="dom_96_95"/>
</syntaxhighlight>

'''2. ''run_icosa.def'': setting file to execute a simulation'''

In this file, regarding of the horizontal resolution intended, you have to set the number of subdivision on the main triangle.
For reminder, each hexagonal mesh is divided in several main triangles and each main triangles are divided in suitable number of sub-triangles according the horizontal resolution

<syntaxhighlight lang="bash" line>
#nbp --> number of subdivision on a main triangle: integer (default=40)
# nbp = sqrt((nbr_lat x nbr_lon)/10)
# nbp: 20 40 80 160
# T-edge length (km): 500 250 120 60
# Example: nbp(128x96) = 35 -> 40
# nbp(256x192)= 70 -> 80
# nbp(360x720)= 160 -> 160
nbp = 160
</syntaxhighlight>

If you have chosen the 96_95 output grid in ''context_lmdz_physics.xml'', you have to calculate $$nbp = \sqrt(96x95) / 10 = 10$$ and in this case

<syntaxhighlight lang="bash">
nbp = 20
</syntaxhighlight>

After the number of subdivision of the main triangle, you have to define the number subdivision over each direction. At this stage you need to be careful as the number of subdivisions on each direction:
* needs to be set according to the number of subdivisions on the main triangle '''nbp'''
* will determine the number of processors on which the GCM will be most effective

<syntaxhighlight lang="bash" line>
## sub splitting of main rhombus : integer (default=1)
#nsplit_i=1
#nsplit_j=1
#omp_level_size=1
###############################################################
## There must be less MPIxOpenMP processes than the 10 x nsplit_i x nsplit_j tiles
## typically for pure MPI runs, let nproc = 10 x nsplit_i x nsplit_j
## it is better to have nbp/nsplit_i > 10 and nbp/nplit_j > 10
###############################################################
#### 40 noeuds de 24 processeurs = 960 procs
nsplit_i=12
nsplit_j=8

#### 50 noeuds de 24 processeurs = 1200 procs
#nsplit_i=10
#nsplit_j=12
</syntaxhighlight>

With the same example as above, the 96_95 output grid requires:
$$nsplit_i < 2$$ and $$nsplit_j < 2$$
We advise you to select:

<syntaxhighlight lang="bash">
## sub splitting of main rhombus : integer (default=1)
nsplit_i=1
nsplit_j=1
</syntaxhighlight>

and using 10 processors.

== How to Change the Topography (or remove it) ==

The generic model can use in principle any type of surface topography, provided that the topographic data file is available in the right format, and put in the right place. The information content on the surface topography is contained in the ''startfi.nc'', and we do have developed tools (see below) to modify the ''startfi.nc'' to account for a new surface topography.

To change the surface topography of a simulation, we recommend to follow the procedure detailed below:

* Create file ''start_archive.nc'' with ''start2archive.e'' compiled at the same (horizontal and vertical) resolution than the ''start.nc'' and ''startfi.nc'' files.
* Create files ''restart.nc'' and ''restartfi.nc'' with ''newstart.e'' compiled again at the same (horizontal and vertical) resolution.
* While executing ''newstart.e'', you need to choose the answer '0 - from a file start_archive' and then press enter to all other requests.
* At some point, the script ''newstart.e'' asks you to chose the surface topography you want from the list of files available in your 'datagcm/surface_data/' directory.

We do have a repository of for Venus, Earth and Mars through time available at https://web.lmd.jussieu.fr/~lmdz/planets/LMDZ.GENERIC/datagcm/surface_data/. You can download the surface topography files and place them in your 'datagcm/surface_data/' directory.

----

Special note: How to remove the topography?

TBD by Gwenael?

== How to Change the Opacity Tables ==

TO BE COMPLETED by Sandrine ?

== How to Manage Tracers ==

Tracers are managed thanks to the [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_traceur.def_Input_File ''traceur.def''] file.

Specific treatment of some tracers (e.g., water vapor cycle) can be added directly in the model and an option added in [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/The_callphys.def_Input_File ''callphys.def''] file.

Tool Box

2022-05-11T09:44:20Z

Jleconte: /* python scripts */

== Pre-processing Tools ==
=== newstart ===
=== start2archive ===
=== visualization tools ===
=== other third party scripts and tools ===

TO BE COMPLETED

== Post-processing tools ==
=== zrecast ===

TO BE COMPLETED

=== mass stream function ===

The mass stream function (and the total angular momentum) can be computed from a diagfi.nc or a stats.nc, using the '''streamfunction.F90''' script. The script is located at

<syntaxhighlight lang="bash">
trunk/LMDZ.GENERIC/utilities
</syntaxhighlight>

To compile the script, open the ''compile'' file in the same directory and do the following:
* Replace "pgf90" with your favorite fortran compiler
* replace "/distrib/local/netcdf/pgi_7.1-6_32/lib" with the lib address and directory that contains your NetCDF library (file ''libnetcdf.a'').
* Replace "/distrib/local/netcdf/pgi_7.1-6_32/include" with the address of the directory that contains the NetCDF include file (''netcdf.inc'').
* You can mess with the compiling options but it is not mandatory.

Once the script is compiled, copy it in the same directory as your '''.nc''' file and run

<syntaxhighlight lang="bash">
./streamfunction.e
</syntaxhighlight>
The script will ask you for the name of your '''.nc''' file, and will run and produce a new '''nameofyourfile_stream.nc''' file.

'''Be careful''' : In this new file, all fields are temporally and zonally averaged.

If you want to use '''python''' instead of '''fortran''', you can take a look at this [https://github.com/aymeric-spiga/dynanalysis repo]. It hosts a tool to perform dynamical analysis of GCM simulations (and therefore, it computes the mass stream function and a lot of other stuff), but it is tailored for Dynamico only. This repo also takes care of recasting (it does the job of both ''zrecast.F90'' and ''streamfunction.F90'')

== Continuing Simulations ==

=== manually ===

At the end of a simulation, the model generates restart files (files 'restart.nc' and 'restartfi.nc') which contain the final state of the model. The 'restart.nc' and 'restartfi.nc' files have the same format as the 'start.nc' and 'startfi.nc' files, respectively.

These files can in fact be used as initial states to continue the simulation, using the following renaming command lines:

<syntaxhighlight lang="bash">
mv restart.nc start.nc
mv restartfi.nc startfi.nc
</syntaxhighlight>

Running a simulation with these start files will in fact resume the simulation from where the previous run ended.

=== with bash scripts ===

We have set up very simple bash scripts to automatize the launching of chain simulations. Here is an example of bash script that does the job:

<syntaxhighlight lang="bash">
#!/bin/bash
###########################################################################
# Script to perform several chained LMD Mars GCM simulations
# SET HERE the maximum total number of simulations

nummax=100

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

echo "---------------------------------------------------------"
echo "STARTING LOOP RUN"
echo "---------------------------------------------------------"

dir=`pwd`
machine=`hostname`
address=`whoami`

# Look for file "num_run" which should contain
# the value of the previously computed season
# (defaults to 0 if file "num_run" does not exist)
if [[ -r num_run ]] ; then
echo "found file num_run"
numold=`cat num_run`
else
numold=0
fi
echo "numold is set to" ${numold}

# Set value of current season
(( numnew = ${numold} + 1 ))
echo "numnew is set to" ${numnew}

# Look for initialization data files (exit if none found)
if [[ ( -r start${numold}.nc && -r startfi${numold}.nc ) ]] ; then
\cp -f start${numold}.nc start.nc
\cp -f startfi${numold}.nc startfi.nc
else
if (( ${numold} == 99999 )) ; then
echo "No run because previous run crashed ! (99999 in num_run)"
exit
else
echo "Where is file start"${numold}".nc??"
exit
fi
fi

# Run GCM -- THIS LINE NEEDS TO BE MODIFIED WITH THE CORRECT GCM EXECUTION COMMAND
mpirun -np 8 gcm_64x48x26_phystd_para.e < diagfi.def > lrun${numnew}

# Check if run ended normaly and copy datafiles
if [[ ( -r restartfi.nc && -r restart.nc ) ]] ; then
echo "Run seems to have ended normaly"

\mv -f restart.nc start${numnew}.nc
\mv -f restartfi.nc startfi${numnew}.nc

else
if [[ -r num_run ]] ; then
\mv -f num_run num_run.crash
else
echo "No file num_run to build num_run.crash from !!"
# Impose a default value of 0 for num_run
echo 0 > num_run.crash
fi
echo 99999 > num_run
exit
fi

# Copy other datafiles that may have been generated
if [[ -r diagfi.nc ]] ; then
\mv -f diagfi.nc diagfi${numnew}.nc
fi
if [[ -r diagsoil.nc ]] ; then
\mv -f diagsoil.nc diagsoil${numnew}.nc
fi
if [[ -r stats.nc ]] ; then
\mv -f stats.nc stats${numnew}.nc
fi
if [[ -f profiles.dat ]] ; then
\mv -f profiles.dat profiles${numnew}.dat
\mv -f profiles.hdr profiles${numnew}.hdr
fi

# Prepare things for upcoming runs by writing
# value of computed season in file num_run
echo ${numnew} > num_run

# If we are over nummax : stop
if (( $numnew + 1 > $nummax )) ; then
exit
else
\cp -f run_gnome exe_mars
./exe_mars
fi

</syntaxhighlight>

'''Summary of what this bash script does''':

* It reads the file 'num_run' which contains the step of the simulation.
If num_run is
<syntaxhighlight lang="bash">
5
</syntaxhighlight>
then the script expects to read start5.nc and startfi5.nc.
* It modifies start5.nc and startfi5.nc into start.nc and startfi.nc, respectively.
* It runs the GCM.
* It modifies restart.nc and restartfi.nc into start6.nc and startfi6.nc
* It rewrite num_run as follows:
<syntaxhighlight lang="bash">
6
</syntaxhighlight>
* It restarts the loop until num_run reaches the value (defined in nummax):
<syntaxhighlight lang="bash">
100
</syntaxhighlight>

== Visualization software ==
=== Panoply ===
Panoply is a user-friendly tool for viewing raw NetCDF data, available here: https://www.giss.nasa.gov/tools/panoply/

[[File:Example panoply.png|thumb|Screenshot of panoply showing here LMD Generic results for the exoplanet TRAPPIST-1e]]

=== Planetoplot ===

Planetoplot is a in-house, python based library developped to vizualize LMDG data.

The code and documentation can be found at: https://nbviewer.org/github/aymeric-spiga/planetoplot/blob/master/tutorial/planetoplot_tutorial.ipynb

=== ncview ===
=== paraview ===
=== planetoplot ===
=== python scripts ===

The xarray python library is a very good tool to easily load and plot netcdf data.

TBD

Tool Box

2022-05-11T09:43:10Z

Jleconte: