CSN MMF Example

    CSDMS Standard Names — Model Coupling Metadata File Examples

• Model Coupling Metadata (MCM) files are a relatively new addition to the CSDMS Standard Names that is being developed as part of the EarthCube Earth System Bridge project. Their primary purpose is to capture metadata, especially model assumptions in a standardized way that can be used to determine the "goodness" of matches between components that provide a given variable and components that use that variable. The current, tentative list of CSDMS Assumption Names that can be specified with an <assume> tag can be found at: CSDMS Assumption Names.

• The example given below may be viewed as a scoping exercise or prototype and is a work in progress.

• MCM files also contain enough information to make it possible to automatically implement several of the BMI functions, including: get_input_var_names(), get_output_var_names(), get_attribute(), get_var_type() and get_var_units().

• While the tag to start an XML comment actually has an exclamation point after the "<", it has been removed on this page so the wiki does not interpret them as comments and hide them.

• If multiple units or ranks are supported for a variable (often by setting flag in the model's configuration file), then list them, separated by semicolons in the <units> or <rank> tag.

• The <option_group> tag is used when a model provides multiple methods for doing something. The "type" attribute of the <option_group> tag is then set to one of the following standard strings: "select_one", "select_none_or_more" or "select_one_or_more". In the example below, the model supports two methods for computing channel speed due to flow resistance, the law of the wall and Manning's equation.

<model>

<-- =========================== -->
<--  Model Information -->
<-- =========================== -->
<author> Scott D. Peckham </author>
<name> TopoFlow - Channels: Kinematic Wave </name>
  
<grid_type> uniform </grid_type>
<time_step_type> fixed </time_step_type>
<ellipsoid> none </ellipsoid>

<-- =========================== -->
<--  Model Assumptions -->
<-- =========================== -->
<assume> kinematic_wave_model </assume>
<assume> d8_flow_routing_model </assume>
<assume> no_overbank_flow </assume>
<assume> cartesian_coordinate_system </assume>

<-- =========================== -->
<--  An Option Group -->
<-- =========================== -->
<option_group type = "select_one" name = "flow_resistance_method" default="">
    <option>
        <assume> law_of_the_wall </assume>
        <input_var name = "channel_bottom__roughness_length" internal_name = "z0" units="m"> </input_var>
  
        <output_var>
            <name> channel_bottom__max_over_domain_of_roughness_length </name>
            <units> m </units>
        </output_var> 
  
        <output_var>
            <name> channel_bottom__min_over_domain_of_roughness_length </name>
            <units> m </units>
        </output_var>
  
        <output_var>
            <name> channel_bottom__roughness_length </name>
            <units> m </units>
        </output_var>
    </option>
  
    <option>
       <assume> manning_equation </assume>
       <input_var name = "manning_coefficient" internal_name="manning_n" units="m-1/3 s"> </input_var>
  
       <output_var> 
            <name> channel_bottom__manning_coefficient </name>
            <units> m-1/3 s </units>
        </output_var>
  
        <output_var>
            <name> channel_bottom__max_over_domain_of_manning_coefficient </name>
            <units> m-1/3 s </units>
        </output_var>
  
         <output_var>
             <name> channel_bottom__min_over_domain_of_manning_coefficient </name>
             <units> m-1/3 s </units>
         </output_var>
  
   </option>
</option_group>

<-- =========================== -->
<--  Object Assumptions -->
<-- =========================== -->
<object name='channel'>
    <assume> 1d </assume>
    <assume> prism_shaped </assume>
</object>
 
<object name='channel_cross-section'>
    <assume> trapezoid_shaped </assume>
</object>
 
<object name='channel_water' >
    <assume> mass_conserved </assume>
    <assume> momentum_conserved </assume>
    <assume> incompressible_fluid </assume>
    <assume> newtonian_fluid </assume>
    <assume> depth_integrated_flow </assume>
    <assume> hydrostatic_flow </assume>
    <assume> nonaccelerating_flow </assume>
    <assume> turbulent_flow </assume>
</object>
 
<object name='channel_bottom_sediment'>
   <option_group type="select_one">
       <option>
        <assume> gravel </assume>
       </option>
  
       <option>
        <assume> sand </assume>
       </option>
    </option_group>
</object>

<var_group>
<type> float64 </type>

<-- =========================== -->
<--  Input Variables -->
<-- =========================== -->
  
<input_var>
    <name> atmosphere_water__liquid_equivalent_precipitation_rate </name>
    <units> m s-1 </units>
</input_var>
  
<input_var>
    <name> glacier_ice__melt_rate </_name>
    <units> m s-1 </units>
    <min> 0 </min>
</input_var>
  
<input_var>
    <name> land_snow__melt_rate </name>
    <units> m s-1 </units>
    <min> 0 </min>
</input_var>
  
<input_var>
    <name> land_surface__elevation </name>
    <units> m </units>
    <assume> hydrologically_sound </assume>
</input_var>
  
<input_var>
    <name> land_water__baseflow_emergence_rate </name>
    <units> m s-1 </units>
    <asssume> nonnegative </assume>
</input_var>
  
<input_var>
    <name> land_water__evaporation_rate </name>
    <units> m s-1 </units>
</input_var>
  
<input_var>
    <name> land_water__infiltration_rate </name>
    <units> m s-1 </units>
</input_var>

<-- =========================== -->
<--  Output Variables -->
<-- =========================== -->
  
<output_var>
    <name> channel_bottom_surface__slope </name>   ### (vs. channel_water_surface__slope)
    <units> m/m </units>
</output_var>
  
<output_var>
    <name> channel_cross-section__hydraulic_radius </name>    ## (insert "water" ?)
    <units> m </units>
</output_var>
  
<output_var>
    <name> channel_cross-section_trapezoid_left-bank__flaring_angle </name> 
    <units> rad </units>
</output_var>
  
<output_var>
    <name> channel_cross-section_trapezoid_right-bank__flaring_angle </name> 
    <units> rad </units>
</output_var>
  
<output_var>
    <name> channel_cross-section_trapezoid_bottom__width </name> 
    <units> m </units>
</output_var>
  
<output_var>
    <name> channel_water__depth </name>    ## (remove "cross_section"?)
    <units> m </units>
    <assume> average_depth </assume>   #####
    <assume> measured_in_zenith_direction </assume>
</output_var>
  
<output_var>
    <name> channel_cross-section_water__mean_flow_speed </name>
    <units> m s-1 </units>
    <assume> speed_is_a_volume_flux </assume>
</output_var>
  
<output_var>
    <name> channel_water__volume_flow_rate </name>    #### (Need outgoing ??)
    <units> m3 s-1 </units>
</output_var>
  
<output_var>
    <name> channel_water__friction_factor </name>   ### What kind?  Darcy, Fanning, etc.?
    <units> 1 </units>
</output_var>
  
<output_var>
    <name> channel_water__froude_number </name>
    <units> 1 </units>
</output_var>
  
<output_var>
    <name> channel_water_surface__slope </name>
    <units> m/m </units>
</output_var>
  
<output_var>
    <name> channel_water__volume </name>     #### (Need "total" ?)
    <units> m3 </units>
</output_var>
  
<output_var>
    <name> model__time_step </name>
    <units> s </units>
</output_var>
  
<output_var>
    <name> land_water__runoff_rate </name>
    <units> m s-1 </units>
</output_var>
  
<output_var>
    <name> watershed_outlet_water__depth </name>
    <units> m </units>
    <assume> depth_is_averaged_over_cross_section </assume>     ####
</output_var>
    
<output_var>
    <name> watershed_outlet_water__volume_flow_rate </name>
    <units> m3 s-1 </units>
</output_var>
  
<output_var>
    <name> watershed_outlet_water__time_integral_from_start_of_volume_flow_rate </name>
    <units> m3 </units>
</output_var>
  
<output_var>
    <name> watershed_outlet_water__time_max_of_depth </name>
    <units> m </units>
    <assume> depth_is_averaged_over_cross_section </assume>     #######
</output_var>
  
<output_var>
    <name> watershed_outlet_water__time_max_of_volume_flow_rate </name>
    <units> m3 s-1 </units>
</output_var>
  
<output_var>
    <name> watershed_outlet_water__time_max_of_flow_speed </name>
    <units> m s-1 </units>
    <assume> speed_is_averaged_over_cross_section </assume>
</output_var>
  
<output_var>
    <name> watershed_outlet_water__flow_speed </name>
    <units> m s-1 </units>
    <assume> speed_is_averaged_over_cross_section </assume>
</output_var>
  
<output_var>
    <name> watershed_outlet_water__time_of_time_max_of_depth </name>
    <units> s </units>
    <assume> depth_is_averaged_over_cross_section </assume>     #######
</output_var>
  
<output_var>
    <name> watershed_outlet_water__time_of_time_max_of_volume_flow_rate </name>
    <units> s </units>
</output_var>
  
<output_var>
    <name> watershed_outlet_water__time_of_time_max_of_speed </name>
    <units> s </units>
    <assume> speed_is_averaged_over_cross_section </assume>
</output_var>
  
<output_var>
    <name> watershed_water__area_time_integral_from_start_of_runoff_rate </name>
    <units> m3 </units>
</output_var>
  
<output_var>
    <name> watershed_water__domain_max_of_depth </name>
    <units> m </units>
</output_var>
  
<output_var>
    <name> watershed_water__domain_max_of_volume_flow_rate </name>
    <units> m3 s-1 </units>
</output_var>
  
<output_var>
    <name> watershed_water__domain_max_of_flow_speed </name>
    <units> m s-1 </units>
</output_var>
  
<output_var>
    <name> watershed_land_water__domain_min_of_depth </name>  ###### land or channel or ??
    <units> m </units>
</output_var>
  
<output_var>
    <name> watershed_water__domain_min_of_volume_flow_rate </name>
    <units> m3 s-1 </units>
</output_var>
  
<output_var>
    <name> watershed_water__domain_min_of_flow_speed </name>
    <units> m s-1 </units>
</output_var>
  
</var_group>
  
</model>