+
+
+
+
+Great Circle Cookbook
+
+
+
This Project Pythia Cookbook covers the mathematics of working with Great Circles
+Motivation
+A great circle is the largest circle that can be drawn onto a sphere (like the Earth) that is the same diameter of the sphere. Great Circle arcs connect two positions on the curved surface of a planet like Earth and are commonly used for navigation that relies on “as-the crow flies” directions like planes, ships, and satellites
+
+
+
Image Source: Wolfram MathWorld
+Authors
+ +Contributors
+ +Structure
+This cookbook is broken into two main sections:
+-
+
Foundations and Terminology
+Working with Great Circles
+
Where avaiable, this cookbook will demonstrate how to determine the features of a great circle with both existing open-source Python packages and through spherical trigonometry and mathematics
+Foundations and Terminology
+-
+
“Great Circle Terminology”: Breakdown of terminology important for working with and understanding great circles including WGS-84
+“Coordinate Systems”: Understanding and converted to different types of coordinate systems like Cartesian, Spherical, Polar, and Geodesic (Latitude/Longitude)
+“Geodesic and Python”: General overview of powerful open-source Python packages for working with geodesic data like
pyprojandgeopy
+
Each section will make use of plotting to visually demonstrate concepts with matplotlib and cartopy
Working with Great Circles
+-
+
Generating a great circle arc and path
+Midpoint (and additional intermediate points) of a great circle arc
+Length of a great circle arc (the distance between two points)
+Bearing of a great circle arc
+Compare great circle arc to rhumb line
+Determine when a great circle path crosses parallels
+Determine if a point lies on a great circle arc and path (with and without tolerances)
+Determine the distance of a point to a great circle arc with error analysis
+Determine the maximum and minimum latitude coordinates along a great circle path
+Find the intersection of two great circle arcs (if it exists)
+Find the intersection of two great circle paths (always exists)
+Calculate the acute and obtuse angle of two great circle paths
+Calculate the directed angle of two great circle paths based on an intersection point
+Working with Spherical Triangles formed by great circle arcs
+Indiana Jones and the Great Circle
+
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:
+-
+
Clone the
+https://github.com/ProjectPythia/great-circle-cookbookrepository:++git clone https://github.com/ProjectPythia/great-circle-cookbook.git +
+Move into the
+great-circle-cookbookdirectory++cd great-circle-cookbook +
+Create and activate your conda environment from the
+environment.ymlfile++conda env create -f environment.yml +conda activate cookbook-gc +
+Move into the
+notebooksdirectory and start up Jupyterlab++cd notebooks/ +jupyter lab +
+
+
+# Great Circle 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 mathematics of working with Great Circles
+
+## Motivation
+
+A great circle is the largest circle that can be drawn onto a sphere (like the Earth) that is the same diameter of the sphere. Great Circle arcs connect two positions on the curved surface of a planet like Earth and are commonly used for navigation that relies on "as-the crow flies" directions like planes, ships, and satellites
+
+![\"Great](\"https://d9-wret.s3.us-west-2.amazonaws.com/assets/palladium/production/s3fs-public/media/images/great%20circle.gif\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Coordinate Types"
+ ]
+ },
+ {
+ "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": [
+ "## Geodesic Coordinates"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": []
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Cartesian Coordinates"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Cartesian coordinates describe points in space based on perpendicular axis lines that meet at a singlle point of orign, where any point's position is described based on the distance to the orgin along xyz axis"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Geodesic to Cartesian Coordinates\n",
+ "Assuming the earth's radius is 6378137 meters\n",
+ "```\n",
+ "x = radius * cos(latitude) * cos(longitude)\n",
+ "y = radius * cos(latitude) * sin(longitude)\n",
+ "z = radius * sin(latitude)\n",
+ "```"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Spherical Coordinates"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Spherical coordinates describe points in space based on three values: radial distance (rho, r) along the radial line between point and the origin, polar angle (theta, θ) between the radial line and the polar axis, and azimuth angle (phi, φ) which is the angle of rotation of the radial line around the polar axis. With a fixed radius, the 3-point coordinates (r, θ, φ) provide a coordiante along a sphere\n",
+ "\n",
+ "- Radial distance: distance from center to surface of sphere\n",
+ "- Polar angle: angle between radial line and polar axis\n",
+ "- Azimuth angle: angle around polar axis\n",
+ "\n",
+ "![\"Spherical](\"https://upload.wikimedia.org/wikipedia/commons/thumb/8/82/Sphericalcoordinates.svg/1024px-Sphericalcoordinates.svg.png\")
\n",
+ "![\"Project](\"images/ProjectPythia_Logo_Final-01-Blue.svg\"){kind=logo}
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Project Pythia Notebook Template\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": [
+ "