Skip to content

Commit 258526d

Browse files
authored
sketch xarray extension plan for convention compliance (#191)
describe how we can support different views of the same underlying simulation data for the different forms (structured vs UGRID) supported for the emerging MF6 NetCDF spec
1 parent 929442a commit 258526d

File tree

1 file changed

+13
-5
lines changed

1 file changed

+13
-5
lines changed

docs/dev/sdd.md

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ Components are specified by **definition files**. A definition file specifies a
6262

6363
## Object model
6464

65-
The product's main use cases will include creating, manipulating, running, and inspecting MODFLOW 6 simulations. It is natural to provide an object-oriented interface in which every MF6 component module will generally have a corresponding class.
65+
The product's main use cases include creating, manipulating, running, and inspecting MODFLOW 6 simulations. It is natural to provide an object-oriented interface in which every MF6 component module will generally have a corresponding class.
6666

6767
There are many ways to implement an object model in Python: dictionaries, named tuples, plain classes, `dataclasses`, etc.
6868

@@ -81,6 +81,8 @@ Components in `imod-python` encode parent/child relations in a dictionary, which
8181

8282
The product aims instead for typed components, where children can be read off the class definition. This pulls structural validation from runtime to type-checking time, so invalid arrangements are visible in e.g. IDEs with Intellisense.
8383

84+
### Core design
85+
8486
The product adopts the standard library `dataclasses` paradigm for class definitions. The `dataclasses` module is derived from a project called [`attrs`](https://www.attrs.org/en/stable/) with [more power](https://threeofwands.com/why-i-use-attrs-instead-of-pydantic/). `attrs` permits terse class definitions, e.g.
8587

8688
```python
@@ -107,13 +109,19 @@ Combining `attrs` and `xarray` in this way presents challenges involving duplica
107109

108110
The sparse, record-based list input format used by MODFLOW 6 is also in some tension with `xarray`, where it is natural to disaggregate tables into an array for each constituent column — this requires a nontrivial mapping between data as read from input files and the values eventually accessible through `xarray` APIs.
109111

110-
## IO
112+
### Convention compliance
113+
114+
Being based on `xarray`, the product can support the [MODFLOW 6 NetCDF specification](https://github.com/MODFLOW-ORG/modflow6/wiki/MODFLOW-NetCDF-Format) via `xarray` extension points: custom indices and accessors.
111115

112-
IO is at the boundary of the product. Details of any particular input or output format should not contaminate the product's object model.
116+
Different "views" of the same underlying components may be provided for each relevant convention through these extension points.
113117

114-
The product provides an IO framework with which de/serializers can be registered for arbitrary components and formats.
118+
The product can define a custom index and accessor (e.g. `.grid`) providing a structured grid specification. The product can adopt the [`xugrid` library](https://github.com/Deltares/xugrid) for UGRID support.
119+
120+
While custom indices will enable indexing and selection directly on datasets, the accessors can provide utilities for plotting, export, etc. For instance, `xugrid` provides a [`.to_netcdf()` function](https://deltares.github.io/xugrid/api/xugrid.UgridDatasetAccessor.to_netcdf.html). Selecting the scheme in which to write simulation input files then reduces simply to calling `.to_netcdf()` through the appropriate accessor.
121+
122+
## IO
115123

116-
The product will allow IO to be configured globally, on a per-simulation basis, or at read/write time via method parameters.
124+
IO is at the product's boundary. Details of any input or output format should not be coupled to the object model.
117125

118126
### Input
119127

0 commit comments

Comments
 (0)