BMI Model Metadata

Revision as of 16:00, 2 April 2013 by Huttone (talk | contribs) (Describe parameter elements)

Model Metadata

Along with an implementation of the Basic Modeling Interface, model developers are required to provide basic metadata for their model and input files. The syntax for these metadata files in the YAML format. For more information about this syntax, see the YAML website.

Model Description

A BMI component specifies metadata about itself in a file called model.yaml. The following is an example of a model.yaml file for the Water Tank example.

%YAML 1.2
--- !<,2012:model>
name: Water_Tank_Model
author: Scott Peckham
version: 0.1
url: ""

- tank_info.cfg

- model__time_step
- tank_cross_section__area
- tank_cross_section__radius
- tank_outlet__area
- tank_outlet__radius
- tank_outlet_water__flow_speed
- tank_water__depth
- tank_water__initial_depth
- tank_water__volume

- atmosphere_water__liquid_equivalent_precipitation_rate
- atmosphere_water__precipitation_duration

Required Elements

A valid model.yaml file must include the following elements:

Name of the model as a string.
Comma-separated list of model author or authors.
Version of the component as major.minor[.micro].
List of input items to the model as CSDMS standard names. This element must be present even if your model does not have input items. In such a case, the element should be an empty list.
input_items: []

- air__temperature
List of output items to the model as CSDMS standard names. This element must be present even if your model does not have output items. In such a case, the element should be an empty list.
- air__temperature

output_items: []
List of input file names our model requires. For each input file listed, there must exist a YAML description of that file whose file name is the input file name with a yaml suffix. For example, the following implies the existence of the file tank_info.cfg.yaml,
- tank_info.cfg

Input File Description

Metadata files also describe model input files using the YAML format. As an example, below is the contents of the configuration input file for the water tank model.

dt         = 1.0
n_steps    = 20
init_depth = 2.0
top_area   = 100.0
out_radius = 1.0
rain_file  = rain_data.txt

The following metadata file is an example description of this file. Metadata includes parameter descriptions, units, valid ranges and default values. In addition, there is an element (either template_string or template_file) that provides a template input file from which input file instances are created.

%YAML 1.2
--- !<,2012:file>
name: tank_info.cfg
brief: Initialization file for water tank model

    brief: Model time step
    units: s
    range: 0., 1.
    default: 1.
    brief: Number of time steps
    description: Total number of model time steps to take for the simulation
    units: 1
    range: 1, 1000
    default: 20
    brief: Initial water depth
    units: m
    range: 0., 10.
    default: 2.
    brief: Inlet area
    description: Cross-sectional area of the top of the water tank
    units: m^2
    range: 0., 100.
    default: 1.
    brief: Outlet radius
    units: m
    range: 0., 100.
    default: 1.
    brief: Name of rainfall file
    description: Name of the file containing rainfall data (if using)
    default: rain_data.txt

template_string: | 
  dt         = ${time_step}
  n_steps    = ${n_steps}
  init_depth = ${init_depth}
  top_area   = ${top_area}
  out_radius = ${outlet_radius}
  rain_file  = ${rain_file}

Required Elements

Name of the input file. This used as an identifier that refers to the list of input files in the model.yaml file.
List of parameter elements that describe parameters in the input file.
Either a file name (template_file) or the contents of a template file (template_string) for the described input file.

Required Parameter Elements

Short description of the model parameter
A default value for the paramter
If a numeric parameter, parameter units as a UDUNITS string