CP-DSL: Supporting Configuration and Parametrization of Ocean Models with UVic (2.9) and MITgcm (67w)

. Ocean models are long-living software systems facing challenges with increasing complexity, architecture erosion, and managing legacy code. These challenges increase maintenance costs in development and use, which reduces the time and resources available for research. Software engineering addresses these challenges by separation of concerns and modularization. One particular approach is to separate concerns by tailor-made notations, i.e. Domain-Specific Languages (DSLs). Using DSLs, the model developer can focus on one concern at a time without the need to consider other concerns of a software sys-5 tem simultaneously. In ocean and climate models, DSL tooling, like PSyclone and Dusk/Dawn, is used for instance to separate scientific and technical code. CP-DSL complements this approach with a focus on configuration and parametrization, which play an important role in ocean models, especially in parameter optimization and scenario-based simulations. CP-DSL is designed to be model agnostic and provides a unified interface to different ocean models. Furthermore, the DSL can be integrated into tools and processes 10 used by domain experts. In this paper we report on the DSL design, implementation, and the evaluation with scientists and research software engineers. The implementation of CP-DSL is available as open source software and a replication package for configuration and parameterization of UVic and MITgcm is provided.

Since CP-DSL is designed for ocean modeling, the language requirements were identified from domain experts. To achieve this, 120 an analysis was conducted with domain experts prior to the design and implementation phase of the DSL. For the analysis of the interviews, we chose the Thematic Analysis approach tailored to our questions (Braun and Clarke, 2006). In this section, we give a brief introduction to the results concerning roles, processes, experiment types, software architectures and version/variant management that we identified in this domain.
The results are based on several interviews conducted with scientists and engineers involved in ocean model development Some of the identified roles are introduced in Subsection 3.1, the modeling and simulation process in Subsection 3.2, simulation experiments in Subsection 3.3, software architectures in Subsection 3.4, handling of versions and variants in Subsection 3.5, and the configuration and parameterization of ocean models in Subsection 3.6. For more details on the thematic 130 analysis results (not required for the present paper) refer to Jung et al. (2021b).

Roles and Interactions
A role conducts certain activities related to ocean models. Each role can be taken by multiple persons and one person can take several roles. In our interview analysis, we identified seven roles in the context of ocean modeling. For a detailed description, refer to Jung et al. (2021b). For this paper, we focus on three of these roles directly involved in developing and maintaining 135 ocean models: -The Scientific Modeler develops new and adapts or extends existing ocean models to address open research questions.
Scientific modelers are software users parameterizing and running the ocean models to conduct research. Thereby, they are developing and checking the underlying theory and the plausibility of simulation results.
-The Model Developer is a software developer and responsible for transferring the ocean models into code and has to 140 consider the scientific aspect of the code as well as technical aspects, like parallelization. Model developers also deploy the software, and submit feature or bug requests.
-The Gatekeeper is responsible to control contributions to the ocean models. They interact with model developers from various institutions to ensure quality standards in submissions and clean up code in collaboration with the contributors.
The gatekeeper is from the organization hosting the ocean models. Therefore, they are also model developers, but are 145 responsible for ensuring code styles and best practices in the common code base.  Figure 1. Extract of the ocean modeling and simulation process, depicting the three roles Scientific Modeler, Model Developer and Gatekeeper. The process is specified with the standardized Business Process Modeling Notation (BPMN) (Chinosi and Trombetta, 2012)

Ocean Modeling and Simulation Process
Based on the analyzed interview data, we identified several processes and sub-processes (Jung et al., 2021b). For this paper, we only provide an overview of the ocean modeling and simulation process. Here, the three roles introduced above are involved in the process, depicted in Figure 1.

150
Let us illustrate this process with an example: Assume that new observations of natural processes were discovered, such as the behavior of plankton, which now need to be integrated into the ocean model: and integrated into an upstream ocean model. This is a sub-process governed by the gatekeeper who ensures coding standards.

