Instantiating Clearwater-Riverine with a config file

[sjordan29]

@aufdenkampe, @jrutyna, @xaviernogueira - as I'm thinking about #43, I was wondering if it might be useful to leverage a config file for Clearwater-Riverine. I feel like this approach could have a few advantages:

• Easy to set up for modelers who might not have as much Python experience
• Simple way to turn on / off modules (are they included in the config or not?)
• Easier to add flexibility in the number of general constituents to include
• More transparency on what information is needed for each of the modules from a user standpoint.

I'm envisioning clearwater looking for a config.yml file that looks something like this, which would be the only input for instantiating a Clearwater-Riverine model:

- name: Sumwere Creek Plan 10
- description: Demo model
- path: ./sumwere_creek_p10.hdf
- diffusion_coefficient: 0.1
- modules:
  - gsm:
    - constituent-A:
      - initial_conditions: ./constituent_a_initial_conditions.csv
      - boundary_conditions: ./constituent_a_boundary_conditions.csv
      - order: 0
    - constituent-B:
      - initial_conditions: ./constituent_b_initial_conditions.csv
      - boundary_conditions: ./constituent_b_boundary_conditions.csv
      - order: 0
  - tsm:
    - initial_conditions: ./tsm_initial_conditions.csv
    - boundary_conditions: ./tsm_boundary_conditions.csv
    - meteo_parameters: ./tsm_meteo_parameters.csv
    - temp_parameters: ./tsm_temp_parameters.csv

To me, this feels like a more organized approach for setting up a Clearwater Riverine model than having a ton of optional inputs when instantiating the model, but I'm curious to hear what others thing from both a programming and modelling standpoint.

[jrutyna]

Yes, I am all for using a "config" file. Many of the other models I use have a similar method of model inputs. I can show you examples from other models if you are interested.

[aufdenkampe]

@sjordan29, I really, really like this idea. The General Lake Model (GLM) works like this I also mentioned to @xaviernogueira that it might be the right approach for ClearWater-modules.

[sjordan29]

Great, I'll proceed with this. @jrutyna and @aufdenkampe it would be great if you could send me the config files for other models you've worked with like GLM that use this approach to help me figure out a good structure.

[xaviernogueira]

The config file can be a layer above the model. For Clearwater-modules it doesn't fit as well as inputs can be grids (I guess you could reference gridded files, but then I'd have to add a variety of xarray IO functions and have to be careful to make sure they are the same shapes).

That said, I am happy to build an IO "module" within Clearwater-modules to support whatever access patterns we want, whether it's a YAML, JSON, or just a Python TypedDict.

For running both models together it seems like a great choice! Maybe we should discuss, potentially after NSM gets farther, as the types of options available with that module are pretty diverse.

One note is that for YAML it is standard practice to not start unintended lines with a "-". I.e.,

modules:
  - gsm:
    - constituent-A:

[aufdenkampe]

@sjordan29, an example of the General Lake Model (GLM) config file is here: https://github.com/LimnoTech/GLM-modeling/blob/main/DALWST/glm3.nml

The connected Aquatic EcoDynamics (AED) module example is here: https://github.com/LimnoTech/GLM-modeling/blob/main/DALWST/aed/aed.nml

@xaviernogueira, Note that the AED config file lists up front which module modules to include, similar to what we want to do for ClearWater-modules.

FYI, both GLM and AED use the Fortran Namelist (.nml) syntax, but I think we all agree to do this one with YAML.

Here's the documentation: https://aquaticecodynamics.github.io/glm-workbook/glm-file-structure.html#glm-configuration-file-glm3.nml