=====
Usage
=====
arpsEnKFtools is a work in progress. Some features may not be working and there are
likely many bugs. It is helpful to first take a look at the directory structure:
.. raw:: html
arpsEnKFtools
├── arpsenkftools
├── docs
├── legacy
├── notebooks
├── plotting_scripts
├── prep_scripts
├── radremap_scripts
├── template
└── utility_scripts
For now, we will focus on just a few of these directories. The project structure is
changing quickly and some of these directories may be renamed or removed altogether.
Pay attention to this documentation.
The ``arpsenkftools/`` subdirectory contains code for editing the FORTRAN namelist files
and generating batch scripts for the HPC system as well as several utility functions.
The ``prep_scripts/`` directory contains several scripts to generate the needed input
data and configuration files, as well as to generate the main working directory for a
given ARPS-EnKF experiment:
.. raw:: html
prep_scripts
├── link_lookup_tables.py
├── link_nam.py
├── link_radremap.py
├── radarinfo.dat
├── run_arpsintrp.py
├── run_arpssfc.py
├── run_arpstrn.py
├── run_ext2arps.py
├── run_radremap.py
├── run_wrf2arps.py
└── setup_experiment_working_dir.py
Before getting into their function, we note that each of the ``run_.py``,
as well as the ``link_.py`` and ``setup_experiment_working_dir.py`` take one
command line argument each. This command line argument is the path to a python configuration
file for a given experiment, typically named ``master_config.py``. Several examples are
in the ``template/`` subdirectory. This directory contains subdirectories with descriptive
names of a particular experiment that contain template input files and a ``master_config.py``
script. The various driver scripts in the ``prep_scripts/`` directory import the configuration
in ``master_config.py`` for that experiment, and uses the template's namelist input files for
the purpose of running one of the preparation programs. For example, the directory
``template/3km153x153_051913_OK_NAM/`` contains the template for a small 3-km domain centered
on central OK for the 19 May 2013 tornadic supercell case. the ``_NAM`` in the name signifies
that it uses the NAM model forecast/analyses as the initial and boundary conditions. The
directory tree for this template looks like this:
.. raw:: html
3km153x153_051913_OK_NAM
├── 2013_0519.radflag
├── arps.input
├── arpsenkf.input
├── arpsenkfic.input
├── arpsintrp.input
├── arpssfc.input
├── arpstrn.input
├── blacklist.sfc
├── ext2arps.input
├── master_config.py
├── plotCRM_control_3km153x153_dBZ_w_zvort.py
├── plotCRM_control_3km153x153_pte_dBZ.py
├── radremap_88D.input
├── run_real_data_case.sh
└── wrf2arps.input
If you are familiar with the ARPS model ecosystem, you will recognize many of the
``*.input`` files as being FORTRAN namelist files that control various programs. At this
point it is a good idea to open up the ``master_config.py`` file. This file sets various
parameters, including the paths to various input, output, and executable files.
There are several dictionaries encapsulating namelist input parameters that will be
copied into the template namelist input files to control the behavior of the different programs.
These include grid and map projection parameters, frequency of boundary conditions, number of
cores for MPI jobs, parameters controlling the behavior of the EnKF assimilation, and so on.
As a quick example, to run the program ``arpstrn`` that generates the terrain file for the
ARPS domain, you would do the following on the command line, assuming you are starting in
the root directory of the repository::
$ cd prep_scripts
$ python run_arpstrn.py ../template/3km153x153_051913_OK_NAM/master_config.py
This will create a working directory, copy ``arpstrn.input`` into it, automatically edit
it with the appropriate parameters as defined in ``master_config.py`` and finally execute
``arpstrn``. Output from the program will be placed in a directory that is also specified
in ``master_config.py``.
Similarly, one would also run ``ext2arps`` to generate the initial and boundary conditions
as follows::
$ python run_ext2arps.py ../template/3km153x153_051913_OK_NAM/master_config.py
The use of a single ``master_config.py`` as input for these scripts greatly simplifies
what otherwise would be a difficult and error-prone workflow by ensuring that each program
that is needed to orchestrate a full experiment is working with the same experiment structure.
This, among other things, obviates the need to manually edit several namelist input files and
manually having to keep track of the same parameters across them.
TODO: continue documentation to explain the other prep scripts and then on to the main
experiment script. Watch this space!