Simulation Experiments
Scientists use the ocean models for at least three different types of experiments: 175 1. Scenario-based predictions, like in the assessment of climate change. For instance, various CO 2 profiles could be used.
Usually, these scenarios are run multiple times to gain probability distributions.
2. Sensitivity studies are conducted to test the ocean model's stability/sensitivity to certain changes. These studies are used to evaluate the validity of ocean models under certain conditions and to detect tipping points.
3. Ocean model calibration aims to find and check start values by comparing ocean model output with observation data.

Software Architectures
Ocean models, as part of earth system models, usually comprise multiple scientific models including one for the atmosphere and one for the ocean (Collins et al., 2005). The ocean model itself includes at least a scientific model to simulate the circulation in the ocean, and a scientific model describing the behavior in the water column, e.g. sediments and plankton. As the ocean and the atmosphere interact, the scientific models have to share information. This is done by couplers which also map different 185 spatial properties and resolutions, e.g., different grid and mesh sizes. In some cases these meshes can have varying densities.
Another option for scientific model interaction is called nesting. Here a global ocean model with a wide mesh is used to cover the whole globe. For specific areas, a denser mesh may be overlaid. The denser and wider meshes are then either coupled using a coupler to provide interpolation or these are directly integrated, as it is the case with NEMO utilizing AGRIF (AIRSEA Team, 2016).

Handling Versions and Variants
Scientists rely on versions and variants of their ocean models. Versions play a role for publications and to document experiments. They can be used to replicate ocean model runs. These versions do not only contain the ocean model code, but often also configurations and parametrizations, as well as, input data used for the experiments.
In contrast, variants occur when ocean models are prepared for specific experiments or moved between hardware platforms 195 which often require adjustments to the implementation due to concurrency issues, different numeric behavior between HPC installations and different versions of used libraries.
Meanwhile, scientists usually rely on Git to handle versions and variants and collaborate on platforms such as GitHub and GitLab to contribute code via pull requests.

200
Before ocean models can be compiled and executed, they need to be configured and parametrized. The configuration specifies which code portions are included in the resulting program, e.g. selecting program features, scientific sub-models, build configuration, adaptations to the hardware and execution environment including parallelization like OpenMP (Dagum and Menon, 1998). The parametrization covers all the settings and inputs necessary to run a ocean model for a specific experiment. However, not all parameters can be set at runtime. Thus, they are set at compile-time, like mesh and grid sizes. Handling this aspect

Design of CP-DSL
In the following, we explain the design decisions for the DSL (Subsection 5.1), followed by a presentation of the abstract 255 (Subsection 5.2) and concrete (Subsection 5.3) syntax of CP-DSL. Subsection 5.4 explains the type semantics.

General Design Decisions for CP-DSL
The general design decisions for CP-DSL are derived form the elicited requirements, as presented in the previous Section 4.
The CP-DSL syntax should fit to other languages that scientific modelers and model developers are familiar with. This helps to incorporate the new tools into their work environment (cf. Challenge 4 in the introduction).

260
To avoid nested braces, which are not a common concept in Fortran or Python, we follow syntaxes present in established configuration formats, namely YAML and to some extent Python. However, in contrast to Python, indentation is not part of the syntax of CP-DSL.
CP-DSL allows to set ocean model features, such as friction heating, and to set parameter values grouped by parameter groups. As ocean models can have global and module-related features and parameters, they can be set on a global level or 265 in specific local modules. A module in this context can be a specific sub-model, e.g., bio-geo-chemical model and ocean circulation model, as we found in UVic or a more fine grained set of features, as in MITgcm.
For each simulation experiment, we need to define a configuration and a parametrization. Independent of a specific experiment, we declare settings that are specific to an ocean model. Thus, the parameters and configurable features are declared with CP-DSL in a Declaration Model specific to each supported ocean model, as depicted in Figure

