Parcels v4 FieldSet design documentation

docs/conf.py

@@ -43,6 +43,7 @@
     "myst_parser",
     "nbsphinx",
     "numpydoc",
+    "sphinxcontrib.mermaid",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -207,6 +208,7 @@
             "type": "fontawesome",
         }
     ],
+    "announcement": "WARNING: This documentation is built for v4 of Parcels, which is unreleased and in active development. Use the version switcher in the bottom right to select your version of Parcels, or see <a href='https://docs.oceanparcels.org/'>stable docs</a>.",
 }
 
 html_context = {

docs/index.rst

@@ -1,11 +1,6 @@
 Parcels documentation
 =====================
 
-.. danger::
-
-   This documentation is built for v4 of Parcels, which is unreleased
-   and in active development. Use the version switcher in the bottom
-   right to select your version of Parcels.
 
 Welcome to the documentation of Parcels. **Parcels** (Probably A Really Computationally Efficient Lagrangian Simulator) is a set of Python classes and methods to create customisable particle tracking simulations using output from Ocean Circulation models. Parcels can be used to track passive and active particulates such as water, plankton, `plastic <http://www.topios.org/>`_ and `fish <https://github.com/Jacketless/IKAMOANA>`_.
 
@@ -22,6 +17,7 @@ If you need more help with Parcels, try the `Discussions page on GitHub <https:/
    :hidden:
 
    Home <self>
+   v4 <v4/index>
    Installation <installation>
    Tutorials & Documentation <documentation/index>
    API reference <reference>

docs/v4/api.md

@@ -0,0 +1,41 @@
+# API design document
+
+## Field data input
+
+Here is the proposed API for Field data ingestion into Parcels.
+
+```{mermaid}
+
+classDiagram
+    class Fieldset{
+        +List[Field] fields
+    }
+    class Field{
+        +xr.Dataset|xr.DataArray|ux.Dataset|ux.DataArray data
+        +parcels.Grid|ux.Grid grid
+        +Interpolator interpolator
+        +eval(...)
+    }
+
+    class Interpolator{
+        +assert_is_compatible(Field)
+        +interpolate(Field, ...)
+    }
+
+
+    <<Protocol>> Interpolator
+
+    Fieldset ..> Field : depends on
+    Field ..> Interpolator : depends on
+    Interpolator <|.. ScalarInterpolator : Realization of
+    Interpolator <|.. VectorInterpolator : Realization of
+    Interpolator <|.. etc : Realization of
+```
+
+Here, important things to note are:
+
+- Interpolators (which would implement the `Interpolator` protocol) are responsible for the actual interpolation of the data, and performance considerations. There will be interpolation and indexing utilities that can be made available to the interpolators, allowing for code re-use.
+
+- In the `Field` class, not all combinations of `data`, `grid`, and `interpolator` will logically make sense (e.g., a `xr.DataArray` on a `ux.Grid`, or `ux.DataArray` on a `parcels.Grid`). It's up to the `Interpolator.assert_is_compatible(Field)` to define what is and is not compatible, and raise `ValueError` / `TypeError` on incompatible data types. The `.assert_is_compatible()` method also acts as developer documentation, defining clearly for the `.interpolate()` method what assumptions it is working on. The `.assert_is_compatible()` method should be lightweight as it will be called on `Field` initialisation.
+
+- The `grid` object, in the case of unstructured grids, will be the `Grid` class from UXarray. For structured `Grid`s, it will be an object similar to that of `xgcm.Grid` (note that it will be very different from the v3 `Grid` object hierarchy).

docs/v4/index.md

@@ -0,0 +1,10 @@
+# v4 development
+
+This is a central hub to discuss the development of v4. As development progresses, some of the pages mentioned here will be incorporated into the main documentation.
+
+You can think of this as a "living" document as we work towards the release of v4.
+
+```{toctree}
+
+api
+```

environment.yml

@@ -46,3 +46,4 @@ dependencies:
   - pydata-sphinx-theme
   - sphinx-autobuild
   - myst-parser
+  - sphinxcontrib-mermaid