Add example to calculate the global gravity disturbance

.github/workflows/docs.yml

@@ -21,10 +21,10 @@ on:
 # Use bash by default in all jobs
 defaults:
   run:
-    # Using "-l {0}" is necessary for conda environments to be activated
+    # The -l {0} is necessary for conda environments to be activated
     # But this breaks on MacOS if using actions/setup-python:
     # https://github.com/actions/setup-python/issues/132
-    shell: bash
+    shell: bash -l {0}
 
 jobs:
   #############################################################################
@@ -53,23 +53,21 @@ jobs:
       - name: Fetch git tags
         run: git fetch origin 'refs/tags/*:refs/tags/*'
 
-      - name: Setup Python
-        uses: actions/setup-python@v2
+      - name: Setup Miniconda
+        uses: conda-incubator/setup-miniconda@v2
         with:
           python-version: ${{ env.PYTHON }}
+          miniforge-variant: Mambaforge
+          use-mamba: true
+          channels: conda-forge,defaults
+          # Needed for caching
+          use-only-tar-bz2: true
 
-      - name: Get the pip cache folder
-        id: pip-cache
-        run: |
-          echo "::set-output name=dir::$(pip cache dir)"
-
-      - name: Setup caching for pip packages
+      - name: Setup caching for conda packages
         uses: actions/cache@v2
         with:
-          path: ${{ steps.pip-cache.outputs.dir }}
-          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
+          path: ~/conda_pkgs_dir
+          key: conda-${{ runner.os }}-${{ env.PYTHON }}-${{ hashFiles('requirements.txt') }}
 
       - name: Install requirements
         run: |
@@ -87,14 +85,14 @@ jobs:
               echo ""
               # Install wheel before anything else so pip can use wheels for
               # other packages.
-              python -m pip install -r env/requirements-build.txt
-              python -m pip install -r $requirements_file
+              mamba install --quiet --file env/requirements-build.txt python==$PYTHON
+              mamba install --quiet --file  $requirements_file python==$PYTHON
           else
               echo "No requirements defined."
           fi
 
       - name: List installed packages
-        run: pip freeze
+        run: mamba list
 
       - name: Build source and wheel distributions
         run: |
@@ -106,8 +104,20 @@ jobs:
       - name: Install the package
         run: pip install --no-deps dist/*.whl
 
+      - name: Cache the Ensaio datasets
+        uses: actions/cache@v2
+        with:
+          path: ${{ runner.temp }}/cache/ensaio
+          # Use a constant key to reuse the datasets across all jobs
+          key: ensaio
+
       - name: Build the documentation
         run: make -C doc clean all
+        env:
+          # Fetch the data from the GitHub releases to avoid overloading Zenodo
+          ENSAIO_DATA_FROM_GITHUB: true
+          # Define directory where sample data will be stored
+          ENSAIO_DATA_DIR: ${{ runner.temp }}/cache/ensaio/
 
       # Store the docs as a build artifact so we can deploy it later
       - name: Upload HTML documentation as an artifact

doc/Makefile

@@ -38,7 +38,8 @@ html: api
 	@echo
 	@echo "Building HTML files."
 	@echo
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	# Set PYGMT_USE_EXTERNAL_DISPLAY to "false" to disable external display
+	PYGMT_USE_EXTERNAL_DISPLAY="false" $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 

doc/index.rst

@@ -44,6 +44,7 @@
 
     ellipsoids/index.rst
     tutorials/normal_gravity.rst
+    tutorials/gravity_disturbance.rst
     tutorials/geodetic_to_geocentric.rst
 
 .. toctree::

env/requirements-docs.txt

@@ -1,5 +1,12 @@
 # Requirements for building the documentation
+ipython
 matplotlib
+xarray
+netcdf4
+pandas
+pygmt==0.6.*
+gmt==6.3.*
+ensaio
 sphinx==4.5.*
 sphinx-book-theme==0.2.*
 sphinx-gallery==0.10.*

environment.yml

@@ -19,7 +19,14 @@ dependencies:
   - flake8
   - pylint
   # Requirements for building the documentation
+  - ipython
   - matplotlib
+  - xarray
+  - netcdf4
+  - pandas
+  - pygmt==0.6.*
+  - gmt==6.3.*
+  - ensaio
   - sphinx==4.5.*
   - sphinx-book-theme==0.2.*
   - sphinx-gallery==0.10.*

tutorials/gravity_disturbance.py

@@ -0,0 +1,49 @@
+# Copyright (c) 2019 The Boule Developers.
+# Distributed under the terms of the BSD 3-Clause License.
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# This code is part of the Fatiando a Terra project (https://www.fatiando.org)
+#
+r"""
+.. _gravity_disturbance:
+
+Gravity disturbances
+====================
+
+Gravity disturbances are the differences between the measured gravity and a
+normal gravity produced by an ellipsoid.
+
+As an example, lets calculate a gravity disturbances grid at a height of 10 km
+using the global gravity from EIGEN-6C4 and WGS84 ellipsoid.
+"""
+
+import boule as bl
+import ensaio
+import xarray as xr
+import pygmt
+
+# Download and cache the global gravity data using Ensaio
+fname = ensaio.fetch_earth_gravity(version=1)
+# Load the gravity data using xarray
+gravity = xr.load_dataarray(fname)
+print(gravity)
+
+# Calculate the normal gravity using the WGS84 ellipsoid from Boule
+ellipsoid = bl.WGS84
+gamma = ellipsoid.normal_gravity(gravity.latitude, gravity.height)
+
+# The disturbance is the observed minus normal gravity (calculated at the
+# observation point)
+disturbance = gravity - gamma
+
+# Make a PyGMT pseudo-color map
+fig = pygmt.Figure()
+fig.basemap(
+    region="g",
+    projection="W15c",
+    frame=True,
+)
+fig.grdimage(disturbance, cmap="polar+h", shading="+nt0.5")
+fig.colorbar(frame='af+l"disturbance [mGal]"')
+fig.coast(shorelines=True, resolution="c", area_thresh=1e4)
+fig.show()