Using the ExtData component

MAPL_ExtDataGridCompMod is an internal MAPL gridded component used to fulfill imports fields in a MAPL hierarchy from netcdf files on disk. It is usually one of the three gridded components in the cap or main program of a MAPL application, the others being the root of the MAPL hierarchy it is servicing and MAPL_HistoryGridCompMod. It is instanciated and all its registered methods are run automatically by the CAP. MAPL_ExtDataGridCompMod will provide data to fields in the Import states of MAPL components that are not satisfied by a MAPL_AddConnectivity call in the MAPL hierarchy. In a MAPL application fields added to the Import state of a component are passed up the MAPL hierarchy looking for a connectivity to another component that will provide data to fill the import. If a connectivity is not found these fields will eventually reach the cap. At this point any fields that have not have their connectivity satisfied are passed to the MAPL_ExtDataGridCompMod through its Export state. MAPL_ExtDataGridCompMod is in essence a provider of last resort for Import fields that need to be filled with data. The graphic below illustrates this point.

The user provides a resource file available to the MAPL_ExtDataGridCompMod GC. At its heart this resource file provides a connection between a field name and a variable name in a netcdf file on disk. The component receives a list of fields that need to be filled and parses the resource file to determine if MAPL_ExtDataGridCompMod can fill a variable of that name. We will refer to each field name-file variable combination as a primary export. Each primary export is an announcment that MAPL_ExtDataGridCompMod is capable of filling a field named A with data contained in variable B on file xyz. Note that the field name in each primary export does not need to actually be a field that needs to be filled by the model. The component only processes primary exports that are needed The resource file should be viewed as an anncountment of what MAPL_ExtDataGridCompMod can provide. In addition to simply announcing what MAPL_ExtDataGridCompMod can provide the user can specify other information such as how frequently to update the data from disk. This could be at every step, just once when starting the model run, or at a particular time each days. MAPL_ExtDataGridCompMod also allows data to be shifted and scaled.

The ExtData.rc file itself can have up to 3 parts. The first is the primary exports. The example below is an example of a primary export block. This may have as many entries as the user desires.

PrimaryExports::
# ---------|---------|-----|-----|------|----------------------|--------|-------|---------------------------------|-----------------------------------------------------------|
#  Export  |         |     | V   |      |_______ Refresh ______|____ Factors ___|________ External File __________|______________________External File Time Data______________|
#  Name    | Units   | Dim | Loc | Clim |     Time Template    | Offset | Scale | Variable |      Template        |  Refference Time   | File Frequency Unit | File Frequency |
# ---------|---------|-----|-----|------|----------------------|--------|-------|----------|----------------------|--------------------|---------------------|----------------|
ALBNF           NA      xy    c      N             0               0.0      1.0     ALBNF    myfile.%y4%m2%d2.nc4   2000-04-15T00:00:00           days               1
du001           NA      xyz   c      N             0               0.0      1.0     du001    /dev/null
::

The following is an explanation of each entry in a line.

Export Name - This is the actual name of the export in the application to fill

Units - Units not currently used

Dimensions - xy for 2D or xyz for 3D

Vertical location - c for center, e for edge, if 2d enter c or e but this will obviously not be used

Clim - enter Y if the file is a climatology file, otherwise enter no.

Refresh template - you have 3 choices

1.) Enter '-'. In this case the field will only be updated once the first time ExtData runs

2.) Enter a refresh template of the form %y4-%m2-%h2T%h2:%n2:00 to set the recurring time to update the file. For example to update the file once a day at 21Z enter %y4-%m2-%d2T21:00:00 to update the file the first of the month at 21Z enter %y4-%m2-01T21:0000