XIOS configuration available through the help-config system #846

AdelekeBankole · 2025-05-13T16:11:11Z

XIOS configuration available through the help-config system

Fixes #830
Merges into #859

Task List

Defined the tests that specify a complete and functioning change (It may help to create a design specification & test specification)
Implemented the source code change that satisfies the tests
Documented the feature by providing worked example
Updated the README or other documentation
Completed the pre-Request checklist below

Change Description

This PR implements and hooks up a HelpConfig system for the XIOS handler class. Building with XIOS support and running ./build/nextsim --help-config, I see the following at the bottom:

Xios

xios.enable
Boolean                
Boolean option to toggle whether XIOS is enabled in the build. This should not need to be modifed by the user. Build nextSIM-DG with XIOS support with the CMake argument -DENABLE_XIOS=ON, passing the path to your XIOS installation with -Dxios_DIR=/path/to/xios.


XiosInput

XiosInput.period
string           (default = 0)
The period between restart file outputs expected in a file to be read, formatted as an ISO8601 duration (P prefix) or number of seconds. A value of zero assumes no intermediate restart files.

XiosInput.filename
string
The file name to be used for input.

XiosInput.field_names
string
Comma-separated list of field names to be read from the input file.


XiosOutput

XiosOutput.period
string           (default = 0)
The period between restart file outputs, formatted as an ISO8601 duration (P prefix) or number of seconds. A value of zero ensures no intermediate restart files are written.

XiosOutput.filename
string
The file name to be used for output.

XiosOutput.field_names
string
Comma-separated list of field names to be written to the output file.

Test Description

The input/output frequency now default to the timestep. This is tested by dropping their specifications in the XiosRead and XiosWrite tests.

Pre-Request Checklist

The requirements of this pull request are fully captured in an issue or design specification and are linked and summarised in the description of this PR
No new warnings are generated
The documentation has been updated (or an issue has been created to track the corresponding change)
Methods and Tests are commented such that they can be understood without having to obtain additional context
This PR/Issue is labelled as a bug/feature/enhancement/breaking change
This change conforms to the conventions described in the README

jwallwork23 · 2025-07-14T12:57:40Z

core/src/Xios.cpp

+static const std::map<int, std::string> keyMap
+    = { { Xios::ENABLED_KEY, "xios.enable" }, { Xios::STARTTIME_KEY, "model.start" },
+          { Xios::STOPTIME_KEY, "model.stop" }, { Xios::TIME_STEP_KEY, "model.time_step" },
+          { Xios::OUTPUT_RESTARTPERIOD_KEY, xOutputPfx + ".period" },
+          { Xios::OUTPUT_RESTARTFILE_KEY, xOutputPfx + ".filename" },
+          { Xios::OUTPUT_FIELD_NAMES_KEY, xOutputPfx + ".field_names" },
+          { Xios::INPUT_RESTARTPERIOD_KEY, xInputPfx + ".period" },
+          { Xios::INPUT_RESTARTFILE_KEY, xInputPfx + ".filename" },
+          { Xios::INPUT_FIELD_NAMES_KEY, xInputPfx + ".field_names" } };


Note that I renamed the keys for consistency with their names in Model.

jwallwork23 · 2025-07-14T13:00:07Z

core/src/Xios.cpp

