View source for 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 [http://yaml.org 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.

<syntaxhighlight lang=yaml>
%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
</syntaxhighlight>

=== 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.
:<syntaxhighlight lang=yaml>
input_items: []

output_items:
- air__temperature
</syntaxhighlight>

;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.
:<syntaxhighlight lang=yaml>
input_items:
- air__temperature

output_items: []
</syntaxhighlight>

;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,
:<syntaxhighlight lang=yaml>
input_files:
- tank_info.cfg
</syntaxhighlight>

== 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. 

<syntaxhighlight lang=text>
dt         = 1.0
n_steps    = 20
init_depth = 2.0
top_area   = 100.0
out_radius = 1.0
rain_file  = rain_data.txt
</syntaxhighlight>

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. 

<syntaxhighlight lang=yaml>
%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}
</syntaxhighlight>

=== 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 [http://www.unidata.ucar.edu/software/udunits/udunits-2/udunits2.html UDUNITS] string