OMS Modeling (DSL) Reference

Introduction

The OMS model development framework provides a DSL for:

• Performing unit tests on OMS science components
• Connecting system and science components to build a model
• Parameterizing and provisioning data for a model simultation
• Running a model simulation with logging, statistics, and output visualization
• Calibrating a model
• Performing sensitivity and uncertainty analysis on a model

The OMS DSL contains elements and sub-elements, which are used to create simulation files. The term simulation is generic, applying to unit tests, basic simulations, calibrations, and analyses. All simulation files have the same formal structure:

// comment
<element>(<key:value>, <key:value>, ...) {
<element>(<properties like above>) {
// sub-elements..
}
<element>(<properties like above>) {
// sub-elements or just elements with value
<element> <value>
}
<element>(<properties like above>)
<element> {
<element ..
}
// more elements and subelements
}

Some useful things to know in general about the OMS DSL:

• Each simulation file has one root element establishing the type of simulation.
• Comments can be single lined ('// ...') or can span multiple lines ("/* ... */")
• Elements can have properties in parentheses after the element name. If there are no properties the parentheses can be omitted.
• Properties are a list of comma separated tuple of <key:value> pairs.
• Multiple properties are separated by comma, and all properties are embedded in parentheses.
• Elements can have sub elements within curly brackets. If there are no sub-elements, the curly brackets can be omitted.
• Elements can have just a value following the element name separated by space.

Complete List of DSL Elements for Basic Simulation and Unit Testing

Simulation	Sub-Element 1	Sub-Element 2	Sub-Element 3	Simulation	Sub-Element 1	Sub-Element 2
sim{}	build			tests{}	resource
	model{}	components{}			model{}	parameter{}
		connect{}				logging{}
		feedback{}			test
		parameter{}
		logging{}
	resource
	outputstrategy
	output
	summary
	efficiency
	analysis{}	timeseries{}	x
			y
			calc{}
		scatter{}	x
			y
			calc{}
		flowduration{}	y
			calc{}

DSL Elements for Component Unit Tests

DSL Element - tests

Root Element	Level 1 Sub-Element	Level 2 Sub-Element	Occurences Allowed
tests{}			one per test
	resource		one to many
	model{}		exactly one, required
		parameter{}	zero to many
		logging{}	one per test
	test		one or many

OMS creates a tests object, which has a property name to identify it and its purpose.

Property

Example

//create the unit test object
tests(name:"CSMLite Plant Growth Unit Test") {
     //add sub-elements...
     }

Unit testing is the concept of automated verification of individual software units. In OMS such units are components,the basic building blocks of simulation models. Unit testing support is part of the core OMS framework. It can be set up easily to efficiently test and verify individual components. Best model developing practice should embrace unit testing by complementing a scientific component with sufficient tests, hence assuring of its proper working and creating confidence.

Some fundamental rules for components tests apply and are consistent with general purpose testing frameworks. Tests are comprised of individual test cases, which are independent from each other. Each test case can run on its own.

The OMS unit testing implementation closely resembles concepts and strategies of related frameworks, such as JUnit or TestNG. This allows easy transitioning into OMS component testing if the modeler has previous unit testing knowledge.

The tests{} element supports the setup of many test cases for an individual component or whole model. Each individual test case for a component is described with the test element. Since components all adhere to a common layout, testing is straightforward. For a single test case the component is populated with data for all Input fields (@In), the execution method gets invoked (@Execute), and finally the produced output fields (@Out) can be checked. There are different ways to generate input, perform test execution and verify proper output. The oms3.prj.csm project contains several unit testing examples.

DSL Elements for Basic Model Simulation

DSL Element - sim{}

Root Element	Sub-Element	Occurences Allowed
sim{}
	build	zero or one, optional
	model{}	exactly one, required
	outputstrategy	zero or one, optional
	resource	one or many
	efficiency	zero or many
	output	zero or one, optional
	summary	zero or many
	analysis{}	zero or many

OMS creates a sim object, which has a property name to identify it and its purpose.

Property

Example

//create the simulation object
sim(name:"CSMLite Basic Simulation for Workshop") {
     //add sub-elements...
     }

The oms3.prj.csm project provides simulation examples showing the use of the relevant DSL elements and sub-elements.

DSL Elements for Analysis (Calibration)

DSL Element - luca

Simulation	Sub-Element 1	Sub-Element 2
luca{}	model{}	parameter{}
	resource
	outputstrategy
	output
	calibration_start
	rounds
	step{}	parameter{}
		objfunc{}

Example Calibration

luca(name: "EFC-luca") {

    // define output strategy: output base dir and
    // the strategy NUMBERED|SIMPLE|DATE
    outputstrategy(dir: "$oms_prj/output", scheme:SIMPLE)

    // define model for calibration
    model(classname:"model.PrmsDdJh") {
        // parameter
        parameter (file:"$oms_prj/data/params_lucatest.csv") {
            inputFile  "$oms_prj/data/data_lucatest.csv"
            outFile    "out.csv"
            sumFile    "basinsum.csv"
            out        "summary.txt"

            startTime "1980-10-01"
            endTime   "1984-09-30"
        }
    }

     output(time:"date", vars:"basin_cfs,runoff[0]", 
                 fformat="7.3f", file:"out1.csv")

//   output(time:"date", vars:"basin_cfs,", 
//                fformat="7.3f", file:"out1.csv")

    calibration_start "1981-10-01"         // calibration start date
    rounds 2                               // calibration rounds, default 1

    // step definitions
    step {                     
        parameter {
            jh_coef(lower:0.001, upper:0.02, strategy:MEAN)
        }
    
        objfunc(method:ABSDIF, timestep:DAILY) {
            simulated(file:"out1.csv", table:"EFC-luca", column:"basin_cfs")
            observed(file:"$oms_prj/data/data_lucatest.csv", table:"obs", 
                         column:"runoff[0]")
        }
        // can add more
    }

    step {                    
        parameter {
        //  ssrcoef_sq(lower:0.001, upper:0.4, strategy:MEAN)
            soil2gw_max(lower:0.001, upper:0.4, strategy:MEAN)
        }

        objfunc(method:ABSDIF, timestep:DAILY)  {        
           simulated(file:"out1.csv", table:"EFC-luca", column:"basin_cfs")
           observed(file:"$oms_prj/data/data_lucatest.csv", table:"obs",
                        column:"runoff[0]")
        }     
    }
}