# Appendix

0. [Quickstart: imsi for CanESM users](#quick)
1. [Comparing commands](#comparing_commands)
2. [Glossary](#glossary)


## 0. Quickstart: `imsi` for CanESM users

To access the `imsi` virtual environment:

```bash
$ load_imsi_latest
```

To do an out-of-the-box run with on-off changes to configuration:

| | `setup-canesm` | `imsi` |
| -- | -- | -- |
| Simple workflow |<pre>  $ setup-canesm repo=${repo} ver={ver} \ <br>      config=${config} runid=${runid} <br>  $ cd $runid <br>  $ source env_setup_file <br>#### edits to canesm.cfg ####<br>  $ config-canesm <br>  $ compile-canesm.sh <br>  $ save_restart_files <br>  $ expbegin -e $SEQ_EXP_HOME -d YYYYddmm <br></pre>| <pre>  $ imsi setup --repo=${repo} --ver=${ver} \ <br>      --model=${model} --exp=${exp} --runid=${runid} <br>  $ cd ${runid} <br>  <br> #### edits to imsi_configuration-${runid}.yaml ####<br>  $ imsi config  <br>  $ imsi build  <br>  $ imsi save-restarts  <br>  $ imsi submit  <br></pre> |

## 1. Comparing commands <a name="comparing_commands" />

| Action | `setup-canesm` | `imsi` |
|:--- |:--- | --- |
| Setup a run directory | <pre>$ setup-canesm \ <br>    repo=git@gitlab.science.gc.ca:CanESM/CanESM5.git \  <br>    ver=v6.0-rc1.1 \ <br>    fetch_method=clone \ <br>    config=ESM  \ <br> <br>   runid=setup-test-01 </pre> | <pre>$  imsi setup \ <br>   --repo=git@gitlab.science.gc.ca:CanESM/CanESM5.git \ <br>   --ver=v6.0-rc1.1 \ <br>   --fetch_method=clone \  <br>   --model=CanESM6-0-rc1-MR_p1 \ <br>   --exp=CanESM6-0-rc1-MR_cmip6-piControl \ <br>   --runid=imsi-test-01 </pre> `imsi` `--model` is similar to `setup-canesm` `config`, `imsi` `--exp` is similar to the `runmode` in `canesm.cfg`|
| Source the "run environment" | <pre>$ source env_setup_file | <pre>$ source config/shell_parameters </pre> Not required for using `imsi` commands. |
| Reload the configuration | No function available; this would be equivalent to overwriting the `canesm.cfg` in the setup directory from `CanESM/CONFIG/` and doing the manipulations of `setup-canesm` | <pre>$ imsi reload |
| Edit the configuration locally | Modifications to `canesm.cfg` | Modifications to `imsi_configuration_${runid}.yaml`. |
| Create/apply the configuration | `$ config-canesm` | `$ imsi config` <br> This operation is already executed within `imsi setup` and `imsi reload`, but needs to be done again if modifications were made in `imsi_configuration_${runid}.yaml` |
| Compile the models + tools | `$ compile-canesm.sh` | `$ imsi build` |
| Save the restart | `$ save_restart_files` | `$ imsi save-restarts` |
| Launching the simulation | Use `expbegin` or open maestro with `xflow` and submit | `$ imsi submit` <br> You can also use `xflow` directly (export `SEQ_EXP_HOME` manually, or initiate `xflow` from the `${runid}/sequencer` directory. |
| CanESM5 repository location | `CanESM_source_link/` or `CanESM/`  | `src/` |
| Monitoring a simulation | Look in `sequencer/sequencing/status/` or open maestro with `xflow` |  <pre>$ imsi status</pre>You can also use `xflow` directly, as described above. |
| Clean a run |  <pre>clean-run -s -t -d $runid </pre> | <pre>imsi clean -s -t -d --runid_path $runid <br>imsi clean -a --runid_path $runid  # -a for "all"</pre>`$runid` should be the entire path to the **Run Setup Directory** |

## 2. Glossary <a name="glossary" />

Here is some helpful terminology used in this training (in conceptual order):

| Token | Term  | Definition       | Note |
|:-- | :--|:------------------| :-- |
| `setup-canesm` | "**Setup-CanESM**" | The CanESM configuration system used before imsi that use a *flat* configuration file, `canesm.cfg`. The configuration system was based on the concept of "runmode". | In imsi, "runmodes" are replaced by `model` + `experiment`. |
| `imsi` | imsi | IMSI ( /ɪm.ziː/ ) is the Integrated Modelling System Infrastructure, a comprehensive Python-based package developed by the CCCma. IMSI is a tool that can be used to help access, configure, build, and run suites of models. | While the focus of this tutorial is CanESM-specific, imsi is generic! It has been developed to be a workhorse for other modelling systems. |
| `${runid}` | **Run Setup Directory** | Directory produced by the execution of `imsi setup` and name `{runid}/` that contains all the requirements to run a simulation. Defined as `${WRK_DIR}` in the run environment (shell_parameters). | `${runid}` as a folder reflects the name of the `pwd`; through this tutorial, it is interchangeable with the (old) env variable `${WRK_DIR}`. |
| <pre>imsi_<br>configuration_<br>${runid}.yaml</pre> | **Resolved Configuration File** | The `imsi_configuration_{runid}.yaml` contains all configuration specification for the run. It's contents are formed from the **imsi Configuration Files** based on the **Setup Parameters** and is used in the construction of the **Run Configuration Directory** (`$runid/config`) and sequencing directory (`$runid/sequencing`). |  This file is editable by the user to make one-off changes to a run (use `imsi config`). |
| `${runid}/config` | **Run Configuration Directory** | The namelist, scripts, executables, and environment variables derived from the **Resolved Configuration File**. | The contents can be changed under several workflows and with several commands, notably `imsi config`, as well as `imsi reload` and `imsi set` |
| `${runid}/sequencing` | **Run Sequencing Directory** | Files, logs and source scripts used by the sequerncer derived from the **Resolved Configuration File**. | The contents can be changed under several workflows and with several commands, notably `imsi config`, as well as `imsi reload` and `imsi set` |
| `${runid}/src` | **Run source directory** | `CanESM5` repository that contains all the models codes, scripts and the imsi configuration files. | This can either be a *link* or a *copy* of an existing repository on disk or a *clone* of the remote CanESM5 repository. That depends on the choice made when setting up a run (e.i. `fetch_method=`). |
| `setup_params` | **Setup Parameters** | User arguments passed to `imsi setup` (or `imsi set`) that define key choices in run configuration. This includes specifying the model (`model`), experiment (`exp`), and run ID (`runid`), among other parameters. | Check `imsi setup -h` for documentation of the setup parameters. | |
| `imsi-config` | **imsi Configuration Files** | The collection of `yaml` files that are located in `imsi-config` folder. Taken together, these files define all possible configurations. | Once the source repository (`repo`) is obtained, these files are located under `${runid}/src/imsi-config`, and can be modified for development using the `imsi reload` workflow. |


Simple schematic of information flow:

```text
imsi-config ->  (imsi cmd)  ->  imsi_configuration_$runid.yaml  ->  /config
                (+ params)                                          /sequencer
```
