Moving away from Fortran namelists - A proposal

[krenzland]

The Fortran namelist based configuration file is the bane of our existence.
I propose the following (really stupid/brilliant) plan:

Step 1

1. Add a yaml/toml/whatever parser, define a new configuration format
2. Add functions to parse this new configuration format and generate a Fortran namelist file from it.
3. Parse this generated namelist with Fortran
4. Recognize when user-specified .par file as input and warn that it is deprecated (and may not support all features)

Step 2

1. Remove support for .par files
2. Move configuration parsing fully over to C++

Step 3

1. Delete all Fortran code

After Step 1 we get a lot of benefits (we can easily add new configuration options to the new format and access it from C++) whilst we keep some backward compatibility.
After Step 2 we are able to access the entire configuration structures from C++ code (and also from Fortran code).
After Step 3 we can finally be happy.

There should be some time (maybe half a year) between step 1 and step 2 so that users have time to adjust to the new format. Maybe we can add a quick script that converts to a new format automatically, e.g. using something like https://github.com/marshallward/f90nml.

What do you think?

[ravil-mobile]

Hi, Sebastian and I are doing a similar thing but in reverse. We parser Fortran namelist and generate a yaml representation in memory. Then we access input data from C++ using yaml-cpp

[krenzland]

Yes, but this is extremely inelegant and confusing.

[krenzland]

The main problem I see with your approach is that it doesn't make any progress towards a new (accepted) configuration format. When we use this, we will still have Fortran namelists in 3 years.

[ravil-mobile]

True, but it is better to change the format from Fortran namelist once you get rid off the fortran code. I mean just think how much small functions you will need to write to pass the information to the Fortran code from C++. Plus, you need to update all documentation and all SeisSol examples.

I feel that once we move dynamic rupture to c++ then it will be relatively easy to deprecate huge pieces of the fortran code. Then it will make sense to change the input to yaml/toml/etc.

[ravil-mobile]

Sorry, I forgot that you proposed to parse yaml/toml back to Fortran namelist

[krenzland]

