{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "580f49cb5fde2c24",
   "metadata": {},
   "source": [
    "<img src=\"https://raw.githubusercontent.com/UXARRAY/uxarray/main/docs/_static/images/logos/uxarray_logo_h_dark.svg\"\n",
    "     width=\"30%\"\n",
    "     alt=\"UXarray logo\"\n",
    "     align=\"right\"\n",
    "/>\n",
    "\n",
    "# Grid Visualization\n",
    "\n",
    "### In this section, you'll learn about:\n",
    "* Plotting the edges of an unstructured grid\n",
    "* Plotting the coordinates of an unstructured grid\n",
    "\n",
    "**Related Documentation**\n",
    "\n",
    "* [UXarray Plotting User Guide](https://uxarray.readthedocs.io/en/latest/user-guide/plotting.html)\n",
    "\n",
    "**Time to learn**: 10 minutes\n",
    "\n",
    "-----\n",
    "\n"
   ]
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Introduction\n",
    "\n",
    "Unstructured grids play a vital role in scientific computing and numerical simulations. UXarray's `Grid` data structure provides a robust foundation for working with these grids by managing essential variables like coordinates and connectivity information. Before conducting complex data analysis or running simulations, it's often crucial to visualize and verify the grid geometry.\n",
    "\n",
    "This visualization capability serves multiple purposes: It helps users understand the mesh topology, identify potential issues in grid generation, and verify boundary conditions. For example, when preparing to run a dynamical core simulation, scientists often examine the computational grid to ensure it meets their requirements for spatial resolution and element quality.\n",
    "\n",
    "To demonstrate these visualization techniques, we'll work with a straightforward example: An unstructured grid consisting of four hexagonal elements. "
   ],
   "id": "4037d881fcda3720"
  },
  {
   "cell_type": "code",
   "id": "6bdf1449fbe884c4",
   "metadata": {},
   "source": [
    "import uxarray as ux\n",
    "\n",
    "grid_path = \"../../meshfiles/hex.grid.nc\"\n",
    "\n",
    "uxgrid = ux.open_grid(grid_path)\n",
    "uxgrid"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Plotting Accessor\n",
    "\n",
    "UXarray provides streamlined access to all visualization methods through the `Grid.plot` accessor. This interface serves as the central entry point for grid visualization, with each grid object supporting a default visualization method when calling `Grid.plot()`.\n"
   ],
   "id": "e7fadbf907530c66"
  },
  {
   "metadata": {},
   "cell_type": "code",
   "source": [
    "uxgrid.plot(title=\"Default Plot Function\")"
   ],
   "id": "fd26dc3bc65484dd",
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "Accessing specific plotting functions is showcased below.",
   "id": "b5cef0a110a390e5"
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Visualizing Edges\n",
    "\n",
    "Edge visualization is a fundamental technique for understanding the unstructured grid topology. By plotting the edges between grid elements, we can examine the mesh structure, verify connectivity patterns, and assess the overall grid quality. The edge representation provides an intuitive view of how elements are arranged and connected.\n"
   ],
   "id": "c7a07184bc48fa47"
  },
  {
   "metadata": {},
   "cell_type": "code",
   "source": [
    "uxgrid.plot.edges(title=\"Edge Plot\")"
   ],
   "id": "8fa4b5a83e176bc",
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Visualizing Coordinates\n",
    "\n",
    "Unstructured grids incorporate three distinct types of geometric coordinates, each serving a specific purpose in defining the grid's spatial structure and properties.\n",
    "\n",
    "### Corner Nodes\n",
    "\n",
    "Corner nodes define the fundamental geometry of each grid element through their latitude and longitude coordinates, which are stored in the `Grid.node_lat` and `Grid.node_lon` variables. \n",
    "\n"
   ],
   "id": "bb28fe23ce8bac55"
  },
  {
   "metadata": {},
   "cell_type": "code",
   "source": [
    "uxgrid.plot.corner_nodes(title=\"Corner Nodes\") * uxgrid.plot()"
   ],
   "id": "7d9662c1e5dac8f7",
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Face Centers\n",
    "\n",
    "Face centers represent the geometric centroid of each grid element, with their latitude and longitude coordinates stored in the `Grid.face_lat` and `Grid.face_lon` variables."
   ],
   "id": "366153db5c1e1f4f"
  },
  {
   "metadata": {},
   "cell_type": "code",
   "source": [
    "uxgrid.plot.face_centers(title=\"Face Centers\") * uxgrid.plot()"
   ],
   "id": "6199ebccebd321e7",
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Edge Centers\n",
    "\n",
    "Edge centers denote the midpoint of each grid boundary segment, with their spatial coordinates stored in the `Grid.edge_lat` and `Grid.edge_lon` variables. "
   ],
   "id": "af4b3dcc8e32e88e"
  },
  {
   "metadata": {},
   "cell_type": "code",
   "source": [
    "uxgrid.plot.edge_centers(title=\"Face Centers\") * uxgrid.plot()"
   ],
   "id": "31a9075b5e5fa7a4",
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Plotting Everything Together\n",
    "\n",
    "By combining the visualization of edges, face centers, corner nodes, and edge centers, we can generate a comprehensive representation of the unstructured grid's geometry. This allows us to example the complete spatial structure of our grid. \n"
   ],
   "id": "35505cab621918ed"
  },
  {
   "metadata": {},
   "cell_type": "code",
   "source": [
    "(\n",
    "    uxgrid.plot.edges(color=\"black\")\n",
    "    * uxgrid.plot.nodes(marker=\"o\", size=150).relabel(\"Corner Nodes\")\n",
    "    * uxgrid.plot.face_centers(marker=\"s\", size=150).relabel(\"Face Centers\")\n",
    "    * uxgrid.plot.edge_centers(marker=\"^\", size=150).relabel(\"Edge Centers\")\n",
    ").opts(title=\"Grid Coordinates\", legend_position=\"top_right\")"
   ],
   "id": "d93c1ca0d2b3e2d0",
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "## ",
   "id": "1f0c9ad6f9cedc55"
  }
 ],
 "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.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}