Overview

MAPL_ExtDataGridCompMod is one of several specialized components provided by the MAPL library. It is used to fulfill imports fields in a MAPL hierarchy of components from NetCDF files containing gridded, geospatial data 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 instantiated 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. Like other components, it has a run method that gets called every step in your MAPL application. What actually happens when it is run is determined by the resource file. The component can be used to provide a centralized way to provide external, time-varying data to MAPL components such as chemical and aerosol emissions and forcings like sea surface temperature.

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 being delivered to Extdata and a variable name in a NetCDF file on disk. The component receives a list of fields that need to be supplied with data and parses the resource file to determine if MAPL_ExtDataGridCompMod can supply a variable of that name. We will refer to each field name-file variable combination as a primary export of ExtData. Each primary export is an announcement 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 announcement of what MAPL_ExtDataGridCompMod can provide, not what it necessarily will 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 and how the data is organized. This update could be at every step, just once when starting the model run, or at a particular time each days. It also allows tremendous flexibility as to how the user chooses to organize the data files. MAPL_ExtDataGridCompMod also allows data to be shifted, scaled, and control what method is used to regrid the file to the application grid.

ExtData Resource File

The ExtData resource file can have 2 types of entries, a Primary Export section and a Derived Export section.The file itself is processed sequentially so that it can have any number of Primary, Derived. Each of these sections is a list of single line entries. Each entry describes how to supply a variable of a given name with data. The tables currently use %% instead of the standard :: identifiers because of an odd behaviour in ESMF. The first table the user can define is a PrimaryExports table. Below is an example of a PrimaryExport table. This may have as many entries as the user desires. Note that only the last entry in a line is optional.

PrimaryExports%%
# ---------|---------|-----|-----|------|------------ |----------------------|--------|-------|------------------------------------|-----------------------------------------------------------|
#  Export  |         |     | V   |      |             |_______ Refresh ______|____ Factors ___|________ External File _____________|______________________External File Time Data______________|
#  Name    | Units   | Dim | Loc | Clim |Conservative |     Time Template    | Offset | Scale | Variable |      Template           |  Reference Time and frequency                             |
# ---------|---------|-----|-----|------|------------ |----------------------|--------|-------|----------|-------------------------|-----------------------------------------------------------|
ALBNF           NA         N        N               0                0.0      1.0     ALBNF     myfile.%y4%m2%d2_%h2z.nc4   2000-04-15T00:00:00P03:00
du001           NA         N        N               0                0.0      1.0     du001     /dev/null
%%