Setting Up MAPL Automatic Code Generator

Overview

The MAPL MAPL Automatic Code Generator (ACG) is a utility to allow the user specify certain bits of "boilerplate" 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 obfuscate 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 essential generates the code above into an include file you can then include in your component.

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)