-
-
-
-
-Fundamentals of Atmsopheric Modeling Cookbook
-
-
-
This Project Pythia Cookbook covers the fundamentals of atmospheric modeling, including topics such as:
--
-
basic conservation equations
-approaches to finite differencing
-numerical scheme assessments
-numerical corrections and filtering
-coordinate systems
-initial/boundary conditions
-limitations and tradeoffs in modeling
-
Motivation
-Numerical models are widely used, but gaining expertise in how they work has often been unnecessarily challenging. This cookbook hopes to address that! This is intended for a somewhat broad audience: those with at least some atmospheric dynamics knowledge, but nearly any level of programming experience (assuming a baseline level as covered in the Pythia Foundations).
-Authors
- -Contributors
- -Resources
-This cookbook would not be possible without the vast collection of academic texts and prior work in atmospheric modeling. The key resources used in building this notebook include:
--
-
Textbooks
- -
-Journal Articles
--
-
…
-
-Other Resources
- -
-
Structure
-(State one or more sections that will comprise the notebook. E.g., This cookbook is broken up into two main sections - “Foundations” and “Example Workflows.” Then, describe each section below.)
-Section 1 ( Replace with the title of this section, e.g. “Foundations” )
-(Add content for this section, e.g., “The foundational content includes … “)
-Section 2 ( Replace with the title of this section, e.g. “Example workflows” )
-(Add content for this section, e.g., “Example workflows include … “)
-Running the Notebooks
-You can either run the notebook using Binder or on your local machine.
-Running on Binder
-The simplest way to interact with a Jupyter Notebook is through -Binder, which enables the execution of a -Jupyter Book in the cloud. The details of how this works are not -important for now. All you need to know is how to launch a Pythia -Cookbooks chapter via Binder. Simply navigate your mouse to -the top right corner of the book chapter you are viewing and click -on the rocket ship icon, (see figure below), and be sure to select -“launch Binder”. After a moment you should be presented with a -notebook that you can interact with. I.e. you’ll be able to execute -and even change the example programs. You’ll see that the code cells -have no output at first, until you execute them by pressing -Shift+Enter. Complete details on how to interact with -a live Jupyter notebook are described in Getting Started with -Jupyter.
-Running on Your Own Machine
-If you are interested in running this material locally on your computer, you will need to follow this workflow:
-(Replace “cookbook-example” with the title of your cookbooks)
--
-
Clone the
-https://github.com/ProjectPythia/cookbook-examplerepository:--git clone https://github.com/ProjectPythia/cookbook-example.git -
-Move into the
-cookbook-exampledirectory--cd cookbook-example -
-Create and activate your conda environment from the
-environment.ymlfile--conda env create -f environment.yml -conda activate cookbook-example -
-Move into the
-notebooksdirectory and start up Jupyterlab--cd notebooks/ -jupyter lab -
-
-
-# Fundamentals of Atmsopheric Modeling Cookbook
-
-[](https://github.com/ProjectPythia/cookbook-template/actions/workflows/nightly-build.yaml)
-[](https://binder.projectpythia.org/v2/gh/ProjectPythia/cookbook-template/main?labpath=notebooks)
-[](https://zenodo.org/badge/latestdoi/475509405)
-
-This Project Pythia Cookbook covers the fundamentals of atmospheric modeling, including topics such as:
-
-- basic conservation equations
-- approaches to finite differencing
-- numerical scheme assessments
-- numerical corrections and filtering
-- coordinate systems
-- initial/boundary conditions
-- limitations and tradeoffs in modeling
-
-## Motivation
-
-Numerical models are widely used, but gaining expertise in how they work has often been unnecessarily challenging. This cookbook hopes to address that! This is intended for a somewhat broad audience: those with at least some atmospheric dynamics knowledge, but nearly any level of programming experience (assuming a baseline level as covered in the [Pythia Foundations](https://foundations.projectpythia.org/landing-page.html)).
-
-## Authors
-
- - [JT Thielen](https://github.com/jthielen)
- - [Sam Gardner](https://github.com/wx4stg)
- - [Roger Riggin](https://github.com/riotrogerriot)
-
-### Contributors
-
-![\"Project](\"images/ProjectPythia_Logo_Final-01-Blue.svg\"){kind=logo}
"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "# Boundary Conditions\n",
- "\n",
- "Next, title your notebook appropriately with a top-level Markdown header, `#`. Do not use this level header anywhere else in the notebook. Our book build process will use this title in the navbar, table of contents, etc. Keep it short, keep it descriptive. Follow this with a `---` cell to visually distinguish the transition to the prerequisites section."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Overview\n",
- "If you have an introductory paragraph, lead with it here! Keep it short and tied to your material, then be sure to continue into the required list of topics below,\n",
- "\n",
- "1. This is a numbered list of the specific topics\n",
- "1. These should map approximately to your main sections of content\n",
- "1. Or each second-level, `##`, header in your notebook\n",
- "1. Keep the size and scope of your notebook in check\n",
- "1. And be sure to let the reader know up front the important concepts they'll be leaving with"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Prerequisites\n",
- "This section was inspired by [this template](https://github.com/alan-turing-institute/the-turing-way/blob/master/book/templates/chapter-template/chapter-landing-page.md) of the wonderful [The Turing Way](https://the-turing-way.netlify.app) Jupyter Book.\n",
- "\n",
- "Following your overview, tell your reader what concepts, packages, or other background information they'll **need** before learning your material. Tie this explicitly with links to other pages here in Foundations or to relevant external resources. Remove this body text, then populate the Markdown table, denoted in this cell with `|` vertical brackets, below, and fill out the information following. In this table, lay out prerequisite concepts by explicitly linking to other Foundations material or external resources, or describe generally helpful concepts.\n",
- "\n",
- "Label the importance of each concept explicitly as **helpful/necessary**.\n",
- "\n",
- "| Concepts | Importance | Notes |\n",
- "| --- | --- | --- |\n",
- "| [Intro to Cartopy](https://foundations.projectpythia.org/core/cartopy/cartopy.html) | Necessary | |\n",
- "| [Understanding of NetCDF](https://foundations.projectpythia.org/core/data-formats/netcdf-cf.html) | Helpful | Familiarity with metadata structure |\n",
- "| Project management | Helpful | |\n",
- "\n",
- "- **Time to learn**: estimate in minutes. For a rough idea, use 5 mins per subsection, 10 if longer; add these up for a total. Safer to round up and overestimate.\n",
- "- **System requirements**:\n",
- " - Populate with any system, version, or non-Python software requirements if necessary\n",
- " - Otherwise use the concepts table above and the Imports section below to describe required packages as necessary\n",
- " - If no extra requirements, remove the **System requirements** point altogether"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Imports\n",
- "Begin your body of content with another `---` divider before continuing into this section, then remove this body text and populate the following code cell with all necessary Python imports **up-front**:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "import sys"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Your first content section"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "This is where you begin your first section of material, loosely tied to your objectives stated up front. Tie together your notebook as a narrative, with interspersed Markdown text, images, and more as necessary,"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "# as well as any and all of your code cells\n",
- "print(\"Hello world!\")"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "### A content subsection\n",
- "Divide and conquer your objectives with Markdown subsections, which will populate the helpful navbar in Jupyter Lab and here on the Jupyter Book!"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "# some subsection code\n",
- "new = \"helpful information\""
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "### Another content subsection\n",
- "Keep up the good work! A note, *try to avoid using code comments as narrative*, and instead let them only exist as brief clarifications where necessary."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Your second content section\n",
- "Here we can move on to our second objective, and we can demonstrate"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "### Subsection to the second section\n",
- "\n",
- "#### a quick demonstration\n",
- "\n",
- "##### of further and further\n",
- "\n",
- "###### header levels"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "as well $m = a * t / h$ text! Similarly, you have access to other $\\LaTeX$ equation [**functionality**](https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Typesetting%20Equations.html) via MathJax (demo below from link),\n",
- "\n",
- "\\begin{align}\n",
- "\\dot{x} & = \\sigma(y-x) \\\\\n",
- "\\dot{y} & = \\rho x - y - xz \\\\\n",
- "\\dot{z} & = -\\beta z + xy\n",
- "\\end{align}"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Check out [**any number of helpful Markdown resources**](https://www.markdownguide.org/basic-syntax/) for further customizing your notebooks and the [**Jupyter docs**](https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Working%20With%20Markdown%20Cells.html) for Jupyter-specific formatting information. Don't hesitate to ask questions if you have problems getting it to look *just right*."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Last Section\n",
- "\n",
- "If you're comfortable, and as we briefly used for our embedded logo up top, you can embed raw html into Jupyter Markdown cells (edit to see):"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "![\"Colormesh](\"../images/basic_bubble.png\")
"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "# Crash Course Towards Your First Model"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Overview\n",
- "\n",
- "The following notebook serves as a crash course in constructing a simple two-dimensional mesoscale atmospheric numerical model. To begin, we select a closed set of dynamical equations, in line with Klemp and Wilhelmson (1978; hereafter KW78). Necessary assumptions are stated to simplify the equations into a managble form to maximize both computational and educational applications. Pre-defined model configurations are presented (in an attempt) to ensure numerical stability. Equations are converted into finite-differences and then broken down into Python code to explicity demonstrate the construction of a numerical model. Additional resources will be provided in the future regarding varying model configurations and utilizing increasingly more realistic and complex model equations."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Prerequisites\n",
- "\n",
- "| Concepts | Importance | Notes |\n",
- "| --- | --- | --- |\n",
- "| [NumPy Basics](https://foundations.projectpythia.org/core/numpy/numpy-basics.html) | Necessary | |\n",
- "| [Introduction to xarray](https://foundations.projectpythia.org/core/xarray/xarray-intro.html) | Helpful | Familiarity with coordinate-aware arrays |\n",
- "| Dynamical Meteorology | Helpful | |\n",
- "\n",
- "- **Time to learn**: Estimated 30 to 60 minutes."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "---"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Imports\n",
- "\n",
- "Here we'll be using a basic set of Python libraries, along with Numba for fast numerical routines. A helpful constants file is also imported, along side the code that controls the running of the model. (For those curious, these files can be viewed [here](./constants) and [here](./constants).)"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 1,
- "metadata": {},
- "outputs": [],
- "source": [
- "import numpy as np\n",
- "import numba\n",
- "import xarray as xr\n",
- "import matplotlib.pyplot as plt\n",
- "\n",
- "from constants import *\n",
- "from driver import ModelDriver"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Basic Equations\n",
- "\n",
- "### Starting Equations (from WK78)\n",
- "\n",
- "#### Diagnostics\n",
- " \n",
- "DEQ 1. Equation of State (2.1) \n",
- "$$\n",
- "p = \\rho R_{d} T\n",
- "$$ \n",
- "* $p$: Pressure\n",
- "* $\\rho$: Density\n",
- "* $R_{d}$: Specific gas constant for dry air\n",
- "* $T: Temperature\n",
- "