275
Due to the nature of the domain of CP-DSL, the terms model and modeling are used both to describe models of the ocean in ocean science and models of software in software engineering. In software engineering, models are built as abstractions of the software systems themselves. In this subsection, we present models of software: the abstract syntax of CP-DSL as metamodels via the standardized Unified Modeling Notation UML (UML 2.5.1).
The concrete syntax of a programming language is defined by a context-free grammar (see Subsection 5.3 below). It consists 280 of a set of rules that define the way programs look like to the programmer. The purpose of the abstract syntax, presented here, is to have a simpler representation of what is essential in the syntax (Aho et al., 2007).  Each feature has a name (inherited from NamedElement), a description which is shown in the editor as context assist information, and a flag showing whether a feature is mandatory or optional. A feature may contain sub-features. These are grouped in a FeatureGroup, as the refined metamodel for features in Figure 4 shows. The model allows to have multiple feature groups.
Each feature group can contain multiple features, which are either alternatives or can be used in parallel.    to support unit conversion. For example, if a parameter requires its value in meter (m), then the scientist can also specify the value in km and it is automatically translated to the correct meter value in the configuration file, e.g., 2km/h will become 2 * 1/3.6m/s. As ocean models may use a wide range of parameters, the parameter declarations are grouped in declaration groups (ParameterGroupDeclaration in Figure 3).
Types can be the primitive types Integer, Float, String, File, and Boolean, as well as, ocean-model-specific enumeration 305 and array types. As Fortran before Fortran 2003 did not have enumerations, developers used various approaches to implement them. The CP-DSL supports such approaches on the code level providing enumeration values to the developer on the ocean model level.
In addition to name, type and unit, a ParameterDeclaration contains optional default values (see the containment association between ParameterDeclaration and Expression in Figure 5). Beside a plain default value, it is also possible to define expressions 310 as defaults. This functionality is used, e.g., for grid size parameters computed based on tile sizes, number of tiles, and border points around the core grid of ocean models.
Beside the generic module syntax, we implemented a specific syntax for the concern of ocean model diagnostics. Diagnostics refer to log files that are written during a simulation to support the model developers to assess the run of the ocean model and to check whether everything is working properly. Figure 6 shows a metamodel extract for diagnostics and logging. Here, 315 diagnostics parameters and log file information are defined.

Concrete Syntax of CP-DSL
In this section, we present an extract of CP-DSL's concrete syntax in Figure 7, which is defined as a context-free grammar using the EBNF (Aho et al., 2007). With the EBNF (Extended Backus Naur Form), optional parts of the syntax are enclosed in brackets. Here, this is the case for defining global features, parameter groups, and modules. Alternatives are specified via 320 a |. A module can have its own set of features and parameter groups (not included in the excerpt of Figure 7). The complete grammar can be found in the replication package (Jung et al., 2021a).
The start for the excerpt in Figure 7 is <model-setup>. The ID left of the colon defines the name of the experiment. The second ID identifies the ocean model. This information is required to make the matching feature and parameter declarations available for a ocean model, and to select the right code generators for it. An example for selecting MITgcm for an experiment

Features
Features are used to activate and deactivate certain configuration options of an ocean model. They usually relate to #ifdefs in the code and allow to create different variants of a ocean model. In Listing 1, the feature for 'friction heating' is activated 330 and 'geothermal flux' is deactivated. While features are deactivated by default, CP-DSL allows to import other configurations.
It is possible to deactivate imported features.

Parameters
Parameters, specify configuration and parametrization values, which can be scalars or arrays. CP-DSL supports multidimensional arrays. To set a single cell of an array, its cell number must be specified, e.g., levels(1) = 5. To fill a complete array, only the parameter name is specified and an array value of the same size on the right-hand side, e.g., levels = [ 1,2,3,4,5 ].

340
However, in some ocean models not all fields of an array need to be initialized and the underlying array declaration may not start at the target language default, i.e., 0 for C and 1 in Fortran. Thus, we allow to specify a range as dimension expression, e.g., levels(4:5) = [ 1,2 ], where the first and last index are specified.
Parameters are grouped in CP-DSL to offer a lean way to put related parameters together or follow the configuration file layout of the ocean model. For example, MITgcm (Artale et al., 2010)  parameter group is placed in front with the dot notation, .e.g., Nx = SIZE.sNx * SIZE.nSx * SIZE.nPx.

