Experiment configuration scripts
Summary
Once you have managed to run a test case, you may want to run your own experiment. The model configuration, diagnostics, and simulation parameters
of your experiment can be configured with a python-based run script.
Find the test case in Isca/exp/test_cases that most resembles your experiment, copy and modify it. The important lines are described below.
Setup
from isca import DryCodeBase
imports the Isca python module that should have been installed.
DryCodeBase refers to the part of the code needed to run the dry model. The codebase object is defined in Isca/src/extra/python/isca/codebase.py. The different default codebases are designed to avoid the model compiling un-needed parts of the code, which speeds up compilation. DryCodeBase can be replaced by IscaCodeBase, GreyCodeBase, or SocratesCodeBase (provided you setup Socrates, see Socrates documentation).
NCORES = 16
specifies how many cores should be used when running the model.
RESOLUTION = T42, 25
specifies the horizontal (in this case, spectral T42) and vertical (25 pressure levels)
resolution. Runs at T42 by default. If the horizontal resolution is not T42, make sure the
input files (such as land masks) are changed and add exp.set_resolution(*RESOLUTION) after exp is defined.
Other common spectral resolutions are T21 and T85.
cb = DryCodeBase.from_directory(GFDL_BASE)
tells Isca to find the model code at the location GFDL_BASE, which is where the source code may be changed. You can replace from_directory(GFDL_BASE) with from_repo(repo='https://github.com/isca/isca', commit='isca1.1') to point to a specific git repository and commit id. This should ensure future, independent, reproducibility of results. But, the compilation depends on computer specific settings. The $GFDL_ENV environment variable is used to determine which $GFDL_BASE/src/extra/env file is used to load the correct compilers. The env file is always loaded from $GFDL_BASE and not the checked out git repo.
cb.compile()
compiles the source code.
exp = Experiment('EXPERIMENT_NAME', codebase=cb)
creates an experiment object which will handle the configuration of model parameters and output diagnostics. The output files will be found at $GFDL_DATA/EXPERIMENT_NAME.
Diagnostics
diag = DiagTable()
creates a DiagTable object which we can configure to tell Isca which variables to output.
diag.add_file('atmos_monthly', 30, 'days', time_units='days')
creates an atmos_monthly.nc file every 30 days, which is an average of the output over the previous 30 days. The output files can be found at $GFDL_DATA/EXPERIMENT_NAME/run####/*.
diag.add_field(MODULE_NAME, VARIABLE_NAME, time_avg=True)
determines which fields will be written in atmos_monthly.nc. Find the available VARIABLE_NAMEs by going to the MODULE_NAME documentation or by finding the relevant source code (cd Isca/src/ & find . -name "MODULE_NAME*").
Namelist
namelist = Namelist({...})
defines a namelist object, which lets us configure the science options.
It is only necessary to set values that are different from the default parameters, which are defined
in the relevant module documentation (for example, atmosphere_nml parameters can be found in the atmosphere
module documentation or at the beginning of the atmosphere.F90 source file).
Running the experiment
exp.run(...)
will make the model run for the amount of time specified in main_nml (usually 30 days).
The use_restart option can be set to False to start from scratch (isothermal atmosphere) or can point to a restart file (use_restart = $GFDL_DATA/exp_name/run####/restarts/*) to initialize the run from the output of a previous run. If unspecified, it will start from where the previous run left off or from an isothermal atmosphere in the absence of a previous run.
Output
Output from the experiment can be found at $GFDL_DATA/EXP_NAME. The atmospheric output is provided on
sigma levels where sigma is the pressure normalized by the surface pressure. For a planet with no topography, sigma and pressure levels are quite similar.
If there is topography present (such as in the realistic_continents test case), you need to interpolate the
data onto pressure levels before analyzing it. Top of atmosphere and surface values are not affected, but in-atmosphere values are.
The details and code for interpolation to pressure levels can be found at https://github.com/ExeClim/Isca/tree/master/postprocessing/plevel_interpolation
In the python code, there is a convenient function which can be used to call the interpolation code: https://github.com/ExeClim/Isca/blob/master/src/extra/python/isca/util.py (line 134).
For example:
from isca.util import interpolate_output
for run in ["EXPERIMENT_NAME"]:
print(run)
for i in range(121, 241):
try:
infile = '/data_directory/' + run + '/run%04d/atmos_monthly.nc' % i
outfile = '/data_directory/' + run + '/run%04d/plev_monthly.nc' % i
interpolate_output(infile, outfile, p_levs='EVEN', var_names=['slp', 'height'])
except:
print(i)