Skip to content

Setting Up MAPL Automatic Code Generator

Jump to bottom
Ben Auer edited this page Mar 18, 2024 · 20 revisions

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 an include file you can then include in your component.

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:

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.

YAML

This will be implemented in the future.

Edit source code.

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)
Clone this wiki locally