Modules
Modules represent parts or packages of ocean models that address a specific concern in an ocean model. Often these are scientific sub-models, like biogeochemical models, or specific functionality, like diagnostics. In the CP-DSL, a module consists domain to group functionality together.

Logging and Diagnostics
Listing 4 illustrates the use of the diagnostics syntax in the context of the MITgcm (Artale et al., 2010). The diagnostics includes general parameters to setup the diagnostics, i.e., a storage directory for all diagnostics, a file format and mask setup for the output. For each kind of log, a separate log section must be specified which defines the log file name, here first-out.log, the kind of log, e.g., a snapshot or an aggregation of values, a frequency and which value should be used to indicate a missing 375 value. Finally, the fields and levels are specified. In the following, we explain our implementation infrastructure for agile development of CP-DSL (Subsection 6.1), and the implementation of the code generators (Subsection 6.2).
6.1 Implementation Infrastructure for Agile Development

410
As implementation infrastructure, we use XText (Bettini, 2016), Xtend (Efftinge et al., 2012), and EMF (Steinberg et al., 2009) for the following reasons: -The CP-DSL, its metamodels and code generators should be developed with continuous feedback from users, i.e., scientists, and by adding new case studies to the project. This continually creates new feature requests that must be integrated into the DSL. Hence, the development context requires an agile approach which allows to introduce changes frequently.

415
The selected technology stack is able to provide this, as XText automatically derives syntax tree representations and metamodels from the grammar specifiation, and includes the generator template language XTend. Thus, it reduces development and maintenance costs (cf. Challenge 1 in the introduction).
-XText supports the Language Server Protocol (LSP) (Microsoft Corporation, 2016) that allows to provide DSL-supportive editor features to many editors, including Vim, Emacs, and Jupyter. This facilitates the integration in the existing devel-420 opment environment of scientists (cf. Challenge 4 in the introduction).
-We have previous experience in implementing DSLs for ocean science with XText/Xtend/EMF  reducing the time necessary to familiarize the involved researchers and developers with these technologies.
While such an implementation infrastructure introduces a new dependency and therefore a risk (cf. Challenge 5 in the introduction), we mitigate this, as the generated code is human readable and in case the DSL becomes deprecated, the generated 425 artifacts can still be used.

Code Generation
The relationships and code transformations among these metamodels are specified as so-called megamodels. The overall architecture for the code generation for MITgcm is a two step process, depicted as a megamodel in Figure 8. For the megamodel notation in Figure 8, we follow the notation of Favre et al. (2012) and Jung (2016). 430 We distinguish Configuration and Declaration Models, as discussed in Subsection 5.1, see Figure 2. On the left of Figure 8, the Configuration and Declaration Models for a specific ocean model (here MITgcm) are shown. The models in the middle are intermediary models that can be transformed into specific configuration and parametrization files. The first step of the process utilizes a set of model-to-model transformations to create the intermediary models. The second step uses a set of model-totext transformations to generate the required output files. We chose this two step process, as this helps with maintaining code 435 templates and model-to-model transformations.  arrows references between models and asterisks denote multiplicity (the notation is derived from Favre et al. (2012) and Jung (2016)).
MITgcm has four different types of configuration files and uses separate files for each module (called package in MITgcm).
The transformations T Namelist , T Options , T Packages and T Size in Figure 8 produce output models for Fortran namelists, feature selections which can be stored in preprocessor files based #defines and #undefs, MITgcm package selection files, and MITgcm include files defining variables and sizes, respectively. As the ${PKG}_OPTIONS.h and ${PKG}_SIZE.h 440 files do not follow a unique structure that can automatically be derived from parameter and feature settings alone, additional structural information is provided in multiple Options Structure Models and Size.h Structure Models (cf. Figure 8, lower left).
The Declaration model contains the declaration of data types, parameters, features, and modules and refers to supplemental information, as shown in Figure 8 for the MITgcm generators.
Each ocean model has its own configuration and parametrization file types. Thus, the set of transformations and code-level 445 models differ. Figure 8 and Figure 9 depict the transformations for MITgcm and UVic, respectively.
As depicted in Figure 9, UVic handles its configuration and parametrization in two files, where mk.in contains feature selections and compiler setup. control.in serves as runtime parametrization file in a Fortran namelist format. Our generator architecture provides an API to integrate additional transformations for other file formats necessary to support additional ocean and climate models. We provide a template extension mechanism alongside with documentation that allows 450 to create extensions for any scientific model with little knowledge of the overall technology.
For model developers, who implement new features and modules for an already supported ocean model, writing new transformations can be omitted when they follow the general guidelines for their respective scientific model. They only need to add module, feature and parameter declarations to the Declaration model.

