Instructions for adding a BMI to a model

From CSDMS

Currently, these are only (very) loose notes gathered from discussions with Mariela, Scott, and Eric.

Standard names

What variables will your model accept as input, and provide as output? Consult the list of standard names. However, don't use standard names in the input file for your model! (I'm trying to work around this, however.)


Metadata

After you've added a BMI to a model, you'll need to create a set of BMI metadata files. These files are used by CSDMS software engineers to transform the model into a CSDMS plug-and-play component. There are typically four files:

  1. api.yaml: describes how to build the model
  2. info.yaml: gives author information and a description of the model
  3. parameters.yaml: lists all input parameters for the model, as well as their type, range, and default value
  4. <your_model_input_file>.tmpl: a template input file for the model, with {variables} from parameters.yaml in place of parameter values

These files should be placed in a directory named .bmi at the root of your repository.

Use CamelCase for the component name in api.yaml. For example, "FrostNumberModel", not "Frost_Number_Model". Don't forget the initialize_args attribute in api.yaml -- it's used by PyMT to know what file the component's initialize method takes as an argument.

Take care to validate the YAML used for these files.

For examples, see the .bmi directory in https://github.com/csdms/bmi-live-2016.

Units

Parameters should be described with standard units. CSDMS uses the UDUNITS package developed by Unidata. UDUNITS follows the syntax for unit strings developed by NIST.

The UDUNITS manual has some useful information, especially Section 4.3, "What Gets Installed?", which lists the actual XML files used by UDUNITS. This I've found most useful -- on a machine where UDUNITS is installed, I've grepped these files for unit definitions.

Time

CSDMS has traditionally used days, d, for time units. Years, yr, are also used. We should really move to the SI standard of seconds, s.

Model time should start at 0.0. Scott argues that we should allow the option of calendar-based time.

The CSDMS Bakery and Farm

We use Anaconda Cloud to host built distributions of componentized models and tools. There are two channels, csdms (https://anaconda.org/csdms) and csdms-stack (https://anaconda.org/csdms-stack). The csdms channel (aka The Farm) is used for development builds of components, usually based on the master branch of the component's repository. The csdms-stack channel (aka The Bakery) is used for release builds of components. The recipes in this channel should be tied to a particular release of the component. (Think of The Bakery as the stable channel.)

The Farm is really only used for development and testing. The Bakery is public-facing.

Retrieved from "https://csdms.colorado.edu/csdms_wiki/index.php?title=Instructions_for_adding_a_BMI_to_a_model&oldid=226977"