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
instructs the NamlistInserter to insert an integer from its conf section's "domid" option. The i:domid
r: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.