+            "an ISO8601 duration (P prefix) or number of seconds. A value of zero assumes no "
+            "intermediate restart files." },
+        { keyMap.at(INPUT_RESTARTFILE_KEY), ConfigType::STRING, {}, "", "",
+            // TODO: Support format "restart%Y-%m-%dT%H:%M:%SZ.nc"


Filename patterns are not currently supported in our XIOS implementation. This would likely make use of setFileSplitFreq and getFileSplitFreq.

I don't plan to do this in this PR.

jwallwork23 · 2025-07-14T13:02:41Z

core/src/Xios.cpp

        >> std::boolalpha >> isEnabled;

    // Extract the start time from the model configuration
+    // TODO: Deduce from Model.iterator rather than duplicating here?


Question for the reviewer: what's the best way to transfer start time, stop time, and timestep info to the XIOS handler? The current implementation duplicates the logic in Model.iterator. I considered associating the Model with the XIOS handler but then we'd have to set up Models for the sake of the unit tests. Perhaps some of the parsed info could be static?

this is something I have faced with development of the MPI backend. IMO I think we should get the info from Model either by making it a friend or by creating getters. But yes, it does make testing more laborious 😞

I'd suggest a new class (or perhaps rather a struct) that holds two TimePoints and one Duration. The Iterator class could then hold a private one, but have a getter function to create copy of the information it holds. The duration/stop time logic would then be a part of this class.

Thanks @timspainNERSC. I opened #925 to follow this up.

TomMelt

Thanks @jwallwork23 it all looks good to me

TomMelt · 2025-07-29T13:14:16Z

core/src/Xios.cpp

+Xios::HelpMap& Xios::getHelpText(HelpMap& map, bool getAll)
+{
+    map["Xios"] = {
+        { keyMap.at(ENABLED_KEY), ConfigType::BOOLEAN, {}, "", "",


is the idea of this key so that we can build with XIOS=ON but then disable it as a runtime option?

Oh I'd just been including it because it was in the map. But yes, I suppose that could be one use case.

jwallwork23 · 2025-08-20T07:58:59Z

[Rebased on top of develop]

timspainNERSC

Approved, unless you want to include a possible new start/stop time handling class.

AdelekeBankole self-assigned this May 13, 2025

AdelekeBankole added the ICCS Tasks or reviews for the ICCS team label May 13, 2025

AdelekeBankole added this to neXtSIM_DG overview May 13, 2025

github-project-automation bot moved this to Todo in neXtSIM_DG overview May 13, 2025

jwallwork23 force-pushed the xios-help-config-system branch from 1b8e3ef to c867e4e Compare July 14, 2025 12:49

jwallwork23 changed the base branch from develop to issue850_xios-domain-from-modelmetadata July 14, 2025 12:50

jwallwork23 assigned jwallwork23 and unassigned AdelekeBankole Jul 14, 2025

jwallwork23 moved this from Todo to Review required in neXtSIM_DG overview Jul 14, 2025

jwallwork23 removed this from neXtSIM_DG overview Jul 14, 2025

jwallwork23 added the documentation Improvements or additions to documentation label Jul 14, 2025

jwallwork23 marked this pull request as ready for review July 14, 2025 12:55

jwallwork23 reviewed Jul 14, 2025

View reviewed changes

jwallwork23 requested review from TomMelt, einola and timspainNERSC July 14, 2025 13:02

jwallwork23 force-pushed the issue850_xios-domain-from-modelmetadata branch from f388d14 to 00acebc Compare July 29, 2025 08:17

TomMelt approved these changes Jul 29, 2025

View reviewed changes

jwallwork23 mentioned this pull request Jul 29, 2025

XIOS: Account for filename patterns #898

Open

Base automatically changed from issue850_xios-domain-from-modelmetadata to develop July 30, 2025 09:48

jwallwork23 added 8 commits August 20, 2025 08:50

Implement getConfig for XIOS

c34da51

Implement getHelpText for XIOS

5c56858

Implement getHelpRecursive for XIOS

91f2b60

Hook XIOS help getter up

97b9fc3

Use consistent key names as in Model

e60df9e

Set default stop time and period for XIOS

1c16d7f

Cut down config text in XIOS module docstring

d5de3c1

More info on building with XIOS

4397cce

jwallwork23 added 2 commits August 20, 2025 08:55

TODO notes for model config

80c1228

Test period automation in XIOS read/write tests

456d2a7

jwallwork23 force-pushed the xios-help-config-system branch from ccdca3a to 456d2a7 Compare August 20, 2025 07:58

timspainNERSC approved these changes Sep 15, 2025

View reviewed changes

jwallwork23 mentioned this pull request Sep 15, 2025

XIOS: Avoid duplication of timestep and start and stop times #925

Closed

jwallwork23 merged commit 5575ba3 into develop Sep 15, 2025
24 checks passed

jwallwork23 deleted the xios-help-config-system branch September 15, 2025 09:19

XIOS configuration available through the help-config system #846

XIOS configuration available through the help-config system #846

Uh oh!

Conversation

AdelekeBankole commented May 13, 2025 • edited by jwallwork23 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

XIOS configuration available through the help-config system

Task List

Change Description

Test Description

Pre-Request Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TomMelt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jwallwork23 commented Aug 20, 2025

Uh oh!

timspainNERSC left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AdelekeBankole commented May 13, 2025 •

edited by jwallwork23

Loading