Ludwigw95 icon docu

Documentation of ICON-NWP on jet (by serafin) and data assimilation with dwd's bacy. Put all of it in a directory named ICON-NWP

ICON-NWP/bacy.md

+bacy (short for basic cycling) 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
+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
+your local machine are necessary:
+
+    git clone git@gitlab.dkrz.de:dace/dace_bacy.git <my_bacy_name>
+    cd <my_bacy_name>/modules
+    ./copy_defaults.sh
+
+===================================================================================
+                         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
+part of each module.
+
+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 
+cannot be run. Otherwise, the module can start its work and it uses its working
+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'.
+
+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
+IMPORTANT to maintain the modular concept.
+
+In summary: to run a module stand-alone, the following steps are necessary.
+
+    prep_<module> [-h] [-d] arg1 ... argn
+    <module>      [-h] [-d] arg1 ... argn
+    save_<module> [-h] [-d] arg1 ... argn
+
+The option [-h] gives you an explanation of the usage of the script and the
+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
+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.
+
+In summary: to start an experiment, the following steps are necessary.
+
+    prep_cycle [-h]      arg1 ... argn
+    cycle      [-h] [-d] arg1 ... argn
+
+For the options [-h] and [-d] see the explanations above.
+
+-----------------------------------------------------------------------------------
+                              Default files
+-----------------------------------------------------------------------------------
+
+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.
+
+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?
+===================================================================================
+
+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
+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'
+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.
+
+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'.