re-organized some headings in gradient tutorial

Author: andrewdelman

Tutorials_as_Jupyter_Notebooks/ECCO_v4_Gradient_calc_on_native_grid.ipynb

@@ -7,7 +7,9 @@
     "tags": []
    },
    "source": [
-    "*Contributors*: [Ian Fenty](https://github.com/ifenty), [Andrew Delman](https://github.com/andrewdelman).\n",
+    "# Calculating gradients and curl on the ECCO native grid\n",
+    "\n",
+    "*Contributors*: [Ian Fenty](https://github.com/ifenty), [Andrew Delman](https://github.com/andrewdelman) (ed.).\n",
     "\n",
     "## Objectives\n",
     "\n",
@@ -35,9 +37,9 @@
     "\n",
     "We first demonstrate how to calculate zonal/meridional gradients of scalar fields, then gradients of vector fields provided at model 'u' and 'v' points, and finally gradients of vector fields provided at model tracer points (using atmosphere surface winds)\n",
     "\n",
-    "## Preliminaries:\n",
+    "## Preliminaries\n",
     "\n",
-    "### Preliminaries: Prepare the working enviornment"
+    "### Prepare the working enviornment"
    ]
   },
   {
@@ -140,7 +142,7 @@
    "id": "ee0e86f2-eb56-4914-bc3d-8ee4f55e968d",
    "metadata": {},
    "source": [
-    "### Preliminaries: Load ECCO Geometry\n",
+    "### Load ECCO Geometry\n",
     "\n",
     "First, load the llc model grid geometry."
    ]
@@ -190,7 +192,7 @@
    "id": "d02addec-8607-432c-a23b-dd28ad884460",
    "metadata": {},
    "source": [
-    "### Preliminaries: Rotating between the model's vector basis and vector basis of parallels ($\\lambda$) and meridians ($\\phi$)"
+    "### Rotating between the model's vector basis and vector basis of parallels ($\\lambda$) and meridians ($\\phi$)"
    ]
   },
   {
@@ -416,7 +418,7 @@
     "tags": []
    },
    "source": [
-    "### Preliminaries: The logical connection between geographically adjacent tile edges\n",
+    "### The logical connection between geographically adjacent tile edges\n",
     "\n",
     "To calculate gradients for grid cells on the edges of model tiles we will need information from from logically adjacent tiles. For example, to calculate zonal gradients along the eastern edge of Tile 1 we need information found along the western edge of Tile 4 (i.e., we need to difference the field in the last column of Tile 1 and the first column of Tile 4) and gradients across the western edge of Tile 4 need information found along the eastern edge of Tile 8 (i.e., we need to difference the field in the last column of Tile 4 and the reversed first row of Tile 8). Managing these connections requires careful bookkeeping.  Fortunately the 'xgcm' Python library (https://xgcm.readthedocs.io/en/latest/) allows us to construct a logical map that specifies the logical relation between tiles. *So useful!*. \n",
     "\n",
@@ -1580,25 +1582,39 @@
     "tags": []
    },
    "source": [
-    "## Calculating zonal and meridional gradients of **vector** ECCO fields located on the 'u' and 'v' points\n",
+    "## Calculating gradients of vector fields located on the 'u' and 'v' points (vorticity/divergence)\n",
     "\n",
     "The ECCO model uses the Arakawa-C grid where velocities and horizontal fluxes are located at the grid cell edges (i.e., the 'u' and 'v' points), unlike scalar fields which are located at the grid cell centers (tracer points).\n",
     "\n",
-    "Gradients of vector fields located at 'u' and 'v' points are themselves located at tracer points, \"halfway\" between adjacent grid cell edges. The meridional and zonal gradients of vector fields, e.g., horizontal ocean velocity, yield four vectors:\n",
-    "1. Zonal gradient of the **zonal component** of the vector \n",
-    "1. Zonal gradient of the **meridional component** of the vector \n",
-    "1. Meridional gradient of the **meridional component** of the vector \n",
-    "1. Meridional gradient of the **zonal component**  of the vector \n",
+    "Gradients of vector fields located at 'u' and 'v' points are themselves located at tracer points, \"halfway\" between adjacent grid cell edges. The meridional and zonal gradients of vector fields, e.g., horizontal ocean velocity, yield four gradient components:\n",
+    "\n",
+    "1. Zonal gradient of the **zonal component** of the vector ($\\partial{u_\\lambda}/\\partial{\\lambda}$)\n",
+    "\n",
+    "1. Zonal gradient of the **meridional component** of the vector ($\\partial{v_\\phi}/\\partial{\\lambda}$)\n",
+    "\n",
+    "1. Meridional gradient of the **meridional component** of the vector ($\\partial{v_\\phi}/\\partial{\\phi}$)\n",
+    "\n",
+    "1. Meridional gradient of the **zonal component**  of the vector ($\\partial{u_\\lambda}/\\partial{\\phi}$)\n",
+    "\n",
+    "Two of these gradients $\\partial{v_\\phi}/\\partial{\\lambda} - \\partial{u_\\lambda}/\\partial{\\phi}$ comprise the vorticity or curl of the flow field, while the other two $\\partial{u_\\lambda}/\\partial{\\lambda} + \\partial{v_\\phi}/\\partial{\\phi}$ comprise the divergence of the flow field.\n",
     "\n",
     "\n",
     "The recipe is as follows:\n",
+    "\n",
     "1. interpolate the 'x' and 'y' components of the flow field, u_x and v_y respectively, to the grid cell centers\n",
-    "1. rotate the u_x and v_y vectors from the orthogonal 'x-y' basis to the orthogonal *lambda-phi* basis, the basis of parallels and meridians to make the u_lambda and v_phi vectors. \n",
+    "\n",
+    "1. rotate the u_x and v_y vectors from the orthogonal 'x-y' basis to the orthogonal *lambda-phi* basis, the basis of parallels and meridians to make the u_lambda and v_phi vectors.\n",
+    "\n",
     "1. calculate the gradients of 'u_lambda' and 'v_phi' with respect to the model's 'x' direction to make *du_lambda_dx* and *dv_phi_dx* vectors\n",
+    "\n",
     "1. calculate the gradients of 'u_lambda' and 'v_phi' with respect to the model's 'y' direction to make *du_lambda_dy* and *dv_phi_dy* vectors\n",
+    "\n",
     "1. interpolate the four gradients to the tracer points\n",
-    "1. rotate the four gradients of the zonal flow with respect to 'x' and 'y' to the zonal and meridional directions to make the *du_lambda_dphi* and *du_lambda_dlambda* vectors \n",
-    "1. rotate the gradients of the meridional flow with respect to 'x' and 'y' to the zonal and meridional directions to make the *dv_phi_dphi* and *dv_phi_dlambda* vectors \n",
+    "\n",
+    "1. rotate the four gradients of the zonal flow with respect to 'x' and 'y' to the zonal and meridional directions to make the *du_lambda_dphi* and *du_lambda_dlambda* vectors\n",
+    "\n",
+    "1. rotate the gradients of the meridional flow with respect to 'x' and 'y' to the zonal and meridional directions to make the *dv_phi_dphi* and *dv_phi_dlambda* vectors\n",
+    "\n",
     "\n",
     "Note: for vorticity calculations we could use 1) *dv_phi_dlambda* and *du_lambda_dphi* or 2) *dv_y_dx* and *du_x_dy*. Vorticity calculated using *dv_phi_dlambda* and *du_lambda_dphi* is calculated at tracer points while vorticity calculated using *dv_y_dx* and *du_x_dy* are calculated at the so-called zeta points (the grid cell corners of tracer cells). Vorticity calculated at zeta points may be more accurate than those calculated at tracer points because fewer interpolations are required. The calculation of vorticity on the zeta points is the subject of a different tutorial.\n",
     "\n",
@@ -2371,24 +2387,36 @@
     "tags": []
    },
    "source": [
-    "## Calculating zonal and meridional gradients of vector ECCO fields located on the grid cell centers\n",
+    "## Calculating gradients of vector fields located on the grid cell centers (wind stress curl)\n",
     "\n",
     "In ECCO llc state estimates the atmosphere forcing vector fields (surface winds/wind stress) are located at the grid cell centers (i.e., the tracer points). It is important to note that, in contrast, horizontal vector fields generated by the model like horizontal velocity (UVEL,VVEL) and horizontal advective and diffusive fluxes are located at the grid cell edges ('u' and 'v' points). \n",
     "\n",
-    "The meridional and zonal gradients of these vector fields are comprised of four vectors:\n",
-    "1. Zonal gradient of the **zonal component** of the vector \n",
-    "1. Zonal gradient of the **meridional component** of the vector \n",
-    "1. Meridional gradient of the **meridional component** of the vector \n",
-    "1. Meridional gradient of the **zonal component**  of the vector \n",
+    "The meridional and zonal gradients of these vector fields yield four gradient components:\n",
+    "\n",
+    "1. Zonal gradient of the **zonal component** of the vector\n",
+    "\n",
+    "1. Zonal gradient of the **meridional component** of the vector\n",
+    "\n",
+    "1. Meridional gradient of the **meridional component** of the vector\n",
+    "\n",
+    "1. Meridional gradient of the **zonal component**  of the vector\n",
+    "\n",
     "\n",
     "\n",
     "The recipe is as follows. It is the same as the recipe for the vector fields located on grid cell edges, except with the first interpolation step omitted:\n",
-    "1. rotate the u_x and v_y vectors from the orthogonal 'x-y' basis to the orthogonal *lambda-phi* basis, the basis of parallels and meridians to make the u_lambda and v_phi vectors. \n",
+    "\n",
+    "1. rotate the u_x and v_y vectors from the orthogonal 'x-y' basis to the orthogonal *lambda-phi* basis, the basis of parallels and meridians to make the u_lambda and v_phi vectors.\n",
+    "\n",
     "1. calculate the gradients of 'u_lambda' and 'v_phi' with respect to the model's 'x' direction to make *du_lambda_dx* and *dv_phi_dx* vectors\n",
+    "\n",
     "1. calculate the gradients of 'u_lambda' and 'v_phi' with respect to the model's 'y' direction to make *du_lambda_dy* and *dv_phi_dy* vectors\n",
+    "\n",
     "1. interpolate the four gradients to the tracer points\n",
-    "1. rotate the four gradients of the zonal flow with respect to 'x' and 'y' to the zonal and meridional directions to make the *du_lambda_dphi* and *du_lambda_dlambda* vectors \n",
-    "1. rotate the gradients of the meridional flow with respect to 'x' and 'y' to the zonal and meridional directions to make the *dv_phi_dphi* and *dv_phi_dlambda* vectors \n",
+    "\n",
+    "1. rotate the four gradients of the zonal flow with respect to 'x' and 'y' to the zonal and meridional directions to make the *du_lambda_dphi* and *du_lambda_dlambda* vectors\n",
+    "\n",
+    "1. rotate the gradients of the meridional flow with respect to 'x' and 'y' to the zonal and meridional directions to make the *dv_phi_dphi* and *dv_phi_dlambda* vectors\n",
+    "\n",
     "\n",
     "### Preliminaries: Load fields"
    ]

doc/index.rst

@@ -67,7 +67,7 @@ The `ecco_v4_py`_ package used in this tutorial was inspired by the `xmitgcm`_ p
 
 .. toctree::
    :maxdepth: 2
-   :caption: Scalar Calculations
+   :caption: Scalar and Vector Calculations
 
    ECCO_v4_Example_calculations_with_scalar_quantities.ipynb
    ECCO_v4_Gradient_calc_on_native_grid.ipynb