Setting Up MAPL Automatic Code Generator - GEOS-ESM/MAPL GitHub Wiki

Overview

The MAPL MAPL Automatic Code Generator (ACG) is a utility to allow the user specify certain bits of "boilerplate" code common in MAPL gridded components in an external text file. This text file is then parsed to generate include files the user can include in their component. The main functionality to to specify the import/export/internal state of a component in the set services as well as provide a short to access the pointers associated with these fields and states. A component can have potential hundreds of items which make for very, very long blocks of source code, as well as obfuscating the actual computational code.

Setting up the MAPL Automatic Code Generator (ACG), consists of three steps:

  1. Create a specs file the ACG will use to generate source code
  2. Edit source code to in include the appropriate include files that will be generated
  3. Edit CMakeLists.txt.

Create a specs file.

The spec file allows the user specify the component state in the spec file, rather than in the code. In particular a properly configured spec file allows the user to replace these sorts of calls. First is the add an import/export/internal spec:

   call MAPL_AddImportSpec(GC,                                    &
   SHORT_NAME = 'V',                                         &
   LONG_NAME  = 'northward_wind',                            &
   UNITS      = 'm s-1',                                     &
   DIMS       =  MAPL_DimsHorzVert,                          &
   VLOCATION  =  MAPL_VLocationCenter,                       &
   RC=STATUS  )

This tells the component to add a field named V to the import state. Then during the run method of the component the user would want to use this field. That requires declaring a Fortran pointer of write dimensionality and retrieving the pointer from the field using our MAPL_GetPointer call. I.E.

real, pointer :: v(:,:,:)

call MAPL_GetPointer(IMPORT, v, 'V",rc=status)

If you combined import/export/internal state has several hundred fields it can become a lot of code. The ACG essentially generates the code above into several include files you can then include in your component. In general the AddVarSpecs will be in one include file, the variable declarations will be in another, and the MAPL_GetPointers, will be in yet another file.

Note that the variable declaration for the pointer, is the SAME NAME AS THE SHORT NAME. So anywhere you would use the pointer it will be the short name! So in the example above, the pointer it will declare is name v and that's what you will use in your code.

Spec File Format

CSV (Comma Separated Value)

The first way to specify the input spec file for the ACG is via CSV or comma separated value type file. The input spec file can specify all 3 component states, the import/export/internal. The file consists of a keyword to denote which of those 3 states it is, a row of entries separated by a | character whose name what that columns represents. Then a series of rows, that each specify a variable specification. For example, here how you would do the export state, thing of a each line as a MAPL_AddExportSpec, the first one for is of a field named DUMASS.

category: EXPORT
#----------------------------------------------------------------------------------------
#  VARIABLE              | DIMENSIONS  |          Additional Metadata
#----------------------------------------------------------------------------------------
 NAME          | UNITS      | DIMS | VLOC | UNGRIDDED                      | LONG NAME
#----------------------------------------------------------------------------------------
 DUMASS        | kg kg-1    | xyz  | C    |                                | Dust Mass Mixing Ratio
 DUMASS25      | kg kg-1    | xyz  | C    |                                | Dust Mass Mixing Ratio
 DUCONC        | kg m-3     | xyz  | C    |                                | Dust Mass Concentration
 DUEXTCOEF     | m-1        | xyz  | C    | size(self%wavelengths_profile) | Dust Extinction Coefficient
 DUEXTCOEFRH20 | m-1        | xyz  | C    | size(self%wavelengths_profile) | Dust Extinction Coefficient - Fixed RH=20%
 DUEXTCOEFRH80 | m-1        | xyz  | C    | size(self%wavelengths_profile) | Dust Extinction Coefficient - Fixed RH=80%
 DUSCACOEF     | m-1        | xyz  | C    | size(self%wavelengths_profile) | Dust Scattering Coefficient

Notice one annoyance about this format is that if a particular entry does not need to specify, you still must a blank entry there. For for example the first item, DUMASS has no UNGRIDDED entry, but you still must have the blank column there. Likewise, you decide something needs a new column, you have to insert a whole column.

Allowed columns

In general several columns are not option in a practical sense, in that you need to specify a name, and dimensionality etc.. Here we will enumerate all allowed columns, note that one or more columns are only applicable to specific state types (import/export/internal) and this will be noted if so.

NAME: This is the short name of the add varspec. I.E. the name the field you are adding, non-optional
UNITS: units to be added to the field
DIMS:
VLOC:
RESTART: 
LONG NAME: long name attached to the field
COND:
UNGRIDDED: 
ADD2EXPORT:
FRIENDLYTO:

YAML

This will be implemented in the future.

Edit source code.

Assuming you are converting that does not use the ACG, to code that does you must do the following. For each Spec in the specs file, remove:

  1. the MAPL_Add...Spec call.
  2. the corresponding pointer declaration.
  3. the MAPL_GetPointer call.

Edit CMakeLists.txt.

In addition to creating the Specs file, you need to modify CMakeLists.txt at the GridComp and Repository levels.

Edit GridComp CMakeLists.txt.

For each GridComp, add the following block to CMakeLists.txt in the directory that contains the GridComp source file:

mapl_acg (${this}   SPECS_FILENAME
          IMPORT_SPECS EXPORT_SPECS INTERNAL_SPECS
          GET_POINTERS DECLARE_POINTERS)

replacing SPECS_FILENAME with the name of the specs file you created. If the directory contains multiple GridComp source files, add a separate block for each GridComp source file. Each block runs the ACG and generates include files for the corresponding GridComp source file.

Edit Repository CMakeLists.txt.

At the top level directory of the Repository, add the following line to CMakeLists.txt:

include(mapl_acg)