API, changelog

Deltares · Sep 6, 2024 · fc55760 · fc55760
1 parent 9becbac
commit fc55760
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 0 deletions.
diff --git a/docs/api.rst b/docs/api.rst
@@ -195,6 +195,8 @@ UGRID1D Topology
     Ugrid1d.sizes
     Ugrid1d.attrs
     Ugrid1d.coords
+    Ugrid1d.fill_value
+    Ugrid1d.start_index
 
     Ugrid1d.n_node
     Ugrid1d.node_dimension
@@ -258,6 +260,8 @@ UGRID2D Topology
     Ugrid2d.sizes
     Ugrid2d.attrs
     Ugrid2d.coords
+    Ugrid2d.fill_value
+    Ugrid2d.start_index
 
     Ugrid2d.n_node
     Ugrid2d.node_dimension

diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -26,6 +26,29 @@ Fixed
   value; the fill value is also set when calling
   :meth:`xugrid.UgridDataArrayAccessor.to_netcdf` or
   :meth:`xugrid.UgridDatasetAccessor.to_netcdf`.
+
+Added
+~~~~~
+
+- :class:`xugrid.Ugrid1d` and :class:`xugrid.Ugrid2d` now take an optional
+  ``start_index`` which controls the start index for the UGRID connectivity
+  arrays.
+- :attr:`xugrid.Ugrid1d.fill_value`, :attr:`xugrid.Ugrid1d.start_index`,
+  :attr:`xugrid.Ugrid2d.fill_value`, and :attr:`xugrid.Ugrid2d.start_index`,
+  have been added to get and set the fill value and start index for the UGRID
+  connectivity arrays. (Internally, every array is 0-based, and has a fill
+  value of -1.)
+
+Changed
+~~~~~~~
+
+- :class:`xugrid.Ugrid1d` and :class:`xugrid.Ugrid2d` will generally preserve
+  the fill value and start index of grids when roundtripping from and to xarray
+  Dataset. An exception is when the start index or fill value varies per
+  connectivity: ``xugrid`` will enforce a single start index and a single fill
+  value per grid. In case of inconsistent values across connectivity arrays,
+  the values associated with the core connectivity are used: for Ugrid2d, this
+  is the face node connectivity.
 
 [0.12.0] 2024-09-03
 -------------------

diff --git a/xugrid/ugrid/ugridbase.py b/xugrid/ugrid/ugridbase.py
@@ -353,6 +353,7 @@ def copy(self):
 
     @property
     def fill_value(self) -> int:
+        """Fill value for UGRID connectivity arrays."""
         return self._fill_value
 
     @fill_value.setter
@@ -361,6 +362,7 @@ def fill_value(self, value: int):
 
     @property
     def start_index(self) -> int:
+        """Start index for UGRID connectivity arrays."""
         return self._start_index
 
     @start_index.setter