Pass catchment hydrofabric attributes to BMI models as model_params

[mattw-nws]

Especially wIth GeoPKG hydrofabric support in #522, add the ability to pass attributes from the features to the BMI model stack. The foremost use-case is to pass area_sqkm to a lumped module that needs it to convert rainfall depth to volume, but also we may store other model-specific or general attributes/parameters in the hydrofabric where appropriate.

These parameters/values should be passed only once, before the input variables (gotten from get_input_var_names) are passed--at about the same time as any model_params from the realization config are passed, and using a similar mechanism. A model accepting such a parameter should respond properly to metadata functions for that parameter such as get_var_type and this information should determine how the value is passed to the module.

Preferably, some mechanism should be designed such that the value is only attempted to be set on a BMI model that needs it--possibly using the existing model_params feature with an object value (instead of a numeric value) that indicates that the source of the parameter is the hydrofabric. Some way of mapping the hydrofabric attribute name to a model parameter name--which may be different--is also desirable, e.g. leverage variables_names_map or allow aliasing information in a JSON key within model_params.

This feature is focused on lumped catchment models defined in the hydrofabric. Future similar use-cases to keep in mind:

• Nexus attributes may be passed to the BMI version of a routing module (e.g. roughness coefficient)
• We may in the future, for gridded models, have a (non-hydrofabric) grid parameter file (e.g. NetCDF file) with one or more parameter variables which would need to be made available to the model using a similar idiom.

Current behavior

No information from the hydrofabric is made available to BMI models

Expected behavior

A BMI model (including nested models in a multi-BMI stack) should be able to have attributes from the hydrofabric passed to it.

Steps to replicate behavior (include URLs)

Screenshots

[mattw-nws]

A valid special case occurs to me... the id attribute... We will want to pass this through also when we implement this. We may however want to rename it... feature_id? hydrofabric_feature_id? This will probably be useful for some iterative approaches to forcing BMI models, particularly. Also there may be scenarios where a model may want this ID so that it could look up data in its own file/tables... again, hopefully as an interim solution to something better, but in research scenarios it may only get this far.

[program--]

Some Notes:

• model_params is set with the call to Bmi_Module_Formulation::set_initial_bmi_parameters(1) within Bmi_Module_Formulation::inner_create_formulation(2).
• The first argument of the create formulation function is a geojson::PropertyMap representing the realization config (not the feature properties)
• Bmi_Module_Formulation::inner_create_formulation(2) is only used within the definitions for Bmi_Module_Formulation::create_formulation
• Bmi_Module_Formulation::create_formulation is then generally called from a Formulation_Manager in Formulation_Manager::construct_formulation_from_tree(5)
• The formulation manager construction function is called from its own read(2) function, with the above properties being passed within arg 3 (tree). However, only read(2) has access to the hydrofabric data

To accomplish what this issue requires, I think we'd want to move the properties from the fabric parameter, over into the realization config tree so that the model_params key contains the new properties during runtime. Assuming my understanding is correct, we can do that within the Formulation_Manager::read(2) function 🤔

As for representing which keys must be taken, maybe we have a designated object scheme within model_params? (as @mattw-nws suggests) For example,

"model_params": {
  "sloth_ice_fraction_schaake(1,double,m,node)": 0.0,
  "sloth_ice_fraction_xinan(1,double,1,node)": 0.0,
  "sloth_smp(1,double,1,node)": 0.0,
  "areasqkm": {
    "from": "hydrofabric",
    "as": "area_sqkm"
  }
}

This also potentially allows for alternative sources to be specified and joined on startup (i.e. sidecar files, with from: being a path)

[program--]

Some more notes:

After some initial investigation/work, I think we can conceptualize these additional model parameters as dynamic parameters (like the et_params), since these most likely need to be joined/set as each catchment is run.

However, the responsibility of this gets very muddled in the NGen executable code, since we only have access to a Catchment_Formulation pointer, which does not expose any direct BMI functionality.

...I think I need to think through this a bit more, since it might be better to approach this from the feature side, rather than the formulation side (though I'm not sure that's the "correct" way)