Add section in from_points doc on creating regional grid with boundary points (#1250)

* [#1219] Add section on creating regional grid with boundary points

* run pre-commit

---------

Co-authored-by: Rajeev Jain <[email protected]>
Co-authored-by: Philip Chmielowiec <[email protected]>
Co-authored-by: Philip Chmielowiec <[email protected]>

Author: 3 people

docs/user-guide/from-points.ipynb

@@ -824,6 +824,68 @@
     "    title=\"Regional Delaunay Regions\",\n",
     ")"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "560212c8",
+   "metadata": {},
+   "source": [
+    "### Creating a Regional Unstructured Grid from Points\n",
+    "UXarray allows users to create unstructured grids from scattered (lon, lat) point coordinates using Delaunay triangulation. When constructing regional unstructured grids with the method=\"regional_delaunay\" option, it is critical to explicitly specify boundary points to avoid mesh artifacts and ensure accurate face bounds."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "45780c35",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "\n",
+    "import uxarray as ux\n",
+    "\n",
+    "# Define a regular grid of longitude and latitude points over [0, 60] x [0, 60]\n",
+    "lon, lat = np.meshgrid(\n",
+    "    np.linspace(0, 60.0, 10, dtype=np.float32),\n",
+    "    np.linspace(0, 60.0, 10, dtype=np.float32),\n",
+    ")\n",
+    "lon_flat = lon.ravel()\n",
+    "lat_flat = lat.ravel()\n",
+    "\n",
+    "# Identify points along the domain boundary\n",
+    "mask = (\n",
+    "    np.isclose(lon_flat, 0.0)\n",
+    "    | np.isclose(lon_flat, 60.0)\n",
+    "    | np.isclose(lat_flat, 0.0)\n",
+    "    | np.isclose(lat_flat, 60.0)\n",
+    ")\n",
+    "boundary_points = np.flatnonzero(mask)\n",
+    "\n",
+    "# Create the unstructured grid using the regional Delaunay method\n",
+    "uxgrid = ux.Grid.from_points(\n",
+    "    (lon_flat, lat_flat), method=\"regional_delaunay\", boundary_points=boundary_points\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9ce1fb8d",
+   "metadata": {},
+   "source": [
+    "#### Why Specify `boundary_points`?\n",
+    "The internal triangulation algorithm assumes a **spherical domain**. Without user-defined constraints, it may attempt to \"wrap\" the grid edges to form a closed surface, which is inappropriate for bounded regional domains. This can cause:\n",
+    "\n",
+    "* Element bounds that exceed the expected coordinate extents.\n",
+    "* Spatial hash errors in downstream workflows.\n",
+    "* Unexpected overlaps or distortions in edge geometry.\n",
+    "\n",
+    "By supplying `boundary_points`, you ensure:\n",
+    "\n",
+    "* Proper triangulation only within the region of interest.\n",
+    "* Accurate `face_bounds_lat` and `face_bounds_lon`.\n",
+    "* Stable behavior for spatial indexing and remapping."
+   ]
   }
  ],
  "metadata": {