Note: This documentation refers to the current development version 1.4.0.
The configuration and parameter DSL (CP-DSL) allows to set parameters and features of all parts of a model. Features can be used to enable code portions or even sub-models and sub-model-variants in a model. The division of a model in sub-models may refer to any substructure a developer sees fit. For example, in our UVic setup, embm, mom, and ice are sub-models. Sub-model-variants refer to different version of a sub-model.
Header
The header of the configuration file specifies the name of the experiment, the scientific model to be used for the code generation, and a set of includes used to complete the configuration. In the example below, we create a configuration named example for the model uvic and it includes a configuration called common.
Note: The include feature is not yet available completely and may create unwanted side effects.
configuration example : uvic include common
Features
A single feature can be selected by the keyword feature followed by the feature name. In case the feature also requires parameters, these can be specified in parameter groups. Parameter groups allow to reuse names of parameters. In the following example a feature enables the sub-features NAME2 and NAME3 with the parameters a and b.
feature NAME1 {
activate NAME2,NAME3
group PARAM1 {
a: 4 s
b: 6 m
}
}
To activate one or more features that do not have any parameters, they can be activated by stating their names in a comma separated list, using the keyword activate.
activate NAME2, NAME3
Deactivating features can be done by using the activate keyword followed
by a ! and the name (compare the upper line example) or in a list with
other enabled or disabled features.
activate !NAME1,NAME2,NAME3,!NAME4
The the latter disables feature NAME1, enables NAME2 and NAME3, but disables NAME4.
Parameters
Parameters are organized in groups or records as models often group parameters, e.g., in Fortran namelists, for technical or scientific reasons. Furthermore, it allows to define a parameter with the same name in different groups. Parameter assignments comprise a name, a value and an optional unit. The unit serves three purposes:
- It provides documentation about the unit of the parameter.
- It can be checked for validity, i.e., if the unit is compatible with the unit specified with the parameter declaration.
- It allows automatic conversion between compatible units if, e.g., the model requires the parameter in Kelvin (K), but the user specifies the value in °C.
The value of a parameter assignment can be either a value or an expression accessing other parameter values.
group PARAM1 {
a: 4 s
b: 5 * a s
}