diff --git a/ICON-NWP/bacy.md b/ICON-NWP/bacy.md index cde7a6435a39c856f70413fb553c3d1e1bb26c23..2a60d3486009e9e3642458b509cf5e243c3c40a7 100644 --- a/ICON-NWP/bacy.md +++ b/ICON-NWP/bacy.md @@ -1,17 +1,19 @@ -bacy (short for basic cycling) is a collection of scripts that run assimilation +bacy (short for ***ba***sic ***cy***cling) is a collection of scripts that run assimilation cycles with ICON. It is modular in structure with each module performing steps like computing the dynamical model evolution (more), data assimilation (core), surface, snow and sea surface analysis. # BACY_1.0 + This document gives you a short introduction into the usage of BACY_1.0. A detailed userguide and further documentation is available at -'git@gitlab.dkrz.de:dace/dace_doc.git' under dace_doc/org/dace_bacy.git +`git@gitlab.dkrz.de:dace/dace_doc.git` under dace_doc/org/dace_bacy.git and is continuously being updated. ## How to get BACY_1.0? -BACY_1.0 is under version control using 'git'. To obtain BACY_1.0 from the -remote repository 'git@gitlab.dkrz.de:dace/dace_bacy.git' the following steps on + +BACY_1.0 is under version control using `git`. To obtain BACY_1.0 from the +remote repository `git@gitlab.dkrz.de:dace/dace_bacy.git` the following steps on your local machine are necessary: ~~~ git clone git@gitlab.dkrz.de:dace/dace_bacy.git <my_bacy_name> @@ -20,25 +22,27 @@ cd <my_bacy_name>/modules ~~~ ## How to use BACY_1.0? (Overview) + ### Modules + BACY_1.0 pursues a MODULAR CONCEPT. Each MODULE is an self-sufficient unit. The only contact points to its environment are realized by INTERFACES. -These are the directories 'iodir/input' and 'iodir/output' which are +These are the directories `iodir/input` and `iodir/output` which are part of each module. -The 'prep_<module>' and 'save_<module>' scripts take care of PROVIDING the +The `prep_<module>` and `save_<module>` scripts take care of PROVIDING the module with input data from and of STORING its output data to a central place, respectively. In this way the COMMUNICATION between modules is realized. -Unless the 'input' directory is not filled with input data, the module itself +Unless the `input` directory is not filled with input data, the module itself cannot be run. Otherwise, the module can start its work and it uses its working -directory 'run'. +directory `run`. The behaviour of a module can be controlled via its INPUT ARGUMENTS during the <module> script call and via its PARAMETERS defined in the configuration file -'<module>_conf.sh'. Parametes which are needed by more than one module are -outsourced to the COMMON configuration file 'common/bacy_conf.sh'. +`<module>_conf.sh`. Parametes which are needed by more than one module are +outsourced to the COMMON configuration file `common/bacy_conf.sh`. -For a more detailed module-setup please read 'modules/module/README'. This +For a more detailed module-setup please read `modules/module/README`. This module is a dummy module and serves as TEMPLATE to help you to create your own modules. In particular, in its README file you can find some valuable hints which rely on NAMING CONVENTIONS, classification of variables, etc., which are @@ -56,9 +60,10 @@ option [-d] calls the script in a dry-run, meaning that no jobs will be submitted. ### A cycle -The module 'cycle' plays a special role and cannot be understood as a module in -the usual sense (see above). The main difference is the absence of the 'input', -'output' and 'run' directories. The purpose of 'cycle' is the provision of an + +The module `cycle` plays a special role and cannot be understood as a module in +the usual sense (see above). The main difference is the absence of the `input`, +`output` and `run` directories. The purpose of `cycle` is the provision of an environment in which the order of individual module calls can be controlled. Thus, this is the central place to arrange all modules to set up an experiment. @@ -69,36 +74,32 @@ In summary: to start an experiment, the following steps are necessary. For the options [-h] and [-d] see the explanations above. ------------------------------------------------------------------------------------ - Default files ------------------------------------------------------------------------------------ +### Default files -The configuration files '<module>_conf.sh' as well as namelists and job +The configuration files `<module>_conf.sh` as well as namelists and job scripts are not under version control. Instead we use default-files, e.g., -'<module>_conf.sh.default'. This has the advantage that subsequent calls of -'git pull' will not change the current configuration. +`<module>_conf.sh.default`. This has the advantage that subsequent calls of +`git pull` will not change the current configuration. -The script 'copy_defaults.sh' creates the normal files from the default +The script `copy_defaults.sh` creates the normal files from the default versions. This must be done whenever you clone a fresh BACY from the repository! -=================================================================================== - How to make your own developments on BACY_1.0? -=================================================================================== +## How to make your own developments on BACY_1.0? -The BACY_1.0 MAIN DEVELOPMENT BRANCH is called 'bacy-dev'. This branch provides +The BACY_1.0 MAIN DEVELOPMENT BRANCH is called `bacy-dev`. This branch provides the BACY_1.0 REFERENCE which has to be the BASIS for ALL users! Only a few -people can push to 'bacy-dev' to keep this branch away from accidental or not +people can push to `bacy-dev` to keep this branch away from accidental or not quality proven commits. If you want to contribute to a NEW FEATURE for BACY_1.0, first of all create a -new branch <project>-<feature>-<team>, which you can setup as 'remote' +new branch <project>-<feature>-<team>, which you can setup as `remote` to share results inside your team. -During your development it is IMPORTANT to regularly pull from the 'bacy-dev' -branch to keep your 'basic' BACY_1.0 up to date. +During your development it is IMPORTANT to regularly pull from the `bacy-dev` +branch to keep your `basic` BACY_1.0 up to date. Once you have FINISHED your contribution and you have tested, tested and again tested your work and you are sure that you match all naming conventions for BACY_1.0 (see above), then you are ready to contact one person responsible -which merges (together with you) your contribution into 'bacy-dev'. +which merges (together with you) your contribution into `bacy-dev`.