Adding beginner friendly explanations on the Docs

docs/tutorials.rst

@@ -7,4 +7,6 @@ Tutorials & Videos
 
 Tutorials
 ---------
-* `Project Pythia Unstructured Grid Visualization Cookbook <https://projectpythia.org/unstructured-grid-viz-cookbook>`_
+* `Project Pythia Unstructured Grid Visualization Cookbook <https://projectpythia.org/unstructured-grid-viz-cookbook>`_ - A series of guides in the form of Jupyter notebooks. Shows code, examples, visualizations for various uses of ``uxarray``.
+* `UXarray Tutorial at ESDS 2024 <https://www.youtube.com/watch?v=sOCMSLZrwQs>`_ - A YouTube video presentation by one of the lead UXarray developers on the motivation of UXarray, its origins, and uses.
+* `UXarray Presentation at SciPy 2023 <https://www.youtube.com/watch?v=qwqJeOO8m6A>`_ - A second YouTube video presentation by another one of the lead UXarray developers on UXarray at SciPy 2023.

docs/user-guide/data-structures.ipynb

@@ -24,8 +24,8 @@
     "The core functionality of UXarray revolves around three data structures, which are used for interacting with unstructured grids and the data variables that reside on them.\n",
     "\n",
     "1. **[`uxarray.Grid`](https://uxarray.readthedocs.io/en/latest/generated/uxarray.UxDataArray.html)**: Stores the grid representation (i.e. coordinates, connectivity information, etc.)\n",
-    "2. **[`uxarray.UxDataset`](https://uxarray.readthedocs.io/en/latest/api.html#uxdataset)**: One or more data variable that resided on a grid.\n",
-    "3. **[`uxarray.UxDataArray`](https://uxarray.readthedocs.io/en/latest/api.html#uxdataarray)**: A single data variable that resides on a grid\n"
+    "2. **[`uxarray.UxDataset`](https://uxarray.readthedocs.io/en/latest/api.html#uxdataset)**: One or more data variables that resided on a grid. Each variable is stored in a UxDataArray.\n",
+    "3. **[`uxarray.UxDataArray`](https://uxarray.readthedocs.io/en/latest/api.html#uxdataarray)**: A single data variable that resides on a grid.\n"
    ]
   },
   {
@@ -486,7 +486,10 @@
     }
    },
    "outputs": [],
