Dev: Simulation Cycle

Each component is able to perform a simulation by dividing it into discrete phases: preperation, work, and cleanup. In turn, these phases are divided into steps, which move files into appropriate locations, modify namelists, and ensure everything is ready for an execution. After the execution, the result outdata and restart files are moved to appropriate locations.

In principle, the “simulation cycle” looks like this:

We briefly describe what happens during each of these phases.

The Prepare Phase

During the prepare phase, the following steps are performed:

1. The default filetables are read: <Component.Name>_<Component.Version>_prepare_default_files.json.
2. Next, if it exists, a modification table is read.
3. Finally, the filetable keys are used to read from the environment and change the source of certain files.
4. These files are copied to the experiment tree
5. Any modifications are performed that may be needed. Here, you should implement things that might modify namelists, or perform hotfixes on restart files

Note that before and after each of these steps, users may attach self-defined methods. The image above only gives the “short” names of the methods (with the exception of change_from_env, this is actually called override_filetables_from_env, but that wouldn’t fit in the image). The full names always take the form _prepare_<method short name>. All of these steps are performed if the method prepare is called on an object that inherits from ComponentCompute:

>>> from random_clouds.random_clouds_simulation import RandomCloudsCompute
>>> computable_clouds = RandomCloudsCompute(*args)  # Note that *args should be something appropriate.
>>> computable_clouds.prepare()
>>> # Calling computable_clouds._prepare_read_filetables()
>>> # Calling computable_clouds._prepare_modify_filetables()
>>> # Calling computable_clouds._prepare_override_filetables_from_env()
>>> # Calling computable_clouds._prepare_copy_files_to_exp_tree()
>>> # Calling computable_clouds._prepare_modify_files()

The Work Phase

The work phase by default does the following steps:

1. Copies files from the experiment tree to the work folder
2. Modifies files in the work folder if needed
3. Modifies namelists in the work folder if needed

In the basic ComponentCompute case, only the first step actually does any work. Modification of files and namelists needs to be implemented specifically for each component.

Attention

Currently, copying of files into work directory pops off the files from the dictionary, since after the work phase, the cleanup phase loads new dictionaries into ComponentCompute.files, thus after this step the file dictionaries are empty.

As before, if the work phase is called, this would happen:

>>> from random_clouds.random_clouds_simulation import RandomCloudsCompute
>>> computable_clouds = RandomCloudsCompute(*args)  # Note that *args should be something appropriate.
>>> computable_clouds.work()
>>> # Calling computable_clouds._work_copy_files()
>>> # Calling computable_clouds._work_modify_files()
>>> # Calling computable_clouds._work_modify_namelists()

The Cleanup Phase

The cleanup phase consists of a single step, moving files from the work folder to the outdata and restart directories, and setting appropriate names. A new filetable is read <Component.Name>_<Component.Version>_cleanup_default_files.json:

Calling the cleanup method would look like this:

>>> from random_clouds.random_clouds_simulation import RandomCloudsCompute
>>> computable_clouds = RandomCloudsCompute(*args)
>>> computable_clouds.cleanup()
>>> # Calling computable_clouds._cleanup_copy_files()

Here, certain strings are replaced, as was described in the previous section. The rules for these replacements are contained in a small csv file, which can be unique to each component. If you need any specific replacements, you can add them to the list. The current replacement rules are summarized in the table:

String Interpolation during Cleanup

string	replacement
@EXPID@	self.expid
@NAME@	self.Name
@DATE@	self.calendar
@LRES@	self.LateralResolution
@VRES@	self.VerticalResolution

Next, we will work through designing a SetUp object, which controls the simulation of several connected Components

---

Previous: Dev: File Tables

Next: Dev_06