esm_runscripts package¶
Top-level package for ESM Runscripts.
Submodules¶
esm_runscripts.cli module¶
A small wrapper that combines the shell interface and the Python interface
esm_runscripts.compute module¶
Class to hold compute jobs and recipe steps
-
class
esm_runscripts.compute.
compute
(config)[source]¶ Bases:
esm_runscripts.jobclass.jobclass
-
static
initialize_experiment_logfile
(config)[source]¶ Initializes the log file for the entire experiment.
Creates a file
${BASE_DIR}/${EXPID}/log/${EXPID}_${setup_name}.log
to keep track of start/stop times, job id numbers, and so on. Use the functionwrite_to_log
to put information in this file afterwards.The user can specify
experiment_log_file
under thegeneral
section of the configuration to override the default name. Timestamps for each message are given by the sectionexperiment_log_file_dateformat
, or defaults toTue Mar 17 09:36:38 2020
, i.e."%c"
. Please usestftime
compatable formats, as described here: https://strftime.orgParameters: dict – The experiment configuration Returns: As per convention for the plug-in system; this gives back the entire config. Return type: dict Attention
Calling this has some filesystem side effects. If the run number in the general configuration is set to 1, and a file exists for
general.exp_log_file
; this file is removed; and re-initialized.
-
static
esm_runscripts.database module¶
esm_runscripts.database_actions module¶
esm_runscripts.esm_batch_system module¶
-
exception
esm_runscripts.esm_batch_system.
UnknownBatchSystemError
[source]¶ Bases:
Exception
Raise this exception when an unknown batch system is encountered
esm_runscripts.esm_coupler module¶
esm_runscripts.esm_methods module¶
esm_runscripts.esm_sim_objects module¶
Documentation goes here
-
class
esm_runscripts.esm_sim_objects.
SimulationSetup
(command_line_config=None, user_config=None)[source]¶ Bases:
object
-
compute
(kill_after_submit=True)[source]¶ All steps needed for a model computation.
Parameters: kill_after_submit (bool) – Default True
. If set, the entire Python instance is killed with asys.exit()
as the very last after job submission.
-
esm_runscripts.filelists module¶
esm_runscripts.jobclass module¶
-
class
esm_runscripts.jobclass.
jobclass
(job_type, recipe_steps=None)[source]¶ Bases:
object
-
static
assemble_log_message
(config, message, message_sep=None, timestampStr_from_Unix=False)[source]¶ Assembles message for log file. See doc for write_to_log
-
filetype_specific_dict
= {}¶
-
relevant_files
= []¶
-
static
write_to_log
(config, message, message_sep=None)[source]¶ Puts a message into the experiment log file
Parameters: - message (list) – A list of the message elements; which is joined by either (highest
to lowest): 1) the message_sep argument passed to the method, 2)
The user’s chosen seperator, as written in
self.config["general"]["experiment_log_file_message_sep"]
, 3) An empty space" "
. - message_sep (None) – The hard-coded message seperator to use; which ignores user choices.
Note
The user can control two things regarding the logfile format:
- The datestamp formatting, whjich is taken from the config
section
general.experiment_log_file_dateformat
. - The message seperators; taken from
general.experiment_log_file_message_sep
. Note that if the programmer passes amessage_sep
argument; this one wins over the user choice.
- message (list) – A list of the message elements; which is joined by either (highest
to lowest): 1) the message_sep argument passed to the method, 2)
The user’s chosen seperator, as written in
-
static
esm_runscripts.namelists module¶
esm-runscripts
Core Plugins for dealing with Fortran Namelists.
Provides plugins for loading, modifying, deleting, and writing Fortran
Namelists as part of the esm-runscripts
recipe. All plugins are found under
the class Namelist as static methods. A deprecated class namelist
(small “n”) is
provided, which warns you when it is used.
-
class
esm_runscripts.namelists.
Namelist
[source]¶ Bases:
object
Methods for dealing with FORTRAN namelists
-
static
nmls_finalize
(mconfig)[source]¶ Writes namelists to disk after all modifications have finished.
User Information
Part of the main log output will be a section specifing the actual namelists that have been used for your simulation, including all relevant additions, removals, or changes.
Programmer Information
A copy of the f90nml object representations of the namelists is stored under the dictionary key “namelist_objs”, as a dictionary of (“namelist_name”, f90nml_objfect) key/value pairs.
Warning
Removing this step from your recipe might result in a broken run, as the namelists will not be present in their desired form! Even if your model runs, it might not contain all user-required changes.
Parameters: mconfig (dict) – The model (e.g. ECHAM, FESOM, NEMO or OIFS) configuration Returns: mconfig – The modified configuration. Return type: dict
-
static
nmls_load
(mconfig)[source]¶ Loads Fortran namelists into the configuration dictionary.
User Information
To associate namelists with a specific model, you should have a section in your configuration that lists the namelists:
fesom: namelists: - "namelist.config" - "namelist.oce" - "namelist.ice" - "namelist.diag"
Programmer Information
The namelists are represented by f90nml Namelist objects, and are stored under:
mconfig["namelists"]["namelist.echam"]``
This would point to the ECHAM namelist as a f90nml object, which closely resembles a dictionary.
The actual namelists to load are listed in the raw configuration as a list of strings:
mconfig['namelists'] = ['nml1', 'nml2', 'nml3', ...]
Namelists are assumed to have been copied to
mconfig["thisrun_config_dir"]
, and are loaded from there.If the
mconfig
has a key"namelist_case"
equal to “uppercase”, the uppercase attribute of the f90nml representation of the namelist is set toTrue
.Parameters: mconfig (dict) – The model (e.g. ECHAM, FESOM, NEMO or OIFS) configuration Returns: mconfig – The modified configuration. Return type: dict
-
static
nmls_modify
(mconfig)[source]¶ Performs namelist changes.
User Information
In the configuration file, you should have a section as:
echam: namelist_changes: namelist.echam: radctl: co2vmr: 1200e-6
This would change the value of the echam namelist (namelist.echam), subsection radctl, entry co2vmr to the value 1200e-6.
Programmer Information
IDEA(PG): Maybe we can provide examples of how these functions are used in the code?
Note
Actual changes are performed by the f90nml package patch fuction. See here: https://tinyurl.com/y4ydz363
Parameters: mconfig (dict) – The model (e.g. ECHAM, FESOM, NEMO or OIFS) configuration Returns: mconfig – The modified configuration. Return type: dict
-
static
nmls_remove
(mconfig)[source]¶ Removes an element from a namelist chapter.
User Information
In the configuration file, assume you have:
echam: namelist_changes: namelist.echam: radctl: co2vmr: "remove_from_namelist"
In this case, the entry co2vmr would be deleted from the radctl section of namelist.echam.
Programmer Information
IDEA(PG): Maybe we can provide examples of how these functions are used in the code?
Parameters: mconfig (dict) – The model (e.g. ECHAM, FESOM, NEMO or OIFS) configuration Returns: mconfig – The modified configuration. Return type: dict
-
static
-
class
esm_runscripts.namelists.
namelist
(*args, **kwargs)[source]¶ Bases:
esm_runscripts.namelists.Namelist
Legacy class name. Please use Namelist instead!
esm_runscripts.oasis module¶
esm_runscripts.sadfile module¶
esm_runscripts.slurm module¶
Contains functions for dealing with SLURM-based batch systems
-
class
esm_runscripts.slurm.
Slurm
(config)[source]¶ Bases:
object
Deals with SLURM, allowing you to check if a job is submitted, get the current job ID, generate a srun hostfile, get the current job state, and check if a job is still running.
-
filename
¶ The filename for srun commands, defaults to
hostfile_srun
Type: str
-
path
¶ Full path to this file, defaults to
thisrun_scripts_dir / filename
Type: str
Parameters: config (dict) – The run configuration, needed to determine where the script directory for this particular run is. -
static
check_if_submitted
()[source]¶ Determines if a job is submitted in the currently running shell by checking for
SLURM_JOB_ID
in the environmentReturns: Return type: bool
-