add new landlab lesson notebooks

lessons/landlab/landlab/01-intro.a.ipynb

@@ -0,0 +1,312 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<a href=\"http://landlab.github.io\"><img style=\"float: left\" src=\"https://raw.githubusercontent.com/landlab/tutorials/release/landlab_header.png\"></a>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "tags": [
+     "toc"
+    ]
+   },
+   "source": [
+    "# Table of Contents\n",
+    "* [Introduction to Landlab: Grids and simple 2D models](#Introduction-to-Landlab:-Grids-and-simple-2D-models)\n",
+    "  * [What types of problems can Landlab solve?](#What-types-of-problems-can-Landlab-solve?)\n",
+    "  * [What you need to know about Landlab grids](#What-you-need-to-know-about-Landlab-grids)\n",
+    "    * [Grid elements](#Grid-elements)\n",
+    "    * [Explore the Landlab grids](#Explore-the-Landlab-grids)\n",
+    "      * [Nodes](#Nodes)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Introduction to Landlab: Grids and simple 2D models\n",
+    "\n",
+    "This tutorial will introduce you to the basics of Landlab grids. By the end, you will have a basic understanding of the following:\n",
+    "\n",
+    "- The elements that comprise a landlab grid\n",
+    "- The numbering of grid elements \n",
+    "- How to instantiate different types and sizes of landlab grids\n",
+    "- How to attach fields to grids and set boundary conditions\n",
+    "- How to perform basic calculations across the grid\n",
+    "\n",
+    "The tutorial concludes with an (optional / time-permitting) example of how we can rapidly construct a simple, two-dimensional diffusion model on a Landlab raster grid. \n",
+    "\n",
+    "Time-permitting, we may also learn how to instantiate a component that will replicate the diffusion model for us."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## What types of problems can Landlab solve?\n",
+    "\n",
+    "Landlab is great for a variety of earth science problems that have one thing in common: routing a flow across a grid. In today's clinic, we'll see how Landlab handles the gradient calculations that are central to driving many earth (or planetary!) surface processes.\n",
+    "\n",
+    "<img src=\"./media/flow_examples.png\"\n",
+    "     width = \"600\"\n",
+    "     height = auto />\n",
+    "     \n",
+    "     \n",
+    "     \n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "## What you need to know about Landlab grids\n",
+    "\n",
+    "Landlab model grids are 2D data structures that represent the model domain. A few things to know about grid management:\n",
+    "\n",
+    "- Grids are Python <i>objects</i>\n",
+    "- Grids use flat arrays\n",
+    "- Grids are comprised of <i>elements</i> such as nodes and links (see Figure)\n",
+    "- Grids are generated from the user-specified geometry of nodes\n",
+    "- Data fields can be attached to grid elements\n",
+    "- Methods are functions to perform operations on the data fields\n",
+    "- There are regular (raster, radial, and hexgonal) and irregular (Voronoi-Delauney) grid types\n",
+    "- Grids have some built-in numerical functions, such as gradient and divergence\n",
+    "\n",
+    "\n",
+    "<img src=\"./media/Grids1.png\"/>\n",
+    "\n",
+    "**Figure** Geometry and topology of grid elements on various Landlab grids ([Hobley et al. 2017](https://esurf.copernicus.org/articles/5/21/2017/))\n",
+    "\n",
+    "-- [Interactive sketchbook](https://landlab.github.io/grid-sketchbook/)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Grid elements\n",
+    "\n",
+    "As we see in the above figure, Landlab grids are composed of six different grid elements:\n",
+    "*node*, *links*, *patches*, *corners*, *faces*, and *cells*. The most popular of these\n",
+    "are *nodes*, *links*, and *cells*.\n",
+    "\n",
+    "In brief,\n",
+    "* *nodes* are points that have *x* and *y* coordinates.\n",
+    "* *links* are edges that connect two *nodes*.\n",
+    "* *cells* are polygons that surround single *nodes*."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Explore the Landlab grids\n",
+    "\n",
+    "First let's look at the different types of grids Landlab supports. The most common is the `RasterModelGrid`, but Landlab offers other grid types useful for different applications. We'll start by importing a couple of different grid types, and seeing how we can create new grids from those types.\n",
+    "\n",
+    "The following code imports several grids as well as a function we will use to have a quick look at what these grids look like.\n",
+    "\n",
+    "---\n",
+    "\n",
+    "**More complete descriptions of these grid types can be found in [Landlab's documentation](https://landlab.readthedocs.io/en/master/user_guide/grid.html).**\n",
+    "\n",
+    "---"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from landlab import FramedVoronoiGrid, HexModelGrid, RadialModelGrid, RasterModelGrid\n",
+    "from landlab.plot.graph import plot_graph"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "These are all Python <i>classes</i>, and the instances we create of those classes will be our grid <i>objects</i>. For starters, we'll get some basic information on `RasterModelGrid`. Then we'll create an instance of the class `RasterModelGrid` with 3 rows, 4 columns, and 10-unit grid spacing."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "?RasterModelGrid"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Nodes\n",
+    "\n",
+    "*nodes* are simply points that have *x* and *y* coordinates. Different grid types simply lay out\n",
+    "*nodes* in different ways.\n",
+    "\n",
+    "Below we create a `RasterModelGrid` that has four rows and 5 columns of nodes."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "grid = RasterModelGrid((4, 5), xy_spacing=(10, 5))\n",
+    "plot_graph(grid, at=\"node\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The grid has also created a data structure that stores the *x* and *y* coordinates for each\n",
+    "*node*: `xy_of_node` (you can also use `x_of_node` and `y_of_node`, which simply point to the\n",
+    "respective columns of `xy_of_node`).\n",
+    "\n",
+    "You access these data structures as attributes of the grid (regardless of the grid type)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "grid.xy_of_node"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "grid.x_of_node, grid.y_of_node"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "1. Look to see how the nodes are numbered and how those numbers correspond to rows of the\n",
+    "   `xy_of_node` matrix. **All grid elements are numbered in this way.**\n",
+    "2. Notice that these arrays are not \"shaped\" as they appear on the grid. For example, `x_of_node`\n",
+    "   is a flat array of length *n_nodes*, not a matrix with shape `(n_rows, n_cols)`.\n",
+    "   **All of a grid's element data structures are flattened like this.**\n",
+    "3. What happens if you try to change the position of a node?"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now see if you can do something similar with a `HexModelGrid`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "solution"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# Create a hex grid that has 5 rows and 4 colums of nodes.\n",
+    "grid = HexModelGrid((5, 4))\n",
+    "plot_graph(grid, at=\"node\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Try to do something similar with a `RadialModelGrid`. For this you'll likely have to look at the help to see\n",
+    "the correct signature to use."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "solution"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# create a radial grid instance\n",
+    "grid = RadialModelGrid(5, 4)\n",
+    "plot_graph(grid, at=\"node\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Finally, we'll look at a `FramedVoronoiGrid`. This can be best described as a `RasterModelGrid` whose\n",
+    "interior *nodes* have been offset be a random amount."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "solution"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# Create a framed voronoi grid with 4 rows and 5 columns of nodes.\n",
+    "grid = FramedVoronoiGrid((4, 5))\n",
+    "plot_graph(grid, at=\"node\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this tutorial we looked at the various grid types *Landlab* offers and how each of those grids\n",
+    "create a mesh of *nodes*. In the next tutorial we'll have a look at how we can attach data to a *Landlab* grid.\n",
+    "\n",
+    "👉 [Data fields](02-data.ipynb)"
+   ]
+  }
+ ],
+ "metadata": {
+  "anaconda-cloud": {},
+  "celltoolbar": "Tags",
+  "kernelspec": {
+   "display_name": "Ivy",
+   "language": "python",
+   "name": "ivy"
+  },
+  "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.11.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}