This page describes low-level modules in the hwrf package. These modules do not implement the HWRF itself, instead they implement common functionality missing from the Python standard library specific to the way the hwrf is designed. Their purpose is to simplify the rest of the hwrf package by collecting commonly reoccurring code into functions or base classes.
Module hwrf.config: Configuring HWRF
The hwrf.config module contains the HWRFConfig class, a wrapper around the Python ConfigParser, with additional support for inserting time and tcvitals data, logging, connection to a produtil.datastore.Datastore and tracking of produtil.datastore.Task objects. Every HWRF job has exactly one of these HWRFConfig objects, and uses it to configure every HWRFTask and many other aspects of the system. The HWRFConfig also allows one to configure just about every aspect of the HWRF system from a single config file. (Except those related to the POM ocean model, which has hard-coded information in the scripts in the pom package.)
Module hwrf.hwrftask: Executing HWRF Components
The HWRFTask class, a subclass of produtil.datastore.Task, allows HWRF components to store internal state information in a database, and communicate it between jobs. Each task also has a set of Product objects to describe files it delivers. This allows easy addition of new delivery locations and methods from a high-level script, such as emailing the track file or launching an NCEP DBNet alert, without having to edit the hwrf modules themselves. In addition, every HWRFTask is connected to a config section in an HWRFConfig object, providing ways to easily get configuration options without having to read a file each time.
Module hwrf.exceptions: Exceptions Thrown By hwrf
This module contains nearly all Exception subclasses that are specific to the hwrf package. Only hwrf.storminfo and hwrf.revital contain their own exceptions, for backward compatibility to external scripts. Note that the hwrf package may also raise exceptions from the standard library or the pom or produtil packages. Frequently, hwrf uses TypeError to indicate parameters have the wrong type, or KeyError to complain of invalid keys (such as asking for WRF domain 4 when only three domains exist). The number of exceptions is quite large, so the reader is directed towards the docstring documentation. However, the module defines a tree of exception classes, so calling code only needs to be aware of the higher-level classes unless very specific error handling is desired.
Module hwrf.numerics: Time and Numerics Utilities
This module defines a number of numerical utilities to simplify the rest of the hwrf package. The hwrf package performs a large amount of date and time manipulation to, for example, compute file output names based on WRF timestep settings or determine the valid time of a forecast hour, given its analysis time. The Python standard library can be used to do all of this work, but results in very verbose code. This module provides utilities to simplify that code. In addition, there are a number of non-time-related utilities to perform simple numerical computing tasks such as, for example, computing the great arc length between two points.
There are two classes defined in this package that bear further mentioning:
hwrf.numerics.TimeArray – an array-like object that maps an equally spaced list of times each to an object.
hwrf.numerics.TimeMapping – an object that acts similar to the standard library map class, but mapping times to an object. Times within some epsilon of a known time are treated as that time.
Module hwrf.namelist: Fortran Namelist Utilities
This module contains code to generate Fortran namelists from in-memory Python objects. It knows how to convert certain Python objects, such as strings or datetime.datetime to a fortran namelist expression of the same, and back again. The hwrf package this module to generate namelists from the parm/hwrf.conf file in the Experiment Layer. There are two classes in this module that are generally useful outside of it: NamelistInserter and Conf2Namelist. The NamelistInserter implements a simple, but limited, way of converting conf data to Fortran namelist syntax, and inserting it into a pre-written template file. The Conf2Namelist is more sophisticated, and generates an in-memory representation of a Fortran namelist, purely from reading HWRFConfig data. It allows one to automatically variables, or whole sections, before writing the file. One can also query a Conf2Namelist to get namelist settings. That allows, for example, the post and wps scripts to analyze the WRF namelist.
class NamelistInserter
This class, given a file, or a multi-line string, finds angle bracket (<vartype:stuff>) strings with values from aHWRFConfig section. This is the suggested method for namelists with very few configurable items. Here is an example. Suppose this text is in an input file "mynamelist.nml.in":
&mynamelistdomid=<i:domid>size_meters=<r:msize>/
The i:domidr:msize inserts a real from the msize option. See the Python docstring for a full list of possibilities. Suppose you have this conf section, in an HWRFConfig object called conf:
[myconf]
domid=2
msize=12.4e3
Then this code will insert the domid and msize into the specified locations and write to the "mynamelist.nml" file:
with open("mynamelist.nml.in",'rt') as f:
nmlin=NamelistInserter(conf,"myconf")
nmlin.parse(f)
Producing this output:
&mynamelistdomid=2size_meters=12.4e3/
class Conf2Namelist
The Conf2Namelist does not use an input file, and instead generates a namelist purely from the conf sections. It keeps all information in memory in Python data structures, allowing one to query or modify them as needed. This allows one to examine the namelist file, and modify it to run the same program multiple ways. It also allows one to insert new sections and variables into the Conf2Namelist before generating a namelist file. That allows automatic generation of sections of the namelist, hence avoiding manual insertion of error-prone portions of the namelist. In addition, the Conf2Namelist is able to merge multiple Conf2Namelist objects, to append vectors together. For example, one could make a Conf2Namelist for WRF domain 1, and a second Conf2Namelist for domain 2, and then join them generate a combined Conf2Namelist with array data for namelist variables that have data in both the domain 1 and 2 Conf2Namelist objects.
This class is the one that the hwrf.wrf and hwrf.wrfbase modules use to generat the WRF namelist.input file. Those modules fill in all variables related to WRF I/O, domain bounds, communication, and timekeeping automatically before generating the namelist.input, but allow the user to manually specify other options, such as physics schemes. Each domain reads in its information into a Conf2Namelist, and the result is joined to make a single Conf2Namelist that generates the final namelist.input file. Since the file's information is in memory in a Conf2Namelist object, the hwrf.fcsttask module can copy the Conf2Namelist and make a slightly modified version to, for example, run the wrfanl or ghost jobs, which require minor namelist differences. It also allows the post, wps and other components of the HWRF system to query such things as output frequency or physics scheme choices by querying the in-memory version of the actual namelist.
See the Conf2Namelist docstring documentation for detailed documentation and examples.
Module hwrf.constants: Constants and "Constants"
The hwrf.constants module contains a variety of constants, as well as things that are not constant, but are generally treated as such. See the Python docstring documentation for details.