Prototype

.github/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Setup pixi
         uses: prefix-dev/[email protected]
         with:
-          pixi-version: v0.39.2
+          pixi-version: v0.41.1
           environments: dev
           activate-environment: true
 
@@ -41,7 +41,7 @@ jobs:
       - name: Setup pixi
         uses: prefix-dev/[email protected]
         with:
-          pixi-version: v0.39.2
+          pixi-version: v0.41.1
           environments: dev
           activate-environment: true
 
@@ -77,7 +77,7 @@ jobs:
       - name: Setup pixi
         uses: prefix-dev/[email protected]
         with:
-          pixi-version: v0.39.2
+          pixi-version: v0.41.1
           environments: test${{ matrix.python }}
           activate-environment: true
 

docs/dev/sdd.md

@@ -42,7 +42,21 @@ Component types include:
 - **model**: a simulated hydrological process
 - **package**: a subcomponent of a model or simulation
 
-Certain subsets of packages have distinguishing characteristics. A **stress package** represents a forcing. A **basic package** contains only input variables applying statically to the entire simulation. An **advanced package** contains time-variable (i.e. transient) input data. In some cases, only a single instance of a package is expected — in other cases, arbitrarily many. Packages for which the latter is true are called **multi-packages**.
+Certain subsets of packages have distinguishing characteristics. A **stress package** represents a forcing. A **basic package** contains only input variables applying statically to the entire simulation. An **advanced package** contains time-variable (i.e. transient) input data. Usually only a single instance of a package is expected — when arbitrarily many are permitted, the package is called a **multi-package**. A **subpackage** is a concept only recognized by the product, not by MODFLOW 6 — a package linked to its parent not by a separate input file, but directly (i.e., subpackage data provided to the parent's initializer method). Subpackages may be attached to packages, models, or simulations.
+
+```mermaid
+classDiagram
+    Simulation *-- "1+" Package
+    Simulation *-- "1+" Model
+    Simulation *-- "1+" Variable
+    Simulation *-- "1+" Subpackage
+    Model *-- "1+" Package
+    Model *-- "1+" Subpackage
+    Model *-- "1+" Variable
+    Package *-- "1+" Subpackage
+    Package *-- "1+" Variable
+    Subpackage *-- "1+" Variable
+```
 
 Components are specified by **definition files**. A **definition** specifies input variables for a single MF6 component. A **block** is a named collection of input variables. A definition file specifies exactly one component. A component may contain zero or more blocks. Each block must contain at least one variable.
 
@@ -72,19 +86,21 @@ For nodes in the context tree (i.e., components with children), `.data` can be a
 
 ### `attrs` + `xarray`
 
-Combining these patterns naively would result in data duplication and synchronization challenges.
+Combining these patterns naively would result in several challenges, involving duplication, synchronization, and a more general problem reminiscent of [object-relational impedance mismatch](https://en.wikipedia.org/wiki/Object%E2%80%93relational_impedance_mismatch), where the list-oriented and array-oriented paradigms conflict.
 
-We can arrange instead for `attrs` to proxy `xarray` via `__getattribute__`.
+Ultimately, we'd like a mapping between an abstract hierarchy of components and variables, as defined in MF6 definition files, to a Python representation which is self-describing (courtesy of `attrs`) and self-aligning (courtesy of `xarray`).
 
-Likewise, we can use [`on_setattr`](https://www.attrs.org/en/stable/api.html#core) to intercept values sent to the `attrs` attributes and send them to `xarray`.
+#### Details
+
+We can arrange for `attrs` to proxy `xarray` via `__getattr__`.
 
-We must also intercept arguments passed to the initializer. As a consequence, we cannot rely on `__init__()` methods generated by `attrs`.
+Likewise, we can use [`on_setattr`](https://www.attrs.org/en/stable/api.html#core) to intercept values sent to the `attrs` attributes and send them to `xarray`.
 
-However, other `attrs` functionality should "just work" (e.g. validation, `__repr__`, `__eq__`, etc), due to the operation of `__getattribute__` under the hood.
+Other `attrs` functionality should "just work" (e.g. validation, `__repr__`, `__eq__`, etc), due to the operation of `__getattr__` under the hood.
 
 This combined concept can be packaged in a class decorator, which can be applied to component classes.
 
-The `__init__()` method should not be burdensome to generate via Jinja — it can merely send all arguments to a function which sets corresponding entries in the component's `.data` attribute.
+The `attrs.field` decorator can be used for component variables. We can define a separate decorator for subcomponents.
 
 ## Data types