Dual Mesh Construction

benchmarks/mpas_ocean.py

@@ -101,7 +101,17 @@ def time_dataarray_to_polycollection(self, resolution, periodic_elements):
         self.uxds[data_var].to_polycollection()
 
 
-class ConstructTreeStructures(DatasetBenchmark):
+class ConstructTreeStructures:
+
+    param_names = ['resolution']
+    params = ['480km', '120km']
+
+    def setup(self, resolution):
+        self.uxds = ux.open_dataset(file_path_dict[resolution][0], file_path_dict[resolution][1])
+
+    def teardown(self, resolution):
+        del self.uxds
+
     def time_kd_tree(self, resolution):
         self.uxds.uxgrid.get_kd_tree()
 
@@ -144,6 +154,10 @@ class HoleEdgeIndices(DatasetBenchmark):
     def time_construct_hole_edge_indices(self, resolution):
         ux.grid.geometry._construct_hole_edge_indices(self.uxds.uxgrid.edge_face_connectivity)
 
+class DualMesh(DatasetBenchmark):
+    def time_dual_mesh_construction(self, resolution):
+        self.uxds.uxgrid.get_dual()
+
 class CheckNorm:
     param_names = ['resolution']
     params = ['480km', '120km']

docs/internal_api/index.rst

@@ -191,6 +191,9 @@ Validation
    grid.validation._check_connectivity
    grid.validation._check_duplicate_nodes
    grid.validation._check_area
+   grid.validation._check_duplicate_nodes_indices
+   grid.validation._find_duplicate_nodes
+
 
 Accurate Computing Utils
 ------------------------

docs/user-guide/dual-mesh.ipynb

