Restart file output specification

Restart file output specification

Name: Tim Spain

Affiliation: NERSC

Target/Actual Release Date/Project Milestone (delete as appropriate): Stand-alone model

Reviewers: Alex Smith, Kacper Kornet

GitHub Issue: #239

---

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

Currently a restart file is produced at the end of the run. It would be useful to be able to produce this at other times, either specified in the initial configuration or signalled by a coupled model, as I currently believe the NorESM coupling will do.

The ability to create more frequent restart files will help both developer debugging the physics code and users who are pushing the model into regimes where it may suffer from numerical crashes. Since the restart file output code already exists, there will be minimal impact on other components.

Requirements

1. Introduce a new configuration value into the [model] section to specify restart file frequency, called restart_file_frequency. This takes a Duration specification to determine the frequency with which restart files are created other than at the end of the model.

2. The string 'NONE' is a special case and the default and specifies that only the end of run file is to be created. This special value is not case sensitive.

3. The possible forms of the Duration string are then:

   • 'NONE', 'none' and any other variations in case:
     • Do not output any restart files apart from the one at the end of the run.
   • 'PY-DThh:mm:ss':
     • Produce a restart file every _Y_×31536000 + _D_×86400 + _hh_×3600 + _mm_×60 + ss seconds after the start of the run.
   • 'PY-M-DThh:mm:ss':
     • This form, explicitly including the month in the time value, should allow specification according to the calendar. In this case Y specifies a calendar year, including leap days, M is calendar months and D days of the month (so setting it to a value > 28 is probably a bad idea). Within the day, hh is hours in the day, mm minutes in the hour and ss seconds within the minute. The sub-day can be dropped (in both cases) especially when operating on the calendar basis.

In most cases only one unit of time should be non-zero.

4. Include a text feedback function to ensure that the input has been interpreted correctly during testing and also to give the user feedback during a model run.

5. The name of each restart file should be suffixed with the date in the form YYYYMMDD_hhmm. With a 600 second baseline for the timestep, we shouldn't need second granularity. The file name is then runname.YYYYMMDD_hhmm.nc.

Configuration

An addition configuration option model.restart_file_frequency will be added.

Run

Additional file IO whenever a restart file is created. An additional line logged on configuration describing the output frequency and a log message every time a restart file is created.

Architectural

Bung it into Model somehow? Certainly use the Model configuration function, but the new class will parse the passed string. No idea how or whither the new class signals that a restart file is due. Does Model even need to get involved, or can all the data be obtained from Prognostic data?

Test Specification

Test the parsing of the frequency specification.

Test using a re-implementation of most of the model classes to observe that the expected restart file names are produced.

Documentation Impact

Document the new configuration option. If we include documentation on what a restart file is, then a description of this option should be included. The Model class should return additional text in getHelpText() giving a description of this option.