From d743aa8ddb9fd91859353637241dc1bc880787ad Mon Sep 17 00:00:00 2001
From: Xylar Asay-Davis <xylarstorm@gmail.com>
Date: Sun, 15 Oct 2023 13:42:51 +0200
Subject: [PATCH] Update docs with vector class and vector reconstruction

---
 conda_package/docs/index.rst  |  2 ++
 conda_package/docs/vector.rst | 63 +++++++++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 conda_package/docs/vector.rst

diff --git a/conda_package/docs/index.rst b/conda_package/docs/index.rst
index 92de5b6f2..f2866cd66 100644
--- a/conda_package/docs/index.rst
+++ b/conda_package/docs/index.rst
@@ -31,6 +31,8 @@ analyzing simulations, and in other MPAS-related workflows.
 
    transects
 
+   vector
+
    visualization
 
 .. toctree::
diff --git a/conda_package/docs/vector.rst b/conda_package/docs/vector.rst
new file mode 100644
index 000000000..11520613b
--- /dev/null
+++ b/conda_package/docs/vector.rst
@@ -0,0 +1,63 @@
+.. _vector:
+
+*****************
+Vector Operations
+*****************
+
+MPAS-Tools has a ``Vector`` class and an unrelated tool for performing
+vector reconstructions at cell centers from fields defined at edge normals.
+
+.. _vector_class:
+
+Vector Class
+============
+
+The :py:class:`mpas_tools.vector.Vector` class defines a single vector (with
+components that are floats) or a vector field (with components that are
+:py:class:`numpy.ndarray` objects).  See the API documentation for the
+individual methods to find out more.
+
+
+.. _vector_reconstruct:
+
+Vector Reconstructions
+======================
+
+The command-line tool ``vector_reconstruct`` and the function
+:py:func:`mpas_tools.vector.reconstruct.reconstruct_variable()` are used to
+reconstruct Cartesian (X, Y, Z), zonal and meridional components of an MPAS
+vector field at cell centers, given the field on edge normals.
+
+This tool requires that the field ``coeffs_reconstruct`` has been saved to a
+NetCDF file.  The simplest way to do this is to include the following
+stream in a forward run:
+
+.. code-block:: xml
+
+    <stream name="vector_reconstruction"
+            clobber_mode="truncate"
+            type="output"
+            output_interval="initial_only"
+            filename_template="vector_reconstruction.nc">
+
+        <var name="coeffs_reconstruct"/>
+    </stream>
+
+and run the model for one time step.
+
+Then, ``vector_reconstruct`` is called with:
+
+.. code-block::
+
+    $ vector_reconstruct --help
+    usage: vector_reconstruct [-h] [-m MESH_FILENAME] [-w WEIGHTS_FILENAME] -i
+                              IN_FILENAME -v VARIABLES [VARIABLES ...]
+                              [--out_variables OUT_VARIABLES [OUT_VARIABLES ...]]
+                              -o OUT_FILENAME
+
+You must supply input and output files and a list of one or more variables on
+edge normals to reconstruct.  You can optionally supply a separate file that
+contains the MPAS mesh if it is not part of the input file, a file with
+``coeffs_reconstruct`` if it is not in the input file, and a list of variable
+prefixes corresponding to each variable supplied that should be prepended to
+the Cartesian, zonal and meridional reconstructions for that variable.