DART-WRF documentation

DART-WRF is a python package which allows you to

  • run the Weather Research and Forecast model (WRF),

  • generate (satellite) observations from a nature run,

  • and assimilate these observations in ensemble data assimilation using DART,

  • on a computing cluster or on your local machine.

DART-WRF was started a python version of the original DART-WRF tutorial written in csh. It is simpler to use than comparable tools, such as the autosubmit package of Barcelona Supercomputing Center, and ECMWF’s ecFlow.

Current limitations: ‘real’-mode WRF, nested domains are not supported.

Installation

No install required, just download it from the University of Vienna (gitlab.phaidra.org) or Github (github.com/lkugler/DART-WRF).

Program Structure

DART-WRF is controlled by a control script which defines a high-level workflow. The control script specifies the workflow you want to run in an experiment by calling workflow functions. For example, to assimilate observations, then initialize, and run a forecast, the control script calls the workflow functions in this order.

w = WorkFlows(cfg)
w.prepare_WRFrundir(cfg)
id = w.assimilate(cfg)
id = w.prepare_IC_from_prior(cfg, depends_on=id)
id = w.update_IC_from_DA(cfg, depends_on=id)
w.run_WRF(cfg, depends_on=id)

Workflow Functions

Workflow functions are python functions which define resource requirements and submit jobs to the queueing system. They look like this for example:

def assimilate(self, cfg, depends_on=None):
    """Calls assimilate.py

    :returns: job ID of the submitted job
    :rtype: str
    """
    path_to_script = self.dir_dartwrf_run + '/assimilate.py'
    cmd = ' '.join([self.python, path_to_script, cfg.f_cfg_current])
    id = self.run_job(cmd, cfg, depends_on=[depends_on],
                      **{"ntasks": str(cfg.max_nproc), "time": "30",
                         "mem": "110G", "ntasks-per-node": str(cfg.max_nproc), "ntasks-per-core": "1"},
                 )
    return id

In this example, assimilate.py is the task script.

Task Scripts

A task script like assimilate.py does the actual work. It is not executed right away, but only after its dependencies are met, e.g. completion of WRF forecasts. Task scripts are called with a (auto-generated) configuration file path as argument. Any parameters in the config file can be easily accessed in a task script. For example, the task script update_IC.py looks like this:

import os, sys
import netCDF4 as nc
from dartwrf.utils import Config

def update_initials_in_WRF_rundir(cfg: Config) -> None:
    """Updates wrfrst-files in `/run_WRF/` directory
    with posterior state from ./filter output, e.g. filter_restart_d01.0001
    """
    time = cfg.time  # dt.datetime

    for iens in range(1, cfg.ensemble_size+1):
        ic_file = cfg.dir_wrf_run.replace('<exp>', cfg.name
                                          ).replace('<ens>', str(iens)
                                                    )+time.strftime(initials_fmt)
        #### code omitted ####

if __name__ == '__main__':
    cfg = Config.from_file(sys.argv[1])
    update_initials_in_WRF_rundir(cfg)

That’s it. For examples of actual applications, have a look at the tutorials.

Directory Structure

The most important directories are:

  • DART-WRF home: that is the place where you clone DART-WRF to, and where you develop it.

  • WRF run directory: is the place where the temporary “run” directory of WRF is located.

  • DART run directory: same as above for DART.

  • Sim-archive: stores all data for an experiment that is not temporary, e.g. diagnostics, WRF output, DART output.

You only need to create DART-WRF home. The rest is automatically created.

Set these paths in your cluster’s config file, e.g. DART-WRF/config/jet.py.

What’s Next?

To get familiar with DART-WRF’s capabilities, please have a look at the tutorials:

  • Tutorial 1 shows you how to create observations from a nature run simulation.

  • Tutorial 2 shows you how to combine observations and prior forecasts into an analysis.

  • Tutorial 3 shows you how to run a WRF forecast with an analysis.

  • Tutorial 4 combines all steps into a single script.

Tutorials

Other helpful resources