@@ -0,0 +1,355 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0660f9ec-8fa3-44a7-b362-3aa6526d8550",
+   "metadata": {},
+   "source": [
+    "# Dual Grid Construction"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "974ebf95-c0b1-4397-be4d-bd5cf42cc8bc",
+   "metadata": {},
+   "source": [
+    "A dual grid is a secondary grid built from a grid, by constructing new faces over the original grids nodes. One property of this means that if you take the dual grid of a dual grid, the orignal grid will be constructed. However, this will only work properly if the grid is not partial. UXarray allows the constructing of this dual grid on all three of our data structures using the following methods:\n",
+    "\n",
+    "* `Grid.get_dual()`\n",
+    "* `UxDataArray.get_dual()`\n",
+    "* `UxDataset.get_dual()`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4fd7d3b3-5186-4157-841e-1b4c9f38bb62",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import uxarray as ux\n",
+    "import warnings\n",
+    "\n",
+    "warnings.filterwarnings(\"ignore\")\n",
+    "\n",
+    "plot_kwargs = {\n",
+    "    \"backend\": \"matplotlib\",\n",
+    "    \"aspect\": 2,\n",
+    "    \"fig_size\": 400,\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1eebd05d-506e-4227-aa8e-f1212aae30f2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "file = \"../../test/meshfiles/mpas/QU/mesh.QU.1920km.151026.nc\"\n",
+    "\n",
+    "uxds = ux.open_dataset(file, file)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1e6ddbd8-7034-4ddd-bdd0-4454d76ea390",
+   "metadata": {},
+   "source": [
+    "## Computing the Dual Grid"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dc3b2464-b824-413f-b2e6-40b1e7049f3b",
+   "metadata": {},
+   "source": [
+    "When computing the dual of a grid, the original grid is typically referred to as the \"Primal\" grid. The corner nodes of the Primal grid become the face centers of the Dual grid, and the face centers of the Primal grid become the corner nodes of the Dual grid. This means that variables that were originally face-centered on the Primal grid will be node-centered on the Dual grid, and vice versa. Using UXarray we can construct the dual mesh using `grid.compute_dual()`, which returns a new `Grid` object."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6486e0e4-1908-4363-8196-2efa9e521e56",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "grid = uxds.uxgrid"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "925a82d6-2947-4b15-a3ff-0b0612bc5ba0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "dual = grid.get_dual()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "27fd5578-996e-4cdf-be90-0f50cf322684",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    grid.plot(title=\"Primal\", backend=\"matplotlib\", aspect=2)\n",
+    "    + dual.plot(title=\"Constructed Dual\", backend=\"matplotlib\", aspect=2)\n",
+    ").opts(fig_size=350).cols(1)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e8bf665c-6465-473b-91f5-af180d0de7e1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    grid.plot(title=\"Red=Grid\\nBlue=Dual\", backend=\"bokeh\", color=\"red\")\n",
+    "    * dual.plot(backend=\"bokeh\", color=\"blue\")\n",
+    "    * grid.plot.face_centers(backend=\"bokeh\", size=5, color=\"black\")\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "721498b4-d587-4e4e-b1dc-6d8948a7f3f6",
+   "metadata": {},
+   "source": [
+    "## Computing the Dual Grid with Data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9640cb00-6896-49de-b607-1721a8462d53",
+   "metadata": {},
+   "source": [
+    "We can also take a dual mesh of a `UxDataArray`. The concept for constructing the `Grid` remains the same, and what is constructed will be identical. The difference is the data stored inside the `UxDataArray` will be transfered with the dual mesh. The key differences is the location that the data is stored. The data transfer process works as follows:\n",
+    "\n",
+    "* Face centered data becomes node centered, as each face becomes a node in the dual mesh.\n",
+    "* Node centered data becomes face centered, as each node becomes a face in the dual mesh.\n",
+    "* Edge centered data remains unchanged, as the edge centers will remain in the same place, despite the edges themselves being different."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c55b2285-046d-460c-8e64-1bb204a36177",
+   "metadata": {},
+   "source": [
+    "### Face Centered Data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ebdbc2da-938b-455a-9c84-090faf0e25f9",
+   "metadata": {},
+   "source": [
+    "When constructing the dual mesh paired with a face centered variable, the data becomes node centered. We can then plot this using `topological_mean` to get the dual data to the faces for proper visualization comparisions."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "75e86af7-de9c-4013-91f6-9fd9e9c0c3ad",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "uxds_dual_face = uxds[\"latCell\"].get_dual()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8bbcd1ad-d719-409a-b7f0-a1ad6ec43b78",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    uxds[\"latCell\"].plot.rasterize(\n",
+    "        backend=\"matplotlib\",\n",
+    "        title=\"Face centered data on Primal Mesh\",\n",
+    "        cmap=ux.cmaps.sequential_green_blue,\n",
+    "    )\n",
+    "    + uxds_dual_face.topological_mean(destination=\"face\").plot.rasterize(\n",
+    "        backend=\"matplotlib\",\n",
+    "        title=\"Node Centered Data on Dual Mesh\",\n",
+    "        cmap=ux.cmaps.sequential_green_blue,\n",
+    "    )\n",
+    ").opts(fig_size=350).cols(1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "62d27519-aced-47b0-841e-447bf3a200c2",
+   "metadata": {},
+   "source": [
+    "### Node Centered Data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6819dd2b-91a1-465f-8e2e-11cf14b81a7e",
+   "metadata": {},
+   "source": [
+    "When constructing the dual mesh paired with a node centered variable, the data becomes face centered. A benefit of computing the dual of a node centered variable is that it allows us to visualize the data as polygons."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c68473ae-dac6-422e-b322-71cfbfe3f876",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "uxds_dual_node = uxds[\"xVertex\"].get_dual()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fd4847a0-65e5-4973-9269-47e49edb7911",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    uxds[\"xVertex\"]\n",
+    "    .topological_mean(destination=\"face\")\n",
+    "    .plot.rasterize(\n",
+    "        backend=\"matplotlib\",\n",
+    "        title=\"Node centered data on Primal Mesh\",\n",
+    "        cmap=ux.cmaps.sequential_green_blue,\n",
+    "    )\n",
+    "    + uxds_dual_node.plot.rasterize(\n",
+    "        backend=\"matplotlib\",\n",
+    "        title=\"Face Centered Data on Dual Mesh\",\n",
+    "        cmap=ux.cmaps.sequential_green_blue,\n",
+    "    )\n",
+    ").opts(fig_size=350).cols(1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "99ab5fd9-76ea-4b11-91ee-95bf535e3e7f",
+   "metadata": {},
+   "source": [
+    "### Edge Centered Data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4a4b8f5a-4158-4f45-b7a7-9e82fcdac353",
+   "metadata": {},
+   "source": [
+    "When constructing the dual mesh paired with an edge centered variable, the data will stay edge centered. However, a plotting example cannot be shown, as the `topological_mean` needed to visualize edge centered data is not currently implemented for edge centered data."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1dafeee0-3d1d-49dd-aa41-8222463ee3b3",
+   "metadata": {},
+   "source": [
+    "### UxDataset"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "36df7eac-d50d-4bae-883c-310529a1a5f0",
+   "metadata": {},
+   "source": [
+    "We can also construct a dual mesh from an entire dataset, which will convert the whole `UxDataset` to its dual mesh form. Below we can see the dataset before the dual mesh is constructed."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "97a884d0-5966-4bfc-b505-ceb3c37c4b47",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "uxds"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c65085a8-4111-4019-860c-dd28a7f3aefc",
+   "metadata": {},
+   "source": [
+    "Now we can construct the dual and see the new dataset that is returned."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9c14a1bd-d06a-4ccb-92a5-9054e063e740",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "uxds_dual = uxds.get_dual()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7c039b32-03cd-4b83-b41e-dc5e06d118a0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "uxds_dual"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fcac470d-4025-4fe8-afde-4a7bdf05c3ec",
+   "metadata": {},
+   "source": [
+    "As you can see, transforms the whole dataset. We can now take any variable and plot it, as shown below."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "85dedc57-f179-43b9-a55c-c0b469330988",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "uxds_dual[\"xVertex\"].plot.rasterize(\n",
+    "    backend=\"matplotlib\",\n",
+    "    title=\"xVertex from UxDataset dual mesh\",\n",
+    "    cmap=ux.cmaps.sequential_green_blue,\n",
+    ").opts(fig_size=350)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4a6450bd-e6aa-4cca-bac8-0c673ac84349",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}