Add shift_barotropic_streamfunction() to the docs

Author: xylar

conda_package/docs/api.rst

@@ -227,6 +227,7 @@ Ocean Tools
    depth.compute_zmid
 
    compute_barotropic_streamfunction
+   shift_barotropic_streamfunction
 
 .. currentmodule:: mpas_tools.ocean.inject_bathymetry
 

conda_package/docs/ocean/streamfunction.rst

@@ -22,3 +22,18 @@ For large meshes, performance and memory usage can be improved by specifying
 the ``horiz_chunk`` argument to control the number of edges processed at once,
 and by providing a ``tmp_dir`` argument to use a temporary directory for
 intermediate files.
+
+Shifting the barotropic streamfunction
+--------------------------------------
+
+The function :py:func:`mpas_tools.ocean.shift_barotropic_streamfunction()`
+can be used to shift the barotropic streamfunction so that its mean value is
+zero on the boundary within a specified latitude range. This is useful for
+setting a consistent reference for the streamfunction, especially when
+comparing results across different regions or simulations.
+
+The function takes as input the barotropic streamfunction on vertices,
+a latitude range (in degrees), the ``cellsOnVertex`` and ``latVertex``
+arrays from the mesh, and optionally a logger. It returns a shifted
+streamfunction with the mean value on the boundary (within the latitude
+range) subtracted.

conda_package/mpas_tools/ocean/__init__.py

@@ -22,3 +22,6 @@
 from mpas_tools.ocean.streamfunction.barotropic import (
     compute_barotropic_streamfunction as compute_barotropic_streamfunction,
 )
+from mpas_tools.ocean.streamfunction.barotropic import (
+    shift_barotropic_streamfunction as shift_barotropic_streamfunction,
+)