Yes, but that is the entire point of my proposal. You do not need to change a single line of Fortran code for it to work. (And actually, it's probably best to combine both approaches - to also have access to the namelist data from C++)

[uphoffc]

So your proposal is to interpret Fortran namelists as a dialect of .ini/TOML? Sounds good and should be easy to write a parser.

I have a few additional comments:

In Step 1.1 make sure to add a version, the current format being version 1 or so. This way you might not even need to deprecate the old format. (Keep in mind that there are published setups on Zenodo. I'm not saying one needs to support these until t -> inf, but one also doesn't need to break them if there's no good reason.)

One other thing to think about early is what the internal data structure for the configuration should be. Using a generic hash map as offered by yaml-cpp / toml parsers is a design failure imho. Besides being inefficient (which is not a big deal for configuration though), the user has to convert the entry in the hash map to the proper data type always when he uses it. Moreover, there are no guarantees that the configuration data is proper and the values need to be checked everytime. Think of horrible spaghetti code like this:

double cfl = conf["cfl"].get_as<double>();
if (isnan(cfl)) ...; // error
if (cfl < 0) ...; // error

What I found a super useful idea is to implement a schema. (I think I got inspired by the following Python package: https://pypi.org/project/schema/)

In tandem, I do the following. Define a configuration struct, e.g.

struct Config {
  double cfl;
  std::array<double, 3> ref_normal;
  std::optional<std::string> output;
};

Then I define a Schema for this struct, e.g.

TableSchema<Config> schema;
schema.add_value("cfl", &Config::cfl)
        .validator([](auto&& x) { return x > 0 && !isnan(x); })
        .help("CFL tuning parameter");
schema.add_array("ref_normal", &Config::ref_normal).of_values();
schema.add_value("output", &Config::output)
        .converter(path_converter)
        .validator(PathExists());

You then parse a toml (or potentially namelist) file with

    toml::table rawCfg;
    try {
        rawCfg = toml::parse_file(program.get(configPar));
    } catch (toml::parse_error const& err) {
        ...
    }
    Conf cfg;
    try {
        cfg = schema.translate(rawCfg);
    } catch (std::runtime_error const& e) { ...}

and when I want to use a configuration parameter I can just write:

  cfg.cfl

i.e. no checking and very efficient.

[krenzland]

In Step 1.1 make sure to add a version, the current format being version 1 or so. This way you might not even need to deprecate the old format.

It would be better IMO to add version numbers to SeisSol and add this number to the configuration file.

(Keep in mind that there are published setups on Zenodo. I'm not saying one needs to support these until t -> inf, but one also doesn't need to break them if there's no good reason.)

Sorry but I don't see the point. They should be reproducible but they still are. Just use an older version of SeisSol. We can make breaking changes, it is a research code. See also our official README "SeisSol is still under heavy development and comes without any guaranteed funcitonality. At the moment we can only provide very limited support for general users."
Every setup on Zenodo should point to the SeisSol version for which it works with.
If we had version numbers we could use SemVer and make this exploit. That'd be the professional way.

So your proposal is to interpret Fortran namelists as a dialect of .ini/TOML? Sounds good and should be easy to write a parser.

No, it is not my idea, but this is also interesting. How could we handle differently structured configuration files in different formats? E.g. I want to have the ability to add multiple output writers, say two free surface writers with different filters. This feature would be very important for me.

For the rest I agree in principle, that is nicer than parsing them manually.

[uphoffc]

How could we handle differently structured configuration files in different formats?

You could have a Schema for each configuration file. You then need some code to fill the entries of one configuration struct with values of the other -- but you need such functionality anyhow if you have multiple configuration formats.

[krenzland]

if you have multiple configuration formats
Yeah, we probably don't want to have that in the long term. Exahype had this approach and people never switched to the newer format. (which was a strange json thing, so who can blame them)

Okay, that makes sense.
The problem would still be how we get these values into the Fortran part of the code with minimal effort.
My idea would be to generate a fortran namelist file and reuse the old routine. This is extremely ugly but doesn't impose any work on us and it should be a relatively reliable (and testable) way.

[Thomas-Ulrich]

Hi,
Would a simple let say python converter from old to new be sufficient to ensure backward compatibility?
Then we can drop readpar.f90 and replace by something better.
I think we do not need to support both.

[krenzland]

Yes, that'd be step 2 in my proposed plan. Step 1 would just be for convenience.

[davschneller]

Hi... Time to drag out this old thread again.

By now, we've done the plan in reverse (after #829 and following), I'd guess:

• Step 3 is done (we have the suggested schemas distributed over LtsParameters, SeisSolParameters and the dynamic rupture parameters)
• Step 2 is partially done (fully-C++ parsing is complete, but we still use the same old .par files)
• Step 1 has not been started yet—we'd have to define a new input format first I'd guess

In short, we'd need a new format in the end. In the long run, at least. We are now also able to go more tree-like (e.g. have a node output and each output format like wavefield or surface gets its own subnode)

And just to put forward the idea again: I'd love to just have something like a struct annotation which automatically generates us serialization code, like the derive terms in Rust (which there use a preprocessor). But I'd guess if that doesn't already exist, it's not worth implementing. :/

[sebwolf-de]

I've drafted a yaml format for the parameter files. My suggestions are here: https://docs.google.com/document/d/1ljvCQcSwa2B0sENY4SDD4o5homUFPB-s7x4Y5GqG_eA/edit?usp=sharing
Right now, we could just implement a(nother) yaml reader, which reads proper yaml files and not Fortran namelists, converted to yaml.

[davschneller]

Thanks! Once we're settled on a format, we may also need some compatibility script to convert namelists to the new SeisSol format.
(I've added some comments to it—we could think of using more different YAML features like lists etc)

A more general question... Now we have easi files as YAML (or maybe soon lua as in tndm?), and soon the config files are YAML... Should we maybe think about either merging or splitting all these files?

Would it make sense to have a giant model parameter file which includes both the easi content and the Simulation section? (i.e. define material and attenuation parameters etc) ... Maybe DR can be in a separate file or in the same one.
The reasoning behind that is to have a model together with a mesh, and then the purely simulation-dependent parameters in another file. If that differentiation makes sense.

[uphoffc]

Thanks! Once we're settled on a format, we may also need some compatibility script to convert namelists to the new SeisSol format.
(I've added some comments to it—we could think of using more different YAML features like lists etc)

Instead of having a separate compatibility script I'd rather leave support for parsing parameters.par in SeisSol along with a deprecation notice for the following reasons:

• A separate compatibility script is going to break within two weeks because you're not forced to update it if you change something in internal configuration structure of SeisSol.
• There are many published parameters.par, e.g. on Zenodo. Running ./SeisSol parameters.par is much simpler than looking for some script somewhere.
• The YAML format has no immediate benefit for the user. Yes there might be great features introduced, but the current draft is more or less the same as the parameters.par, just with more white-space. (That's no criticism of the new format - it's good to start simple.) So why force users to immediately learn a new format?

Moreover, please add a mandatory version number to the YAML format!

[krenzland]

I argue against keeping support for the old version.
Especially because:

There are many published parameters.par, e.g. on Zenodo. Running ./SeisSol parameters.par is much simpler than looking for some script somewhere.

Then people can use the old SeisSol version for which the simulations used to work.

I'm arguing for removing the old parameter because this would be something we'd need to maintain, which can become painful (and difficult to test) once we decide to add features. It should at least be deprecated for some release and then eventually be removed entirely.
This would mean releasing SeisSol v2.0.0 of course.

Moreover, please add a mandatory version number to the YAML format!
Agreed. Probably something like "SeisSolVersion": "major.minor.patch" and then give a warning when major != current major, or version is to small. Basically follow semver

[krenzland]

By the way, the workflow could also be that SeisSol automatically runs the compability script when it encounters the legacy format. This would be the best of both worlds?

[sebwolf-de]

Sure, we don't need to support the parameters file endlessly. But I propose to have the yaml option available from now on in parallel to the namelists, no additional feature.
Then at some point, the yaml parameter file will have more features (e.g. more flexible output config), then we can fade out support for the namelists.

[krenzland]

I've seen this exact thing with the Exahype software. They designed a new configuration format but everyone kept using the legacy format.. IMO you have to do a hard cut at some point, otherwise you'll end up supporting the old format forever. (However, this won't affect us both anyway, so maybe it's something for the "new generation" to decide!)

[davschneller]

If it's just allowing YAML, that should be possible immediately: all we have to do is to skip the fty step.

Thinking about everything... We may want a compatibility script/option at this point of time already—even just for the namelists, given the changes documented in https://seissol.readthedocs.io/en/latest/breaking-changes-backward-compatibility.html and what was done in #829 , implicitly (that is, the output mask is not as forgiving for wrong/too long values as it once was). I.e. the namelists may have also profited/may also profit from versioning already now—also who knows what older files lie around there.

... maybe, if we allow/switch to YAML (I'd agree that we may have to make a hard cut here some day one we have more features—also the parameter names have become a bit illogical IMO), we could also e.g. provide a console or web GUI for the parameter files to spread the new format more easily—if that could help? (console GUIs seem to be well-doable using something like Python textual or similar)

[sebwolf-de]

By the way, the workflow could also be that SeisSol automatically runs the compability script when it encounters the legacy format. This would be the best of both worlds?

This compability script kind of exists and already is kind of in use ;-)