Declaration DSL

(Version 1.4.0)

The Declaration DSL allows the declaration of parameters and functions that are used in a configuration file. For features their dependencies as well as parameter groups and their default values can be declared. It is also possible by specifying custom information to document features and parameters in the code.

Header

The header of the Declaration DSL consists only of the model keyword and a name referring to the scientific model. Below an example for the uvic model.

model uvic

Data types

The data types section allows to specify range and enumeration types. The data type section is introduced with the keyword types. The section may then contain multiple range and enumeration types.

Range types allow to limit values of a parameters to be inside a certain range, e.g., while a double parameter can have a range from 2.3E-308 to 1.7E+308, it might be useful to restrict this to a smaller range, e.g., a value for water temperature might range from -273 °C to 100 °C.

types
    range myRangeType double [ -273 : 100 ]

Enumeration types allow modeling of nominal values. Enumerations are used to represent model configurations where the parameter value is a string or an integer that is limited in its value ranges. By restricting potential values, issues can be prevented that might otherwise be caused by values arbitrarily set by users.

types
    enum languageVersionType [ f90,f ]

Feature

Features represent elements that can be enabled or disabled in models and their parts or submodels. For each scientific model, the declaration DSL allows to specify a feature model. A feature model contains all features of a scientific model and the dependencies between these features.

A feature can be optional or required. Optional features can be skipped. Required features must be specified. A feature can depend on another feature in the feature model or it can be excluded from other features.
Furthermore, features can contain sub-features. I.e., a feature of a river submodel is a sub-feature. Sub-features can also have sub-features. Alternate features are excluded of each other. Otherwise, features can be in parallel. E.g., only one BGC model may be used.

Each feature has at least a name and a description, as shown with the seaice model in the example below. A Feature can be required as the main feature and require or exclude other features. The below example also includes two different transport features one called transportCartesian and one transportMesh that exclude each other and both require a sediment feature.

feature seaice : "The seaice model"
required feature main : "Model main functionality"
feature transportCartesian : "Ocean circulation model" {
     requires sediment
     excludes transportMesh
}
feature transportMesh : "Mesh based circulation model" {
     required sediment
     excludes transportCartesian
}
feature sediment : "Sediment model"

While the above example places all features on one level, we could also use sub features to model this. In the example below, the main feature includes the two alternative sub features transportCartesian and transportMesh. The keyword alternative indicates that only on of these options is allowed. In case multiple sub-features can be used together, the keyword multiple must be used.

required feature main : "Model main functionality" {
      sub alternative 
         feature transportCartesian : "Ocean circulation model" {
            requires sediment
         }
         feature transportMesh : "Mesh based circulation model" {
            required sediment
         }
      sub multiple
         feature seaice : "The seaice model"
         feature sediment : "Sediment model"
}

Features can also include parameter groups. As depicted in the listing below.

feature main : "Model main functionality" {
    group common {
       def param1 int : meter = 2
    }
}

Parameter

Parameters are declared in groups. The have a name and data type, a unit and an optional default value. In line 2 below, the name is param_1, the type is int, the unit is in meter and the default value is 5. It is also possible to specify arrays with and without bounds, e.g., int[] unbounded integer array, int[4] integer array with 4 values from 0 to 3, int[1:5] an integer array starting with 1 to 5.

Units can be composed, e.g., milli meter / s**2.

group ParameterGroup {
    def param_1 int : meter = 5
    def inline_enum ( ELEMENT_1, ELEMENT_2 ) : "" = ELEMENT_1
}

Note: The inline enum feature is not yet fully tested.