Multiple nudging-forcing files¶
The default IPSL-CM-LAM example uses a single input file with nudging-forcing data, called nudging_forcing.nc.
However, we can imagine a configuration where variables are diveded in a per-month fashion, each in a separate file.
Such multi-file setup is very common, as is in the case of ERA5 data.
The configuration of multiple nudging-forcing files is simple and it requires only two steps:
- Tell MODIPSL where to find our files
- Tell XIOS in which file a given variable is.
Let's start!
Configuring MODIPSL¶
Paths to nudging files are defined under the List key in the [BoundaryFiles] section of the COMP/dynamico.card file.
The standard LAM with ERA5 experiment uses only one nudging_forcing.nc file:
[BoundaryFiles]
List=(${R_IN}/ATM/FORCING_LAM/${config_UserChoices_ForcingName}_${config_UserChoices_ForcingDate}.nc, nudging_forcing.nc)
This file is copied from the source path (on the left) to the target file (on the right).
The source path can be parametrized, like in the example above, where config_UserChoices_<VAR> variables are taken from the [UserChoices] section of the main config.card.
There is also a set of time-related variables, like ${month} or ${year}.
Machine-specific directory with standard input files
The ${R_IN} variable is machine-specific and it points to, de-facto, a standard directory with data.
You can investigate it, by looking into the source code of libIGCM.
This is what the revision 1703 of libIGCM has to tell us:
> grep R_IN= libIGCM_sys -r | sed -E 's/.*sys_([^.]*)\.ksh.*(R_IN:=.*)}.*/\1 has \2/'
mesoipsl has R_IN:=/projsu/igcmg/IGCM
irene has R_IN:=/ccc/work/cont003/igcmg/igcmg/IGCM
irene-amd has R_IN:=/ccc/work/cont003/igcmg/igcmg/IGCM
default has R_IN:=/home_local/${LOGIN}/IGCM
jeanzay has R_IN:=/gpfswork/rech/psl/commun/IGCM
obelix has R_IN:=/home/orchideeshare/igcmg/IGCM
The target specifies the final name of the file in the $RUN_DIR directory.
It is either a completely new file name, like nudging_forcing.nc, or . which leaves the source filename intact.
The file renaming is important for multi-period simulations, e.g. month-by-month simulation, because the XIOS configuration
only operates on fixed file names, like r.nc or u.nc.
If the nudging file has time-parametrized name, similar to u_${year}_${month}.nc, in the end, it must be renamed to u.nc just for XIOS.
Use case: separated variable files¶
In this example of COMP/dynamico.card, files are stored in the directory ForcingDataDir defined in the [UserChoices] section of the main config.card.
Each file contains data for a specific variable, year and month, but in the end for each simulation period, the files get a fixed file name with just the variable name.
[BoundaryFiles]
-List=(${R_IN}/ATM/FORCING_LAM/${config_UserChoices_ForcingName}_${config_UserChoices_ForcingDate}.nc, nudging_forcing.nc)
+List=(${config_UserChoices_ForcingDataDir}/q_${year}_${month}.nc, q.nc), \
+ (${config_UserChoices_ForcingDataDir}/r_${year}_${month}.nc, r.nc), \
+ (${config_UserChoices_ForcingDataDir}/sp_${year}_${month}.nc, sp.nc), \
+ (${config_UserChoices_ForcingDataDir}/t2m_${year}_${month}.nc, t2m.nc), \
+ (${config_UserChoices_ForcingDataDir}/t_${year}_${month}.nc, t.nc), \
+ (${config_UserChoices_ForcingDataDir}/u_${year}_${month}.nc, u.nc), \
+ (${config_UserChoices_ForcingDataDir}/v_${year}_${month}.nc, v.nc), \
+ (${config_UserChoices_ForcingDataDir}/z_${year}_${month}.nc, z.nc)
Watch out for list formatting in *.card files
Watch out for any white-spaces at the end of each list row, because they disturb
the libIGCM parsing capabilities and usually they cut the list in half.
If you get an error, while running the simulation, saying that you are missing some files
it is highly possible that the list of files in *.card file is ill-formatted.
Configuring XIOS¶
In the XIOS configuration, by default, the nudging_forcing.nc file holds all the required forcing variables.
In a multi-file setup, we need to establish new connections between variable definitions and their corresponding files where they are stored in.
We need to do that in two places:
context_dynamico.xml- file groupread_files_ERA5_forcingholds definitions of variables used during the creation of the initial statenudging_dynamico.xml- filesnudging_inandnudging_in0define variables used for the forcing during the simulation.
Why are there two nudging_in file definitions?
Great question! One represents the current time step (nudging_in) while the other represents the previous time step (nudging_in0). Their difference (nudging_in - nudging_in0) forms the forcing values fed to the model.
Use case: separated variable files¶
We continue the previous example of per-variable multi files with forcing data.
Conceptually, all XIOS definitions using nudging_forcing.nc file need to be divided, so that each variable can be assigned to its own file.
Modifying context_dynamico.xml¶
Here,the <file_group> with id read_files_ERA5_forcing must be modified.
Previously, there was one <file> definition pointing to the nudging_forcing.nc file specified with the name attribute.
However, after the division, now each variable is defined within its own <file> tag and with the same attributes as previously (domain_ref, mode, operation, output_freq, time_counter_name, type).
For example, variable with the name sp (surface pressure) and field ID of ps_db_forcing is now stored in the <file name="sp" ...> tag, meaning XIOS will look for it in the sp.nc NetCDF file.
<file_group id="read_files_ERA5_forcing" enabled="false">
- <file name="nudging_forcing" type="one_file" mode="read" output_freq="1000y" time_counter_name="time">
- <field id="relief_db_forcing" name="z" domain_ref="domain_relief" operation="once">this/9.81</field>
-
- <field_group domain_ref="domain_ecdyn" operation="once">
- <field id="ps_db_forcing" name="sp" />
- <field id="z_db_forcing" name="z" />
- <field id="ts_db_forcing" name="t2m" />
- <field_group axis_ref="lev_ecdyn_read">
- <field id="u_db_forcing" name="u" />
- <field id="v_db_forcing" name="v" />
- <field id="temp_db_forcing" name="t" />
- <field id="q_db_forcing" name="r" />
- </field_group>
- </field_group>
- </file>
+ <file name="Relief" type="one_file" mode="read" output_freq="10ts">
+ <field id="relief_db_forcing" name="RELIEF" domain_ref="domain_relief" operation="instant" />
+ </file>
+ <file name="z" type="one_file" mode="read" output_freq="1000y" time_counter_name="time">
+ <field id="z_db_forcing" name="z" domain_ref="domain_ecdyn" operation="once" />
+ </file>
+ <file name="sp" type="one_file" mode="read" output_freq="1000y" time_counter_name="time">
+ <field id="ps_db_forcing" name="sp" domain_ref="domain_ecdyn" operation="once" />
+ </file>
+ <file name="t2m" type="one_file" mode="read" output_freq="1000y" time_counter_name="time">
+ <field id="ts_db_forcing" name="t2m" domain_ref="domain_ecdyn" operation="once" />
+ </file>
+ <file name="u" type="one_file" mode="read" output_freq="1000y" time_counter_name="time">
+ <field id="u_db_forcing" name="u" domain_ref="domain_ecdyn" axis_ref="lev_ecdyn_read" operation="once" />
+ </file>
+ <file name="v" type="one_file" mode="read" output_freq="1000y" time_counter_name="time">
+ <field id="v_db_forcing" name="v" domain_ref="domain_ecdyn" axis_ref="lev_ecdyn_read" operation="once" />
+ </file>
+ <file name="t" type="one_file" mode="read" output_freq="1000y" time_counter_name="time">
+ <field id="temp_db_forcing" name="t" domain_ref="domain_ecdyn" axis_ref="lev_ecdyn_read" operation="once" />
+ </file>
+ <file name="r" type="one_file" mode="read" output_freq="1000y" time_counter_name="time">
+ <field id="q_db_forcing" name="r" domain_ref="domain_ecdyn" axis_ref="lev_ecdyn_read" operation="once" />
+ </file>
</file_group>
It is worth pointing out, that the relief_db_forcing field is now read from the Relief.nc file which is a standard practice giving better accuracy of the terrain height over ERA5 geopotential.
The Relief.nc file is usually defined in the COMP/lmdz.card as:
Modifying nudging_dynamico.xml¶
In this file, we apply the same modifications to two <file> tags with IDs nudging_in and nudging_in0.
As previously, we make sure that each variable is defined in its own <file> tag, while copying all previously used attributes (axis_ref, cyclic, domain_ref, enabled, grid_ref, mode, operation, output_freq, record_offset, time_counter_name), thus, creating a link for XIOS, so that it knows in which file each variable is.
-<file id="nudging_in" name="nudging_forcing" output_freq="1h" mode="read" record_offset="1"
-time_counter_name="time" cyclic="true">
-<field_group operation="instant" freq_offset="1ts">
- <field id="ps_nudged_read" name="sp" domain_ref="domain_nudged" />
- <field_group domain_ref="domain_nudged" axis_ref="axis_nudged_read">
- <field id="p_nudged_read" name="pressure" enabled="false" />
- <field id="ulon_nudged_read" name="u" />
- <field id="ulat_nudged_read" name="v" />
- <field id="temp_nudged_read" name="t" />
- <field id="H2O_g_nudged_read" name="q" />
- <field id="H2O_l_nudged_read" name="clwc" />
- <field id="H2O_s_nudged_read" name="ciwc" />
- <field id="H2O_b_nudged_read" name="cbwc" enabled="false" />
- </field_group>
- <field id="q_nudged_read" name="q" grid_ref="grid_q_nudged" enabled="false" />
-</field_group>
-</file>
-<file id="nudging_in0" name="nudging_forcing" output_freq="1000y" mode="read"
-record_offset="0" time_counter_name="time">
-<field_group operation="once" freq_offset="1ts">
- <field id="ps_nudged_read0" name="sp" domain_ref="domain_nudged" />
- <field_group id="fields_vert_nudging_read0" domain_ref="domain_nudged"
- axis_ref="axis_nudged_read">
-
- <field id="p_nudged_read0" name="pressure" enabled="false" />
- <field id="ulon_nudged_read0" name="u" />
- <field id="ulat_nudged_read0" name="v" />
- <field id="temp_nudged_read0" name="t" />
- <field id="H2O_g_nudged_read0" name="q" />
- <field id="H2O_l_nudged_read0" name="clwc" />
- <field id="H2O_s_nudged_read0" name="ciwc" />
- <field id="H2O_b_nudged_read0" name="cbwc" enabled="false" />
-
- </field_group>
- <field id="q_nudged_read0" name="q" grid_ref="grid_q_nudged" enabled="false" />
-</field_group>
-</file>
+<file_group output_freq="1h" mode="read" record_offset="1" time_counter_name="time" cyclic="true">
+ <file name="sp">
+ <field id="ps_nudged_read" name="sp" domain_ref="domain_nudged" operation="instant" freq_offset="1ts" />
+ </file>
+ <file name="pressure">
+ <field id="p_nudged_read" name="pressure" enabled="false" domain_ref="domain_nudged" axis_ref="axis_nudged_read" operation="instant" freq_offset="1ts" />
+ </file>
+ <file name="u">
+ <field id="ulon_nudged_read" name="u" domain_ref="domain_nudged" axis_ref="axis_nudged_read" operation="instant" freq_offset="1ts" />
+ </file>
+ <file name="v">
+ <field id="ulat_nudged_read" name="v" domain_ref="domain_nudged" axis_ref="axis_nudged_read" operation="instant" freq_offset="1ts" />
+ </file>
+ <file name="t">
+ <field id="temp_nudged_read" name="t" domain_ref="domain_nudged" axis_ref="axis_nudged_read" operation="instant" freq_offset="1ts" />
+ </file>
+ <file name="q">
+ <field id="H2O_g_nudged_read" name="q" domain_ref="domain_nudged" axis_ref="axis_nudged_read" operation="instant" freq_offset="1ts" />
+ <field id="q_nudged_read" name="q" grid_ref="grid_q_nudged" enabled="false" operation="instant" freq_offset="1ts" />
+ </file>
+ <file name="cbwc">
+ <field id="H2O_b_nudged_read" name="cbwc" enabled="false" domain_ref="domain_nudged" axis_ref="axis_nudged_read" operation="instant" freq_offset="1ts" />
+ </file>
+</file_group>
+<file_group output_freq="1000y" mode="read" record_offset="0" time_counter_name="time">
+ <file name="sp">
+ <field id="ps_nudged_read0" name="sp" domain_ref="domain_nudged" operation="once" freq_offset="1ts" />
+ </file>
+ <file name="pressure">
+ <field id="p_nudged_read0" name="pressure" enabled="false" domain_ref="domain_nudged" axis_ref="axis_nudged_read" operation="once" freq_offset="1ts" />
+ </file>
+ <file name="u">
+ <field id="ulon_nudged_read0" name="u" domain_ref="domain_nudged" axis_ref="axis_nudged_read" operation="once" freq_offset="1ts" />
+ </file>
+ <file name="v">
+ <field id="ulat_nudged_read0" name="v" domain_ref="domain_nudged" axis_ref="axis_nudged_read" operation="once" freq_offset="1ts" />
+ </file>
+ <file name="t">
+ <field id="temp_nudged_read0" name="t" domain_ref="domain_nudged" axis_ref="axis_nudged_read" operation="once" freq_offset="1ts" />
+ </file>
+ <file name="q">
+ <field id="H2O_g_nudged_read0" name="q" domain_ref="domain_nudged" axis_ref="axis_nudged_read" operation="once" freq_offset="1ts" />
+ <field id="q_nudged_read0" name="q" grid_ref="grid_q_nudged" enabled="false" operation="once" freq_offset="1ts" />
+ </file>
+ <file name="cbwc">
+ <field id="H2O_b_nudged_read0" name="cbwc" enabled="false" domain_ref="domain_nudged" axis_ref="axis_nudged_read" operation="once" freq_offset="1ts" />
+ </file>
+</file_group>
Why disabled fields are kept?
Three fields p_nudged_read, q_nudged_read, and H2O_b_nudged_read (and their versions with 0 suffix) are disabled by attribute enabled="false", but they are still kept in the configuration.
The reason is that those fields are used in other parts of the XIOS configuration, namely in the definition of interpolation, and removing them requires removing all the dependent definitions as well which is cumbersome.
Without them XIOS would thrown an error.
Removing variables¶
It is not possible to remove any nudging variable, as all of them are required by the ICOSA_LMDZ driver.
However, it is possible to give them 0 value directly without including a NetCDF file.
Check the "set liquid clouds and ice to 0" recipe to find more!