455
The CP-DSL was evaluated utilizing the JupyterLab setup as a case study for the OceanDSL Project (Jung et al., 2021c).
We applied an iterative evaluation process where we evaluated CP-DSL versions via user studies and interviews with domain experts. The initial evaluation was performed with an early syntax of the DSL. The later review was conducted with domain experts based on the revised syntax, which was presented in Section 5.

460
The first CP-DSL revision evaluation replicated three MITgcm experiments derived from the MITgcm User Manual (Alistair et al., 2018). In detail, we used the Barotropic Ocean Gyre experiment, a modified variant of the Barotropic adjustment problem based on a latitude-longitude grid, and a global ocean simulation. We tested the feasibility and usability of the DSL. First, test users were tasked to create suitable configurations for the three experiments based on their documentation. Second, they reported on the feasibility to create the desired configurations and potential issues with the DSL. The created CP-DSL files were 465 used to generate native configuration files for each experiment and compared them to the original setup of the experiments. To gain insight into its usability, test users were asked to report on their experience in a questionnaire.
The feasibility evaluation showed that valid setup files could be generated successfully for all three scenarios. The validation was performed via a regression test against the original setup. The usability analysis is based on the feedback by the test users.
While they were able to create the intended setup, they found the use of JSON-style curly braces in the first version of CP-DSL 470 impractical, affecting readability.

Second Evaluation
In the second evaluation, the revised CP-DSL was presented to domain experts and utilized in a joint session to demonstrate its usage. UVic is the reference simulation by GEOMAR of the University of Victoria model. It was used together with MITgcm in the third phase of Sopran (Bange, 2016). Where UVic formed the basis for all earth system models and MITgcm was used 475 for atmospheric and biogeochemical processes. Based on this experience, interviews were conducted to gain insights on the usability of the CP-DSL. The division in general parameters and modules was considered useful. Also the reworked YAML syntax was rated easy to understand.
perts from ocean science. The key concepts of the DSL, e.g., feature selection, setting up parameters, and module selection are As this is an ongoing research project, we aim to further extend and improve CP-DSL in close contact with users and active 490 scientists from the domain. We initially developed the DSL for a representative subset of MITgcm ocean modeling scenarios and are currently evaluating it to be able to support all modules of MITgcm. However, the current syntax for diagnostics caused a larger comment by our domain experts, as diagnostics are an important topic in climate modeling for various purposes. A concern was raised that the current syntax for the diagnostics might either be not expressive enough or did not provide enough specific features, i.e., it seemed to be too close to the generic module setups. We will address these insights in the next revision 495 of the DSL including a thorough investigation of different diagnostics approaches including CDI-pio (Kleberg et al., 2017) and XIOS (Meurdesoif et al., 2012).
Our current efforts also focus on supporting additional ocean models and improving the syntax and semantics of the CP-DSL. In particular, the current parameter-override semantics follows a straightforward solution where an included parameter can be redefined and thus overwritten. Since this allows accidental redefinition of parameters, we will evaluate several language 500 solutions in the future that prevent this. For instance, the possibility to redefine or hide parameters when importing configurations and parameters. We will further evaluate the CP-DSL versions with ocean scientists and research software engineers from our partner institutions at GEOMAR, DKRZ, and the MPI.
Code and data availability. The CP-DSL code is available at https://git.se.informatik.uni-kiel.de/oceandsl/cp-dsl. Furthermore, a replication package is provided (Jung et al., 2021a) 505 Author contributions. Authors contributed equally to this work.
Competing interests. The authors declare that they have no competing interests.