Schema polymorphism

[wpbonelli]

This is a concept we have been groping towards / grappling with recently, initially in regards to NetCDF support, but it also applies to the MF6 input schema more generally.

As one constructs an MF6 simulation, there are choices to make about how to represent things. The user faces a decision graph. Some decisions are orthogonal, some are conditional on other decisions. Some decisions confine the user to a tree in a given scope. Any materialization of the schema into a simulation is (at least partially) path-dependent.

Different paths through the decision graph may produce functionally (hydrologically equivalent) simulations: choices may be made for convenience, though the choice of one or another path is most often motivated by hydrologic or practical considerations (i.e., certain representations are more suitable for some modeling situations than others).

An example of functional equivalence with path dependence includes the choice between list, layer-array, and grid-array packages. These package variants exist to provide the user flexibility in specifying array data. Support for these variants is not comprehensive across boundary packages, but (at least for now) consists of a patchwork tailored to typical use cases, e.g., layer-array for conditions most commonly applied only to one (e.g. the top) layer: EVTA, RCHA. The package variant you choose (either by enabling READASARRAYS in an MF6 input file, or using a Evta Python class instead of Evt) determines how you must provide array values.

Another example is mesh type selection for NetCDF-based models. For instance, to convert a model specified in terms of a structured grid to an unstructured (e.g. UGRID layered mesh) representation entails not only converting the grid representation itself, but all array variables.

A third example re: NetCDF support is that currently MF6 ASCII files "drive" the simulation's configuration, dictating whether to load input data from NetCDF files for particular models, as well as which particular variables to load from a given model NetCDF file. Thus a NetCDF input file path in a model namefile indicates that a NetCDF file is expected, and NETCDF values in package input files indicate that the NetCDF file must contain certain variables.

Schema polymorphism is particularly relevant for the design of a Python object model (e.g., via pydantic discriminated unions) and for documentation (e.g., choosing which among equivalent representations to show in examples or recommend in the absence of other criteria).