diff --git a/docs/gallery.yml b/docs/gallery.yml index 735760d3a..db257db37 100644 --- a/docs/gallery.yml +++ b/docs/gallery.yml @@ -1,7 +1,3 @@ -- title: Face Area Calculations - path: examples/003-area-calc.ipynb - thumbnail: _static/thumbnails/default.svg - - title: Working with MPAS Grids path: examples/004-working-with-mpas-grids.ipynb thumbnail: _static/thumbnails/004-thumbnail.png diff --git a/docs/examples/003-area-calc.ipynb b/docs/user-guide/area_calc.ipynb similarity index 75% rename from docs/examples/003-area-calc.ipynb rename to docs/user-guide/area_calc.ipynb index cee9ecf8c..d3925cb9c 100644 --- a/docs/examples/003-area-calc.ipynb +++ b/docs/user-guide/area_calc.ipynb @@ -1,27 +1,37 @@ { "cells": [ + { + "cell_type": "markdown", + "source": [ + "# Face Area Calculations" + ], + "metadata": { + "collapsed": false + } + }, + { + "cell_type": "code", + "execution_count": null, + "outputs": [], + "source": [ + "import uxarray as ux\n", + "import numpy as np" + ], + "metadata": { + "collapsed": false + } + }, { "cell_type": "markdown", "metadata": {}, "source": [ - "# Face Area Calculations\n", - "\n", - "Authors: [Rajeev Jain](https://github.com/rajeeja)\n", - "\n", - "\n", - "## Overview\n", - "\n", - "This notebook will showcase the different area calculation options provided by `uxarray`\n", + "Computing and working with face areas is important for the analysis of unstructured grids, with many algorithms and workflows requiring them. This section will showcase the different face area calculation options provided with UXarray:\n", "\n", - "For more details on how to load in data, check out our [previous usage example](https://uxarray.readthedocs.io/en/latest/examples/001-read-grid-data.html)\n", - "\n", - "**This notebook has the following sections:**\n", "1. Calculate Total Face Area\n", "2. Options for `Grid.calculate_total_face_area` Function\n", "3. Getting Area of Individual Faces\n", "4. Calculate Area of a Single Triangle in Cartesian Coordinates\n", - "5. Calculate Area from Multiple Faces in Spherical Coordinates\n", - "6. Area Calculation without Grid Object\n" + "5. Calculate Area from Multiple Faces in Spherical Coordinates" ] }, { @@ -39,29 +49,10 @@ }, "outputs": [], "source": [ - "import uxarray as ux\n", - "import numpy as np\n", - "import xarray as xr" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "# Base data path\n", "base_path = \"../../test/meshfiles/\"\n", + "grid_path = base_path + \"/ugrid/outCSne30/outCSne30.ug\"\n", "\n", - "# Path to Grid files\n", - "ugrid_path = base_path + \"/ugrid/outCSne30/outCSne30.ug\"\n", - "\n", - "# Load grid files and create UXarray Grid objects\n", - "ugrid_ds = xr.open_dataset(ugrid_path)\n", - "\n", - "ugrid = ux.open_grid(ugrid_ds)\n", + "ugrid = ux.open_grid(grid_path)\n", "ugrid" ] }, @@ -70,7 +61,7 @@ "metadata": {}, "source": [ "## 1. Calculate Total Face Area\n", - "We can calculate the total face area by calling the function `Grid.calculate_total_face_area()`. Since our dataset lies on the unit sphere, our expected area is 4*pi, which is approximately 12.56" + "We can calculate the total face area by calling the function `Grid.calculate_total_face_area()`. Since our dataset lies on the unit sphere, our expected area is 4π, which is approximately 12.56" ] }, { @@ -121,7 +112,7 @@ "\n", "Using a lower order is faster, but at the sacrifice of accuracy.\n", "\n", - "Generally, gaussian quadrature rule is more accurate than the triangular quadrature rule. Additionally, a higher order comes at the cost of computation time, but produces a more accurate result. See `uxarray/get_quadratureDG.py` file for details on quadrature points and weights." + "Generally, gaussian quadrature rule is more accurate than the triangular quadrature rule. Additionally, a higher order comes at the cost of computation time, but produces a more accurate result. See `uxarray/grid/area.py` file and function `get_gauss_quadratureDG` for details on quadrature points and weights." ] }, { @@ -252,11 +243,6 @@ }, "outputs": [], "source": [ - "# # Set correct units for the x and y coordinates\n", - "# vgrid.Mesh2_node_x.attrs[\"units\"] = \"km\"\n", - "# vgrid.Mesh2_node_y.attrs[\"units\"] = \"km\"\n", - "# vgrid.Mesh2_node_z.attrs[\"units\"] = \"km\" # This is just a placeholder, UXarray does not support 3D meshes\n", - "\n", "# Calculate the area of the triangle\n", "area_gaussian = vgrid.calculate_total_face_area(quadrature_rule=\"gaussian\", order=5)\n", "area_gaussian" @@ -351,61 +337,6 @@ "area, jacobian = verts_grid.compute_face_areas()\n", "area" ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 6. Area Calculation without Grid Object\n", - "\n", - "If you want to compute the face area without using the `Grid` object, many of the functions for computing the face are can be accessed through `uxarray.helpers`\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "from uxarray.grid.area import calculate_face_area" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "`Grid.calculate_face_area` takes in three coordinate variables (x, y, z) in the form of numpy arrays and the coordinate type (either spherical or artesian) and computes the face area from the set of points" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "cart_x = np.array(\n", - " [0.577340924821405, 0.577340924821405, 0.577340924821405, 0.577340924821405]\n", - ")\n", - "cart_y = np.array(\n", - " [0.577343045516932, 0.577343045516932, -0.577343045516932, -0.577343045516932]\n", - ")\n", - "cart_z = np.array(\n", - " [0.577366836872017, -0.577366836872017, 0.577366836872017, -0.577366836872017]\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "area, jacobian = calculate_face_area(cart_x, cart_y, cart_z, coords_type=\"cartesian\")\n", - "# both area and jacobian are reported for each face\n", - "area, jacobian" - ] } ], "metadata": { diff --git a/docs/userguide.rst b/docs/userguide.rst index 19c2a9a03..3a848b16f 100644 --- a/docs/userguide.rst +++ b/docs/userguide.rst @@ -15,3 +15,4 @@ common tasks that you can accomplish with UXarray. user-guide/representation.rst user-guide/grid-formats.rst user-guide/data-structures.ipynb + user-guide/area_calc.ipynb