Dynamics ModelComponent

The DGDynamics ModelComponent

Name: Tim Spain

Affiliation: NERSC

Project Milestone (delete as appropriate): Dynamics Merge

Reviewers: Piotr Minakowski, Thomas Richter

GitHub Issue: #220

---

1. Introduction
2. Requirements
   1. Architectural
   2. Functional
   3. Other
3. Functional
   1. Build
   2. Configuration
   3. Run
4. Architectura
   1. CMake and Build
   2. Design Details
5. Implementation
6. Integration
7. Test Specification
8. Documentation Impact

---

Introduction

The dynamics should interact with the rest of the model as many other parts do, using the ModelComponent and ModelArrayRef classes. The dynamics ModelComponent will hold a large amount of its own data, much of which will have DG components which are not used by the rest of the model.

Requirements

The new DGDynamics ModelComponent must be able to set the data of the lower level dynamics class from the data provided in the restart input file. In common with other ModelComponent derived classes, this will arrive through an implementation of the setData() virtual function. The data will be provided as ModelArrays of types DG, DGSTRESS and CG.

As with the other ModelComponents, an update function will be needed to advance the dynamics by one long timestep. There will be three steps within the update function:

1. Copy the finite volume (DG0) components of fields such as ice thickness, ice concentration, damage and so on.
2. Advance the dynamics by one long timestep, composed of many shorter advection timesteps.
3. Copy the updated finite volume (DG0) components back to the arrays used by the thermodynamics portion of the model.

The fields shared by the dynamics will probably have to include the full DG arrays of the data so that these can be accessed for output. This will mean that additional ProtectedArray entries need to be introduced into ModelComponent to refer to these DG arrays. These might be named H_ICE_DG &c.

Additional functions in the DGModelArray and CGModelArray family will also be required, in order to copy only the DG0 (finite volume) component of a ModelArray to and from DGVector and CGVector instances.

Functional

Here we explain how a user will interact with the feature.

You should lay out the specification for any external interface or control here (e.g. an API call or a config file parameter and how you turn it on or off and ).

You should describe how the computer's state will change when running this feature and how a user will experience that. Is something printed to terminal or written to file? Does a new window appear? How are users signposted to the write location?

This may affect

Build

Details on how it impacts build/compile workflows. Does the user need to provide any flags, BYOS, etc...

Configuration

Details on how it impacts configuration/input files

Run

Details on how it impacts the overall package workflow as well as any changes to the system state, including terminal/file IO or other UI changes.

Architectural

As a subclass of ModelComponent, the DGDynamics Component class needs to implement a few virtual functions

getName()

Returns "DGDynamics".

setData()

Set data needs to receive ModelArray data. It should be capable of initializing all the DG components in the arrays required for the dynamics even if the supplied fields are Type::H only, that is contain only the DG0 finite volume component. The function should also throw if the required fields are not found in the supplied DataMap.

getState() and getState(const OutputLevel&)

These functions should return all the components of the data, passing them back as Type::DG, Type::DGSTRESS and Type::CG ModelArrays.

update(const TimestepTime&)

In common with most ModelComponent subclasses, there will be an update function, which is not a virtual function. This will copy the necessary data from ModelArrayRef objects pointing at the data in the rest of the model. Then the dynamics and advection are advanced by many advection timesteps to reach the length of a thermodynamics (long) timestep. The updated DG0 terms are then copied back into the shared ModelArrays.

Since the object needs to hold the full DGVectors of the dynamics variables, the main part of the calculation is contained in a class in the dynamics subdirectory, DGDynamicsKernel.

Integration

The Dynamics component will take ownership of some of the data arrays currently in PrognosticData, such as the ice thickness and ice concentration. But will it? This section should outline how the feature relates to existing code on a system-level and any exisiting workflows or third-party software used by developers or users. This is a good place for flowcharts of proposed workflows for your finished feature.

Information about any dependencies with specific information about how they depend on one another could also be captured here. A good example would be to note which outputs from an external program are being supplied as inputs to the main program and how your feature accesses that. You could mention I/O during operation or you could talk about any post-processing steps.

Test Specification

Using the list of requirements generated earlier, you should be able to write a list of test objecives which provide a high-level definition or summary of corresponding tests that you will provide with your pull request (or an a follow-up issue, linked to an issue number and submitted within the code itself). E.g.

1. Initialize component and verify that file was created following call to method X
2. Run the program using config file A with feature parameter set to 'on' and config file B with feature parameter set to 'off'
3. Modify CMakeLists for one test executable such that library X is not available during compile
4. Create a test to add to the collection of perfomance tests and create a test that compares the on and off state.

In addition to tests for any special cases that arose during development (e.g. for different variables types, magic numbers of cores/nodes or race conditions where unavoidable).

Ths section of the specification not replace comments that are included at the top of each test which should describe how the test functions. However it should provide enough context such that a future developer could determine if it is safe to remove or modify a particular test.

Documentation Impact

For anything which is designed to or indirectly affects the user experience or removes or adds a limitation to the capability of the code, a corresponding change should be made to the documentation.

This a good place to note any like impact on the documentation and can be discussed at design review and during the pull request review stage.