feat(config): migrate mizuRoute configuration parsing to native TOML format

[johnpaulalex]

Description of changes

Migrates mizuRoute's configuration file format from legacy space-delimited control files (.control) to native TOML (.toml). Integrates the toml-f Fortran library (externals/toml-f) as a git submodule to parse TOML configuration files natively.

This PR is split into two logical commits:

1. feat(deps): add toml-f Fortran library submodule and build system integration (build system & submodule setup).
2. feat(config): migrate mizuRoute configuration parsing to native TOML format (TOML parsing, buildnml updates, and mizuRoute_control refactoring using OrderedDict).

Updates cime_config scripts (buildnml, buildlib, mizuRoute_control.py) to generate and process mizuroute.toml while maintaining dual generation of legacy mizuRoute.control during the transition phase. Extends buildnml to check for $CASEROOT/user_nl_mizuroute.toml first, falling back to $CASEROOT/user_nl_mizuroute_control if missing.

Specific notes

Contributors other than yourself, if any:

• @johnpaulalex

Linked issues addressed, if any:

• Work on Change format of input control file to a standard format? #395

Description of generative AI usage:

• Google Antigravity was used to write the code and tests, followed by human-guided verification.

Answer Changes & Scientific Impact

• Bit-for-Bit (B4B) with baseline master
• Roundoff-level differences only
• Expected Answer Changes (ECA)

User Interface & Namelist Changes

• Namelist / Defaults modified? Yes (migrated default configuration file to mizuroute.toml)
• XML / Build script changes? Yes (cime_config/buildlib, cime_config/buildnml, .gitmodules)

Testing planned or performed, if any:

• Executed pFUnit / CIME regression tests

CTSM / CESM baseline hash-tag: 28514dea3fd28a2f820c7ecaa9014f820c1bb220
PR branch hash-tag: 8989fe6

Requirements before merge:

• The code in this PR branch builds with no errors.
• The code in this PR branch runs with no errors.
• In-code documentation and Fortran docstrings updated.
• This PR either (a) does not create a need to update documentation or (b) includes required documentation updates. Which?: (a) Bug fix / unit test addition; no documentation updates required.

[ekluzek]

It looks like this removes the old control files, but also has logic to keep them and just add the new TOML file format. As I understand the transition plan this first step needs the old control files to be kept around until they can be removed when the TOML file reading is brought in.

So I think the way this should go is that at this step it should handle both the control file format and the TOML format. So both are kept around. But, at this step it actually reads in the control file format. But, there can be testing/checking that the python is handling the TOML format correctly.

[ekluzek]

Use a underscore rather than a dot to make it match how it's done for the control file.

[ekluzek]

Suggested change

	file_src_toml = "user_nl_mizuroute.toml"
	file_src_toml = "user_nl_mizuroute_toml"

[ekluzek]

Although there are also advantages to the .toml extension, so it really only matters if others have an opinion on this.

[ekluzek]

Actually thinking about it though. For the user_nl_* files in CESM we never use an extension we only use underscores, so we should probably keep that convention until CESM changes it for the user_nl_* files.

[ekluzek]

change name as above...

[ekluzek]

This should stay the same if the control file is going to be left around.

[johnpaulalex]

I thought we'd have users specify their overrides in a toml file going forward, and merge that with the case's toml

[ekluzek]

I talk about this below. We thought keeping the ability to read either format would be good for a transition time. But, this was also from my understanding that this PR doesn't change the code to read TOML format -- but a future PR will do that step. So this can't change until the Fortran code is updated to read TOML format anyway.

I do think it's a good plan to do this in a few steps. And it makes sense to me to make the first step be to just add the toml library to the build -- but don't use it. And then the next step is to actually use it.

[ekluzek]

I wonder if this file should be left alone, and a new file mizuRute_toml.py added to handle toml format? Then the control one can be removed once toml format takes over.

[ekluzek]

This can't really be done, until the Fortran can actually read in the TOML format file. So this change should be removed until then.

[johnpaulalex]

meaning ESMCI/cime#5024? How should that work - get the CIME PR and this one in minus this line, and then flip it on in a later PR?

[ekluzek]

My understanding of this PR is that it brings in the ability to build the toml-f library -- but doesn't change the code to read TOML format (until a fture PR is done). As such the old control file format needs to remain, until the ability to read TOML format is in the Fortran code.

The cime PR just allows cime to do differences on TOML format files. So it's nicely independent of this one. And cime isn't a submodule of mizuRoute, so it doesn't apply here anyway.

[ekluzek]

@johnpaulalex thanks for your work on this. I brought it up with a few people and they agree this is a good thing to work on. One of those is @martynpclark and the library he's using to read TOML file format is the same as the library you are using here. So that's a good sign! This is also something that's too low of a priority for us to work on. But, at the same time it's something that makes a good improvement in usability.

I talked with @nmizukami about this a bit and we do see several things that need to be done. It might be good to have a meeting to go over it.

The most important thing missing is that the standalone build was updated to use the toml-f library. But, the CESM build will also be modified. For that, ccs_config might need changes. And also buildlib under cime_config will need to be updated. The buildlib is currently really simple and it just compiles code in a list of directories. That possibly could be done for toml-f -- but it seems like the toml-f build is really what should be called.

We'd also like to have a path forward that has a transition from control file format to TOML format. So both allowed initially, and then later the control file format removed. A tool to help facilitate that would be good to have is a python tool to convert between the formats. I think that shouldn't be hard to write. But, that would allow users with existing control files to convert the format to TOML and show that the results are identical. They may have a bunch of control files they aleady use, so be able to convert to the new format would help facilitate adoption. And later they start a collection of files in TOML format, that they might need to run with an older version and they'll need it converted backwards. This tool could be built on top of the existing mizuRoute_control.py file in route/settings and hopefully wouldn't need many additions to it.

So let me know what you think about this. I'll put a summary of checkboxes in a comment below to list the things I see.

[ekluzek]

These are the list of things that I see that need to go in here:

• Add a standalone build/run tester (Add a simple standalone build/run test #647)
• Make sure the standalone tester works on Derecho with Intel
• Add the build of the toml-f library to the CESM build
• Keep the option to use either TOML or control file format
• Run the "mizu" test list to make sure the CESM tests run as expected
• Add a tool to convert between control file and TOML format (either direction)

[ekluzek]

Workign on a transition plan with @johnpaulalex and @nmizukami

1. Provide a tool to read and convert between the formats and both can be read in
2. Only TOML format is used to be read in, can still use the tool to covert to TOML, fails if provide old format
3. Eventually remove the tool for conversion