BMI Model Metadata

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
--- !<tag:csdms.edu,2012:model>
name: Water_Tank_Model
author: Scott Peckham
version: 0.1
url: "https://csdms.colorado.edu"

input_files: 
- tank_info.cfg

output_items:
- 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

input_items:
- atmosphere_water__liquid_equivalent_precipitation_rate
- atmosphere_water__precipitation_duration

Required Elements

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

name

Name of the model as a string.

author

Comma-separated list of model author or authors.

version

Version of the component as major.minor[.micro].

input_items

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: []

output_items:
- air__temperature

output_items

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.

input_items:
- air__temperature

output_items: []

input_files

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,

input_files:
- 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
--- !<tag:csdms.edu,2012:file>
name: tank_info.cfg
brief: Initialization file for water tank model

parameters:
  time_step:
    brief: Model time step
    units: s
    range: 0., 1.
    default: 1.
  n_steps:
    brief: Number of time steps
    description: Total number of model time steps to take for the simulation
    units: 1
    range: 1, 1000
    default: 20
  init_depth:
    brief: Initial water depth
    units: m
    range: 0., 10.
    default: 2.
  top_area:
    brief: Inlet area
    description: Cross-sectional area of the top of the water tank
    units: m^2
    range: 0., 100.
    default: 1.
  outlet_radius:
    brief: Outlet radius
    units: m
    range: 0., 100.
    default: 1.
  rain_file:
    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

Name of the input file. This used as an identifier that refers to the list of input files in the model.yaml file.

parameters

List of parameter elements that describe parameters in the input file.

template_file

template_string

Either a file name (template_file) or the contents of a template file (template_string) for the described input file.

Required Parameter Elements

brief

Short description of the model parameter

default

A default value for the paramter

units

If a numeric parameter, parameter units as a UDUNITS string