-   "source": "uxds = ux.open_dataset(grid_path, data_path)\nuxds"
+   "source": [
+    "uxds = ux.open_dataset(grid_path, data_path)\n",
+    "uxds"
+   ]
   },
   {
    "cell_type": "markdown",

docs/user-guide/grid-formats.rst

@@ -242,13 +242,13 @@ Coordinates
 
    <style>
    .yes-cell {
-     background-color: green;
+     background-color: #6aa84f; /* Light green color */
      color: white;
      text-align: center;
    }
 
    .no-cell {
-     background-color: red;
+     background-color: #e06666; /* Light red color */
      color: white;
      text-align: center;
    }

docs/user-guide/terminology.rst

@@ -27,6 +27,11 @@ made up of nodes and edges. Below is an example of an unstructured grid used in
 
 **Node**: A point within a spherical grid, representing the vertices of the elements (such as the corners of triangles or quadrilaterals)
 
+.. image:: ../_static/examples/grids/face_node_edge.png
+  :width: 300
+  :align: center
+  :alt: A visual of the components of a grid
+
 **Edge**: A segment that connects two nodes within a grid.
 
 **Face**: An individual polygon that is defined by nodes connected by edges.

docs/user-guide/unstructured-grids.rst

@@ -0,0 +1,111 @@
+.. currentmodule:: uxarray
+
+================================
+Structured vs Unstructured Grids
+================================
+
+Before diving into unstructured grids, it is helpful to understand the basic differences
+between structured and unstructured grids. Unstructured grids differ from structured grids
+in how they are designed, navigated, and used in modeling functions.
+
+
+Structured Grids - How They're Designed
+=======================================
+
+Structured grids are matrix-like in structure. Just as we can navigate a 2D
+plane using simple coordinates like (2, 2) to (2, 3), a structured grid can be
+navigated predictably because it follows a repeatable pattern.
+
+.. image:: ../_static/examples/grids/structured_grid.png
+  :width: 600
+  :align: center
+  :alt: A structured grid with a regular, matrix-like arrangement of cells
+
+Consider the cell bounded by 19°E–20°E and 19°N–20°N. Its four neighboring cells are bounded by:
+
+    - 19°E–20°E and 20°N–21°N (north),
+    - 19°E–20°E and 18°N–19°N (south),
+    - 20°E–21°E and 19°N–20°N (east), and
+    - 18°E–19°E and 19°N–20°N (west)
+
+You can know the above is true without looking at any data.
+
+Moving along a structured grid has predictable outcomes and observations.
+There are many assumptions you can make about a different cell that is 1 degree East.
+It will have a predictable center, number of sides, and predictable neighboring cells
+of the same characteristics.
+
+Unstructured Grids - How They're Designed
+=========================================
+
+Unstructured grids do not follow a repeated, predictable pattern, and instead
+can vary in shape and organization. Because of this, unstructured grids are
+built like network graphs.
+
+.. image:: ../_static/examples/grids/unstructured_grid.png
+  :width: 600
+  :align: center
+  :alt: An unstructured grid made from hexagons
+
+When you move one degree on a grid like the one above, you may end up in a hole,
+a face of a different shape, or something entirely unexpected. That's why
+the data is traversed by looking at its neighbors from connected edges.
+
+Use Cases
+=========
+
+Many kinds of unstructured grids can exist because of these features.
+
+Some grids use hexagons rather than a rectilinear structure:
+
+.. image:: ../_static/examples/grids/iso_grid.png
+  :width: 600
+  :align: center
+  :alt: An unstructured grid built from hexagonal cells
+
+Others are allowed to have holes that cut out regions that aren't of interest in order to improve efficiency:
+
+.. image:: ../_static/examples/grids/ocean.png
+  :width: 600
+  :align: center
+  :alt: An unstructured ocean grid with holes cut out over land regions
+
+Here a grid changes the size and shape of its cells to provide higher
+resolution in a region of interest and coarser resolution elsewhere:
+
+.. image:: ../_static/examples/grids/cam_se.png
+  :width: 600
+  :align: center
+  :alt: A CAM-SE grid with variable-resolution cells refined over a region of interest
+
+.. note::
+
+   More info about each of the models currently supported can be seen on the `Supported Models & Grid Formats <https://uxarray.readthedocs.io/en/latest/user-guide/grid-formats.html>`__ page
+
+Specialization & Efficiency
+===========================
+
+Structured grids face scalability limits due to several reasons such as global refinement, polar singularity,
+land-ocean boundary fitting, etc. For instance, as the grid resolution scales, a global lat-lon rectilinear grid
+creates too many cells near the poles, wasting massive storage/memory and compute resources for both model generation
+and post-processing & analysis.
+
+Models focused on the equator, like tropical cyclone models, will have a much higher density of cells near the poles
+where they don't need data from, and a much lower density of cells near the equator, due to how the lat-lon grid scales.
+
+On the other hand, models focused on the polar region tend to want more uniform shapes in this region, like the icosahedral
+grid, which is an unstructured grid that contains hexagons of similar size uniformly across the whole grid.
+
+Some of the value of unstructured grids comes from researchers being able to build or adopt
+models that are tailored to their use case. For example, a researcher studying
+measurements made across the planet's many oceans does not want to consider
+cells on land. They can use a model that has no cells on land,
+which creates large holes that structured grids could not run calculations on.
+
+In a traditional lat/lon grid, ~30% of the grid cells in the previous example would be
+unused, meaning the data footprint could be roughly 30% smaller. Many
+calculations will likely require noticeably fewer resources, and less time will be required to
+compute. Many nodes, edges, and faces are eliminated by the removal of the
+land, and even the cells over the sea have fewer connected faces, nodes,
+and edges as a result. These efficiency improvements matter a lot in
+geospatial models, which tend to already be very resource intensive.

docs/userguide.rst

@@ -14,6 +14,9 @@ Introductory Guides
 
 These user guides provide the necessary background information for understanding concepts in UXarray.
 
+`Structured vs Unstructured Grids <user-guide/unstructured-grids.rst>`_
+ Introduction to the concept of unstructured grids
+
 `Terminology <user-guide/terminology.rst>`_
  Core concepts and terminology for working with unstructured grids
 
@@ -26,13 +29,13 @@ These user guides provide the necessary background information for understanding
 Core Guides
 ------------
 
-These user guides provide detailed explanations of the core functionality in UXarray.
+These user guides provide detailed explanations of the core functionality in UXarray
 
 `Data Structures <user-guide/data-structures.ipynb>`_
  Core data structures for working with unstructured grid and data files
 
 `Custom Grid Topology <user-guide/custom-grid.ipynb>`_
- Create a Grid from custom Grid topology and convert existing Xarray data structures to UXarray.
+ Create a Grid from custom Grid topology and convert existing Xarray data structures to UXarray
 
 `Loading Data using Dask <user-guide/parallel-load-ux-with-dask.ipynb>`_
  Read data with chunking and/or in parallel
@@ -50,7 +53,7 @@ These user guides provide detailed explanations of the core functionality in UXa
  Select specific regions of a grid
 
 `Spatial Hashing <user-guide/spatial-hashing.ipynb>`_
- Use spatial hashing to locate the faces a list of points reside in.
+ Use spatial hashing to locate the faces a list of points reside in
 
 `Cross-Sections <user-guide/cross-sections.ipynb>`_
  Select cross-sections of a grid
@@ -109,6 +112,7 @@ These user guides provide additional details about specific features in UXarray.
 .. toctree::
    :hidden:
 
+   user-guide/unstructured-grids.rst
    user-guide/terminology.rst
    user-guide/representation.rst
    user-guide/grid-formats.rst