This is a small guide on how to use bacy to run assimilation cycles in practice.
## Prerequisites
Before running you need:
* a path to a directory containing a bacy with initial conditions for your experiment
* a icon gridfile, a radiation gridfile and extpar-Data. You can create these using the `icongridgenerator`
* a icon gridfile, a radiation gridfile and extpar-Data. You can create these using the `icongridgen`
or via the [web](https://webservice.dwd.de/cgi-bin/spp1167/webservice.cgi) interface at DWD (user icon-web, pw: icon@dwd).
* a working bacy, cloned eihter from [`git@gitlab.dkrz.de:dace/dace_bacy.git`](./bacy.md#How to get BACY_1.0?) or from another bacy using `bacy_clone.sh`
* a working bacy, cloned eihter from [`git@gitlab.dkrz.de:dace/dace_bacy.git`](./bacy.md#markdown-header-how-to-get-bacy_1.0?) or from another bacy using `bacy_clone.sh`
## Running bacy
To run cycles you need to go to to the `cycle` module: `bacy/modules/cycle/`. There you can find the scripts `prep_cycle` and `cycle`.
### Running `prep_cycle`
To initialize bacy run `prep_cycle` in the `cycle` directory. The script describes itself like this:
~~~
SCRIPT for preparing a data assimilation cycle
USAGE: ./prep_cycle [-h] model mode frombacypath startdate
- '-h': help (optional)
- 'model': ICON|COSMO|ICON-LAM
- 'mode': ASS|MAIN|SUPP|URDA|CLIMA
- 'frombacypath': path from which bacy experiment to start the cycle
- 'startdate': format yyyymmddhhmmss|yyyymmddhh
- 'enddate': format yyyymmddhhmmss|yyyymmddhh
(only for mode MAIN|SUPP|URDA)"
DESCRIPTION: serves as preparation of script 'cycle';
links all module relevant input data for a given start date (as specified by
'startdate') from an existing bacy experiment (as specified by 'frombacypath')
into its own cycling directory tree (also containing 'data', 'feedback' and
'veri' subdirectories, but only with initial time-stamp subfolders);
~~~
So you can call it like:
~~~
./prep_cycle ICON-LAM ASS /hpc/path/to/initial/conditons/bacy/ 2023112812
~~~
This will prepare a cycle with the ICON large area model in assimilation mode with initial condition from `/hpc/path/to/initial/conditons/bacy/` starting at the 28.11.2023 - 12 UTC.
### Running `cycle`
After prearation you can run the cycle by calling `cycle` with similar arguments. The script describes itself like this:
- '-d': dry run (does not submit any long-time jobs)
- '--cycle' : from which cycle to resume work (requires a number)
- '--task' : from which task to resume work (requires a number)
- '--subtask': from which subtask to resume work (requires a number)
arguments:
- 'model': ICON|COSMO|ICON-LAM
- 'mode': ASS|MAIN|VERI|VERIENS|SUPP|URDA|CLIMA
- 'startdate': start of bacy experiment (format yyyymmddhhmmss|yyyymmddhh)
- 'enddate' : end of bacy experiment (format yyyymmddhhmmss|yyyymmddhh)
Creating the file 'STOP_CYCLE' in the 'cycle' directory will interrupt
all running cycles. To continue the experiment delete the file and restart
the cycle(s) or run the 'RESTART_CYCLE_*' script(s)'.
DESCRIPTION: Depending on mode, the scripts runs specific cycles:
ASS: a data assimilation cycle by calling the modules 'core',
'more', 'sst', 'sma', 'snow', and 'mec'(COSMO) in the correct order
MAIN: long forecasts (building upon an ASS cycle)
VERI: mec for deterministic verification against observations
(building upon a MAIN cycle)
VERIENS: mec for ensemble verification against observations
(building upon a MAIN cycle)
SUPP: supplemental assimilation of a previous cycle
(building upon an ASS cycle)
URDA: an ultra rapid data assimilation cycle
CLIMA: climate data assimilation cycle with ICON-SML
~~~
So you can call it like:
~~~
./cycle ICON-LAM ASS 2023112812 2023112912
~~~
This will start a cycle prepared above going from the 28.11.2023 - 12 UTC until the 29.11.2023 - 12 UTC.
#### Using `nohup`
For longer experiments you wankt to be able to leave the command shell and let the cycles take care of its own. To do so, you can start the process using [`nohup`](https://linux.die.net/man/1/nohup):
~~~
nohup ./cycle ICON-LAM ASS 2023112812 2023112912 &> cycle.log &
~~~
This will start the process in the background, writing its output to the file `cycle.log`.
*Pro Tip*: You can read the output using `less`. While in `less` press `SHIFT + F` to read it like a feed. To exit this mode press `CTRL + C` and then `q` to exit `less`.
### Interrupting and Restarting the cycle
To interrupt a cycle you can create a file named `STOP_CYCLE` (eg. `touch STOP_CYCLE`) in the `cycle` directory. After completion of the current step, the cycle will break.
To restart a interrupted cycle at any of the past times, delete `STOP_CYCLE` and use the flags `--cycle` and `--task` of the `cycle` script. For example
~~~
./cycle --cycle=5 --task=7 ICON-LAM ASS 2023112812 2023112912
~~~
restarts the former cycle at 28.11.2023 - 16 UTC, at the 7th task, which is the `core` module (assimilation).
