{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "08515bef-ae48-42ce-9a00-6850219e7a61",
   "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",
    "# UXarray Grid\n",
    "\n",
    "### In this tutorial, you'll learn:\n",
    "\n",
    "* What is a UXarray `Grid`?\n",
    "* How to load a `Grid`\n",
    "* How to access `Grid` attributes\n",
    "\n",
    "### Related Documentation\n",
    "\n",
    "* [UXarray Data Structures Documentation](https://uxarray.readthedocs.io/en/latest/user-guide/data-structures.html)\n",
    "\n",
    "### Prerequisites\n",
    "\n",
    "| Concepts | Importance | Notes |\n",
    "| --- | --- | --- |\n",
    "| Unstructured Grids | Necessary  | |\n",
    "| Python programming | Necessary  | |\n",
    "| [Introduction to Xarray](https://foundations.projectpythia.org/core/xarray/xarray-intro) | Helpful | |\n",
    "\n",
    "**Time to learn**: 10 minutes\n",
    "\n",
    "-----\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "01a6f9ae-5f4d-4465-8382-774940052bb6",
   "metadata": {},
   "source": [
    "## Overview"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a2041dc5-06c0-4cae-bbfb-4f62bfb3b7ab",
   "metadata": {},
   "source": "In the previous section, we briefly introduced the ``Grid`` class, which stores unstructured grid variables such as coordinates and connectivity. This class is the foundation of UXarray, which ensures awareness of the unstructured grid topology between operations. Exploring the grid geometry can be helpful throughout analysis and visualization workflows. \n"
  },
  {
   "cell_type": "markdown",
   "id": "aa1771c8-d5b9-4eb2-8cc5-961c214a7625",
   "metadata": {},
   "source": [
    "<div class=\"admonition alert alert-info\">\n",
    "    <p class=\"admonition-title\" style=\"font-weight:bold\">Note:</p>\n",
    "    In most cases, checking the ``Grid`` object of either ``UxDataset`` or ``UxDataArray`` is anticipated be the common scenario since majority of the UXarray workflows will rely on a data set and its variable(s) of interest. Such cases will be showcased as part of many of the following notebooks; thus, this tutorial will focus on the latter where we explore a standalone ``Grid`` object.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7482e47b-4feb-44d7-b118-221ca3d1b50f",
   "metadata": {},
   "source": [
    "## Unstructured Grid Files"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "13319a80-c211-43b5-b7d1-dad74d4b6d94",
   "metadata": {},
   "source": "In the following sections, we will look into loading a standalone grid-specific file. The coordinates and connectivity variables of an unstructured grid are often stored as a separate unstructured grid file. "
  },
  {
   "cell_type": "code",
   "id": "90c3f4f3-bf5c-41cc-8122-e410b4cb8559",
   "metadata": {},
   "source": [
    "grid_path = \"../../meshfiles/outCSne30.grid.ug\""
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "id": "e1d46358-70ae-4500-9786-d9e986637029",
   "metadata": {},
   "source": [
    "## Loading a Grid"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4e5f564a-3fb2-4fcc-b010-94a2631011a8",
   "metadata": {},
   "source": "The suggested way to construct a **standalone** `Grid` is by using the `uxarray.open_grid()` method. When constructing a standalone grid, only topology variables such as coordinates and connectivity are used to construct the grid. This means that any data variables that reside on the unstructured grid, such as temperature, would not be stored in a `Grid`. Pairing the grid definiton with data variables will be covered in the next notebook. \n"
  },
  {
   "cell_type": "code",
   "id": "6bdf1449fbe884c4",
   "metadata": {},
   "source": [
    "import uxarray as ux\n",
    "\n",
    "uxgrid = ux.open_grid(grid_path)\n",
    "uxgrid"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "Printing a `Grid` displays the contents of our newly created grid object. If you are coming from an Xarray background, this output will look very similar to what one might see when constructing an `xarray.Dataset`. ",
   "id": "df239b4dac17e91f"
  },
  {
   "cell_type": "markdown",
   "id": "a5a24484-e5c3-4d38-829f-359d9b3a23cb",
   "metadata": {},
   "source": [
    "## Coordinates"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fefc4cad-d68e-4385-8b16-ecf32cc00185",
   "metadata": {},
   "source": "Different types of coordinates for the geometric elements of a ``Grid`` are either constructed upfront during the  grid instantiation or generated at the time of use."
  },
  {
   "cell_type": "markdown",
   "id": "89eea29c-0f12-4c19-9dac-b5801abd57b8",
   "metadata": {},
   "source": [
    "### Spherical Coordinates"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb0b46d3-9556-4bc9-b9b2-9f247d6e85e2",
   "metadata": {},
   "source": [
    "The spherical **node** coordinates are always instantiated upfront with the grid initialization and can be examined through the grid attributes such as ``node_lon``, ``node_lat``, etc:"
   ]
  },
  {
   "cell_type": "code",
   "id": "caae6cef-bd2c-4a6a-b089-010e5bbfca96",
   "metadata": {},
   "source": [
    "uxgrid.node_lon"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "id": "3f564529-c66a-4bdd-844d-a48a21b46801",
   "metadata": {},
   "source": [
    "However, the spherical **face** and **edge** coordinates might not be readily available in the grid definition (see the  original ``Grid`` object above for reference) and would need to be generated by UXarray when prompted; for instance: "
   ]
  },
  {
   "cell_type": "code",
   "id": "957b37d6-aba1-413b-83a6-13b4ed885675",
   "metadata": {},
   "source": [
    "uxgrid.face_lon"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "id": "2e285ba6-db3a-45bd-98b8-a0fe034041fc",
   "metadata": {},
   "source": [
    "### Cartesian coordinates"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "02589a10-3696-46c2-bf66-611f3204cbb1",
   "metadata": {},
   "source": [
    "The original ``uxgrid`` object above shows no Cartesian coordinates; however, UXarray is able to generate those as soon as the user tries to access one of them; for instance:"
   ]
  },
  {
   "cell_type": "code",
   "id": "d0c9074b-56f8-41bd-856a-41747dec1b9b",
   "metadata": {},
   "source": [
    "uxgrid.node_x"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "id": "a32161a1-b48c-472b-9450-bbdaa33f3c90",
   "metadata": {},
   "source": [
    "## Connectivity"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f8e5bca1-ea3d-46ea-bb4b-354f48576690",
   "metadata": {},
   "source": [
    "In unstructured grid geometry, connectivity information between each type of geometric elements can be defined, e.g. face-node, node-edge, edge-face, etc. UXarray requires only the **face-node** connectivity, either coming from the grid definition or being constructed by UXarray in special cases, in addition to the node coordinates to represent the topology.  \n",
    "\n",
    "UXarray can also generate all the other connectivity information when prompted.\n",
    "\n",
    "Let us look at the face-node connectivity, for example:"
   ]
  },
  {
   "cell_type": "code",
   "id": "50456578-bd38-440a-810e-825ef80df0dd",
   "metadata": {},
   "source": [
    "uxgrid.face_node_connectivity"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "id": "be51d046-0ea7-46e4-b27a-288d072e8f2e",
   "metadata": {},
   "source": [
    "## Descriptors"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f7420393-9c75-4e1a-b2ae-f4221bccaa79",
   "metadata": {},
   "source": [
    "UXarray provides descriptors for further information about the geometry. For instance, an array that shows the number of nodes for each face can be helpful to determine if the grid is uniformly constructed of a single shape or multiple n-gons, and simplify some of the grid-specific calculations as well."
   ]
  },
  {
   "cell_type": "code",
   "id": "9acde2005fcdb175",
   "metadata": {},
   "source": [
    "uxgrid.n_nodes_per_face"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "id": "036d6bab-d89c-481c-94cf-8e0f867ebeac",
   "metadata": {},
   "source": [
    "## What is next?\n",
    "The next section will cover the other core data structures of UXarray, ``UxDataset`` and ``UxDataArray`` classes and how to open unstructured grid datasets for data analysis and visualization purposes."
   ]
  }
 ],
 "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}