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