├── .binder └── environment.yml ├── .dockerignore ├── .gitattributes ├── .github └── workflows │ ├── python-publish.yml │ └── python-request.yml ├── .gitignore ├── CITATION.cff ├── CONTRIBUTORS.rst ├── Dockerfile ├── LICENSE ├── MANIFEST.in ├── README.rst ├── doc ├── Makefile ├── environment.yml ├── make.bat └── source │ ├── _assets │ ├── geoid_height.svg │ └── gravity-refs.bib │ ├── _static │ └── style.css │ ├── _templates │ └── layout.html │ ├── api_reference │ ├── SLR │ │ ├── C20.rst │ │ ├── C30.rst │ │ ├── C40.rst │ │ ├── C50.rst │ │ └── CS2.rst │ ├── aod1b_geocenter.rst │ ├── aod1b_oblateness.rst │ ├── associated_legendre.rst │ ├── calc_degree_one.rst │ ├── calc_harmonic_resolution.rst │ ├── calc_mascon.rst │ ├── calc_sensitivity_kernel.rst │ ├── clenshaw_summation.rst │ ├── cnes_grace_sync.rst │ ├── combine_harmonics.rst │ ├── convert_harmonics.rst │ ├── dealiasing_global_uplift.rst │ ├── dealiasing_monthly_mean.rst │ ├── degree_amplitude.rst │ ├── destripe_harmonics.rst │ ├── esa_costg_swarm_sync.rst │ ├── fourier_legendre.rst │ ├── gauss_weights.rst │ ├── gen_averaging_kernel.rst │ ├── gen_disc_load.rst │ ├── gen_harmonics.rst │ ├── gen_point_load.rst │ ├── gen_spherical_cap.rst │ ├── gen_stokes.rst │ ├── geocenter.rst │ ├── gfz_icgem_costg_ftp.rst │ ├── gfz_isdc_dealiasing_ftp.rst │ ├── gfz_isdc_grace_ftp.rst │ ├── grace_date.rst │ ├── grace_find_months.rst │ ├── grace_input_months.rst │ ├── grace_mean_harmonics.rst │ ├── grace_months_index.rst │ ├── grace_raster_grids.rst │ ├── grace_spatial_error.rst │ ├── grace_spatial_maps.rst │ ├── harmonic_gradients.rst │ ├── harmonic_summation.rst │ ├── harmonics.rst │ ├── itsg_graz_grace_sync.rst │ ├── legendre.rst │ ├── legendre_polynomials.rst │ ├── make_grace_index.rst │ ├── mascon_reconstruct.rst │ ├── mascons.rst │ ├── monte_carlo_degree_one.rst │ ├── ocean_stokes.rst │ ├── piecewise_grace_maps.rst │ ├── plot_AIS_GrIS_maps.rst │ ├── plot_AIS_grid_3maps.rst │ ├── plot_AIS_grid_4maps.rst │ ├── plot_AIS_grid_maps.rst │ ├── plot_AIS_grid_movie.rst │ ├── plot_AIS_regional_maps.rst │ ├── plot_AIS_regional_movie.rst │ ├── plot_GrIS_grid_3maps.rst │ ├── plot_GrIS_grid_5maps.rst │ ├── plot_GrIS_grid_maps.rst │ ├── plot_GrIS_grid_movie.rst │ ├── plot_global_grid_3maps.rst │ ├── plot_global_grid_4maps.rst │ ├── plot_global_grid_5maps.rst │ ├── plot_global_grid_9maps.rst │ ├── plot_global_grid_maps.rst │ ├── plot_global_grid_movie.rst │ ├── podaac_cumulus.rst │ ├── quick_mascon_plot.rst │ ├── quick_mascon_regress.rst │ ├── read_GIA_model.rst │ ├── read_GRACE_harmonics.rst │ ├── read_SLR_harmonics.rst │ ├── read_gfc_harmonics.rst │ ├── read_love_numbers.rst │ ├── regress_grace_maps.rst │ ├── run_grace_date.rst │ ├── run_sea_level_equation.rst │ ├── scale_grace_maps.rst │ ├── sea_level_equation.rst │ ├── spatial.rst │ ├── time.rst │ ├── time_series │ │ ├── amplitude.rst │ │ ├── fit.rst │ │ ├── lomb_scargle.rst │ │ ├── piecewise.rst │ │ ├── regress.rst │ │ ├── savitzky_golay.rst │ │ └── smooth.rst │ ├── tools.rst │ ├── units.rst │ └── utilities.rst │ ├── conf.py │ ├── getting_started │ ├── Background.rst │ ├── Bibliography.rst │ ├── Citations.rst │ ├── Contributing.rst │ ├── GRACE-Data-File-Formats.rst │ ├── Geocenter-Variations.rst │ ├── Getting-Started.rst │ ├── Install.rst │ ├── NASA-Earthdata.rst │ ├── Resources.rst │ ├── Spatial-Maps.rst │ └── Time-Series-Analysis.rst │ ├── index.rst │ └── user_guide │ └── Examples.rst ├── gravity_toolkit ├── SLR │ ├── C20.py │ ├── C30.py │ ├── C40.py │ ├── C50.py │ ├── CS2.py │ └── __init__.py ├── __init__.py ├── associated_legendre.py ├── clenshaw_summation.py ├── data │ ├── Load_Love2_CE.dat │ ├── PREM-LLNs-truncated.dat │ ├── PREMhard-LLNs-truncated.dat │ ├── PREMsoft-LLNs-truncated.dat │ ├── land_fcn_300km.nc │ ├── landsea_1d.nc │ ├── landsea_hd.nc │ ├── landsea_qd.nc │ ├── leap-seconds.list │ └── love_numbers ├── degree_amplitude.py ├── destripe_harmonics.py ├── fourier_legendre.py ├── gauss_weights.py ├── gen_averaging_kernel.py ├── gen_disc_load.py ├── gen_harmonics.py ├── gen_point_load.py ├── gen_spherical_cap.py ├── gen_stokes.py ├── geocenter.py ├── grace_date.py ├── grace_find_months.py ├── grace_input_months.py ├── grace_months_index.py ├── harmonic_gradients.py ├── harmonic_summation.py ├── harmonics.py ├── legendre.py ├── legendre_polynomials.py ├── mascons.py ├── ocean_stokes.py ├── read_GIA_model.py ├── read_GRACE_harmonics.py ├── read_SLR_harmonics.py ├── read_gfc_harmonics.py ├── read_love_numbers.py ├── sea_level_equation.py ├── spatial.py ├── time.py ├── time_series │ ├── __init__.py │ ├── amplitude.py │ ├── fit.py │ ├── lomb_scargle.py │ ├── piecewise.py │ ├── regress.py │ ├── savitzky_golay.py │ └── smooth.py ├── tools.py ├── units.py ├── utilities.py └── version.py ├── notebooks ├── GRACE-Geostrophic-Maps.ipynb ├── GRACE-Harmonic-Plots.ipynb ├── GRACE-Spatial-Error.ipynb └── GRACE-Spatial-Maps.ipynb ├── readthedocs.yml ├── requirements.txt ├── scripts ├── aod1b_geocenter.py ├── aod1b_oblateness.py ├── calc_degree_one.py ├── calc_harmonic_resolution.py ├── calc_mascon.py ├── calc_sensitivity_kernel.py ├── cnes_grace_sync.py ├── combine_harmonics.py ├── convert_harmonics.py ├── dealiasing_global_uplift.py ├── dealiasing_monthly_mean.py ├── esa_costg_swarm_sync.py ├── geocenter_compare_tellus.py ├── geocenter_monte_carlo.py ├── geocenter_ocean_models.py ├── geocenter_processing_centers.py ├── gfz_icgem_costg_ftp.py ├── gfz_isdc_dealiasing_ftp.py ├── gfz_isdc_grace_ftp.py ├── grace_mean_harmonics.py ├── grace_raster_grids.py ├── grace_spatial_error.py ├── grace_spatial_maps.py ├── itsg_graz_grace_sync.py ├── make_grace_index.py ├── mascon_reconstruct.py ├── monte_carlo_degree_one.py ├── piecewise_grace_maps.py ├── plot_AIS_GrIS_maps.py ├── plot_AIS_grid_3maps.py ├── plot_AIS_grid_4maps.py ├── plot_AIS_grid_maps.py ├── plot_AIS_grid_movie.py ├── plot_AIS_regional_maps.py ├── plot_AIS_regional_movie.py ├── plot_GrIS_grid_3maps.py ├── plot_GrIS_grid_5maps.py ├── plot_GrIS_grid_maps.py ├── plot_GrIS_grid_movie.py ├── plot_QML_grid_3maps.py ├── plot_global_grid_3maps.py ├── plot_global_grid_4maps.py ├── plot_global_grid_5maps.py ├── plot_global_grid_9maps.py ├── plot_global_grid_maps.py ├── plot_global_grid_movie.py ├── podaac_cumulus.py ├── quick_mascon_plot.py ├── quick_mascon_regress.py ├── regress_grace_maps.py ├── run_grace_date.py ├── run_sea_level_equation.py └── scale_grace_maps.py ├── setup.cfg ├── setup.py ├── test ├── __init__.py ├── conftest.py ├── out.combine.green_ice.0.5.2008.60.gz ├── out.geoid.green_ice.0.5.2008.60.gz ├── out.green_ice.grid.0.5.2008.cmh20.gz ├── requirements.txt ├── test_download_and_read.py ├── test_gia.py ├── test_harmonics.py ├── test_legendre.py ├── test_love_numbers.py ├── test_point_masses.py ├── test_time.py └── test_units.py └── version.txt /.binder/environment.yml: -------------------------------------------------------------------------------- 1 | name: gravity_toolkit 2 | channels: 3 | - conda-forge 4 | dependencies: 5 | - boto3 6 | - cartopy 7 | - future 8 | - h5py 9 | - ipywidgets 10 | - ipympl 11 | - jupyterlab 12 | - jupyterlab_widgets 13 | - lxml 14 | - matplotlib 15 | - netCDF4 16 | - notebook 17 | - numpy 18 | - python>=3.6 19 | - python-dateutil 20 | - pyyaml 21 | - scipy 22 | - tk 23 | - pip 24 | - pip: 25 | - git+https://github.com/tsutterley/geoid-toolkit.git 26 | - git+https://github.com/tsutterley/read-GRACE-geocenter.git 27 | -------------------------------------------------------------------------------- /.dockerignore: -------------------------------------------------------------------------------- 1 | # Python Build # 2 | ################ 3 | __pycache__ 4 | build/ 5 | dist/ 6 | develop-eggs/ 7 | run/ 8 | wheels/ 9 | *.egg-info/ 10 | .installed.cfg 11 | *.egg 12 | .pytest_cache 13 | pythonenv*/ 14 | setup.cfg 15 | # Jupyter # 16 | ########### 17 | notebooks/ 18 | .ipynb_checkpoints 19 | Untitled.ipynb 20 | # Documentation # 21 | ################# 22 | requirements-dev.txt 23 | environment.yml 24 | readthedocs.yml 25 | codecov.yml 26 | postBuild 27 | test/ 28 | doc/ 29 | # OS generated files # 30 | ###################### 31 | .DS_Store 32 | .DS_Store? 33 | ._* 34 | .Spotlight-V100 35 | .Trashes 36 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | gravity_toolkit/data/*.nc filter=lfs diff=lfs merge=lfs -text 2 | -------------------------------------------------------------------------------- /.github/workflows/python-publish.yml: -------------------------------------------------------------------------------- 1 | # This workflows will upload a Python Package using Twine when a release is created 2 | # For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries 3 | 4 | name: Upload Python Package 5 | 6 | on: 7 | release: 8 | types: [created] 9 | 10 | jobs: 11 | deploy: 12 | 13 | runs-on: ubuntu-latest 14 | 15 | steps: 16 | - uses: actions/checkout@v4 17 | - name: Set up Python 18 | uses: actions/setup-python@v4 19 | with: 20 | python-version: '3.x' 21 | - name: Install dependencies 22 | run: | 23 | python -m pip install --upgrade pip 24 | pip install setuptools wheel twine 25 | - name: Build and publish 26 | env: 27 | TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }} 28 | TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }} 29 | run: | 30 | python setup.py sdist bdist_wheel 31 | twine upload dist/* 32 | 33 | -------------------------------------------------------------------------------- /.github/workflows/python-request.yml: -------------------------------------------------------------------------------- 1 | # This workflow will install Python dependencies, run tests and lint with a variety of Python versions 2 | # For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions 3 | 4 | name: Python on pull request 5 | 6 | on: 7 | pull_request: 8 | 9 | jobs: 10 | build: 11 | 12 | runs-on: ${{ matrix.os }} 13 | strategy: 14 | matrix: 15 | os: [ubuntu-latest, macos-latest] 16 | python-version: [3.12] 17 | env: 18 | OS: ${{ matrix.os }} 19 | PYTHON: ${{ matrix.python-version }} 20 | defaults: 21 | run: 22 | shell: bash -l {0} 23 | 24 | steps: 25 | - uses: actions/checkout@v4 26 | - name: Set up mamba ${{ matrix.python-version }} 27 | uses: mamba-org/setup-micromamba@v1 28 | with: 29 | micromamba-version: 'latest' 30 | environment-file: .binder/environment.yml 31 | init-shell: bash 32 | environment-name: gravity_toolkit 33 | cache-environment: true 34 | post-cleanup: 'all' 35 | create-args: >- 36 | python=${{ matrix.python-version }} 37 | flake8 38 | pytest 39 | pytest-cov 40 | cython 41 | - name: Lint with flake8 42 | run: | 43 | # stop the build if there are Python syntax errors or undefined names 44 | flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics 45 | # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide 46 | flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics 47 | - name: Test with pytest 48 | run: | 49 | pip install --no-deps . 50 | pytest --verbose --capture=no --cov=./ --cov-report=xml \ 51 | --username=${{ secrets.EARTHDATA_USERNAME }} \ 52 | --password=${{ secrets.EARTHDATA_PASSWORD }} \ 53 | --webdav=${{ secrets.PODAAC_PASSWORD }} 54 | - name: Archive code coverage results 55 | uses: actions/upload-artifact@v4 56 | with: 57 | name: code-coverage-report-${{ matrix.os }} 58 | path: ./coverage.xml 59 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Compiled source # 2 | ################### 3 | *.com 4 | *.class 5 | *.dll 6 | *.exe 7 | *.o 8 | *.so 9 | *.pyc 10 | *.m~ 11 | *.m~~ 12 | # Packages # 13 | ############ 14 | *.7z 15 | *.dmg 16 | *.gz 17 | *.iso 18 | *.jar 19 | *.rar 20 | *.tar 21 | *.zip 22 | # Logs and databases # 23 | ###################### 24 | *.log 25 | *.sql 26 | *.sqlite 27 | *.gmtcommands4 28 | *.gmtdefaults4 29 | .RData 30 | .Rhistory 31 | __pycache__ 32 | build/ 33 | _build/ 34 | dist/ 35 | develop-eggs/ 36 | run/ 37 | wheels/ 38 | .eggs/ 39 | *.egg-info/ 40 | .installed.cfg 41 | *.egg 42 | .pytest_cache 43 | pythonenv*/ 44 | # OS generated files # 45 | ###################### 46 | .DS_Store 47 | .DS_Store? 48 | ._* 49 | .Spotlight-V100 50 | .Trashes 51 | ehthumbs.db 52 | Thumbs.db 53 | # LaTeX and Vim # 54 | ################# 55 | *.aux 56 | *.bbl 57 | *.blg 58 | *.dvi 59 | *.fdb_latexmk 60 | *.glg 61 | *.glo 62 | *.gls 63 | *.idx 64 | *.ilg 65 | *.ind 66 | *.ist 67 | *.lof 68 | *.lot 69 | *.nav 70 | *.nlo 71 | *.out 72 | *.pdfsync 73 | *.ps 74 | *.eps 75 | *.snm 76 | *.synctex.gz 77 | *.toc 78 | *.vrb 79 | *.maf 80 | *.mtc 81 | *.mtc0 82 | *.sw* 83 | *.hidden 84 | None*.png 85 | *.gfc 86 | # Jupyter Checkpoints # 87 | ####################### 88 | .ipynb_checkpoints 89 | Untitled.ipynb 90 | # Large data files # 91 | #################### 92 | *-complete.dat 93 | -------------------------------------------------------------------------------- /CITATION.cff: -------------------------------------------------------------------------------- 1 | # This CITATION.cff file was generated with cffinit. 2 | # Visit https://bit.ly/cffinit to generate yours today! 3 | 4 | cff-version: 1.2.0 5 | title: gravity-toolkit 6 | message: Python tools for working time-variable gravity fields 7 | type: software 8 | authors: 9 | - given-names: Tyler 10 | family-names: Sutterley 11 | affiliation: University of Washington, Applied Physics Laboratory 12 | - given-names: Isabella 13 | family-names: Velicogna 14 | affiliation: University of California, Irvine 15 | - given-names: Yara 16 | family-names: Mohajerani 17 | - given-names: Hugo 18 | family-names: Lecomte 19 | identifiers: 20 | - type: doi 21 | value: 10.5281/zenodo.5156864 22 | description: Zenodo Archive 23 | repository-code: 'https://github.com/tsutterley/gravity-toolkit' 24 | url: 'https://gravity-toolkit.readthedocs.io' 25 | repository: 'https://pypi.org/project/gravity-toolkit' 26 | doi: "10.5281/zenodo.5156864" 27 | version: "1.2.3" 28 | date-released: "2025-06-05" 29 | keywords: 30 | - geodesy 31 | - gravity 32 | - spherical harmonics 33 | - GRACE 34 | - GRACE-FO 35 | license: MIT 36 | -------------------------------------------------------------------------------- /CONTRIBUTORS.rst: -------------------------------------------------------------------------------- 1 | - Hugo Lecomte (University of Strasbourg) 2 | - `Yara Mohajerani (University of Washington) `_ 3 | - `Tyler Sutterley (University of Washington) `_ 4 | - `Isabella Velicogna (University of California, Irvine) `_ 5 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM python:3.9-slim-buster 2 | 3 | LABEL Tyler Sutterley "tsutterl@uw.edu" 4 | 5 | ENV DEBIAN_FRONTEND="noninteractive" TZ="America/Los_Angeles" 6 | 7 | RUN useradd --create-home --shell /bin/bash gravity 8 | 9 | RUN apt-get update -y && \ 10 | apt-get install -y --no-install-recommends \ 11 | ca-certificates \ 12 | git \ 13 | libgeos-dev \ 14 | libhdf5-dev \ 15 | libnetcdf-dev \ 16 | libproj-dev \ 17 | libxml2-dev \ 18 | libxslt1-dev \ 19 | openssl \ 20 | proj-data \ 21 | proj-bin && \ 22 | apt-get clean 23 | 24 | WORKDIR /home/gravity 25 | 26 | RUN pip3 install --no-cache-dir --no-binary=cartopy \ 27 | cartopy \ 28 | future \ 29 | geoid-toolkit \ 30 | h5py \ 31 | lxml \ 32 | matplotlib \ 33 | netCDF4 \ 34 | numpy \ 35 | python-dateutil \ 36 | pyyaml \ 37 | scipy 38 | 39 | COPY . . 40 | 41 | RUN --mount=source=.git,target=.git,type=bind \ 42 | pip install --no-cache-dir --no-deps . 43 | 44 | USER gravity 45 | 46 | CMD ["bash"] 47 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Tyler C Sutterley 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /MANIFEST.in: -------------------------------------------------------------------------------- 1 | graft gravity_toolkit/data 2 | prune .github* 3 | prune doc* 4 | prune notebooks* 5 | exclude *.cfg 6 | exclude *.yml 7 | include requirements.txt 8 | include version.txt 9 | -------------------------------------------------------------------------------- /doc/Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line, and also 5 | # from the environment for the first two. 6 | SPHINXOPTS ?= 7 | SPHINXBUILD ?= sphinx-build 8 | SOURCEDIR = source 9 | BUILDDIR = build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 21 | -------------------------------------------------------------------------------- /doc/environment.yml: -------------------------------------------------------------------------------- 1 | name: gravity-docs 2 | channels: 3 | - conda-forge 4 | dependencies: 5 | - docutils 6 | - fontconfig 7 | - freetype 8 | - future 9 | - graphviz 10 | - lxml 11 | - markupsafe==2.0.1 12 | - numpy 13 | - numpydoc 14 | - pip 15 | - python>=3.6 16 | - python-dateutil 17 | - pyyaml 18 | - scipy 19 | - sphinx 20 | - sphinx-argparse>=0.4 21 | - sphinxcontrib-bibtex 22 | - sphinx_rtd_theme 23 | - pip: 24 | - .. 25 | -------------------------------------------------------------------------------- /doc/make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=source 11 | set BUILDDIR=build 12 | 13 | %SPHINXBUILD% >NUL 2>NUL 14 | if errorlevel 9009 ( 15 | echo. 16 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 17 | echo.installed, then set the SPHINXBUILD environment variable to point 18 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 19 | echo.may add the Sphinx directory to PATH. 20 | echo. 21 | echo.If you don't have Sphinx installed, grab it from 22 | echo.https://www.sphinx-doc.org/ 23 | exit /b 1 24 | ) 25 | 26 | if "%1" == "" goto help 27 | 28 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 29 | goto end 30 | 31 | :help 32 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 33 | 34 | :end 35 | popd 36 | -------------------------------------------------------------------------------- /doc/source/_static/style.css: -------------------------------------------------------------------------------- 1 | /* fix for position of equation numbers 2 | * https://github.com/rtfd/sphinx_rtd_theme/issues/301 3 | */ 4 | .eqno { 5 | margin-left: 5px; 6 | float: right; 7 | } 8 | .math .headerlink { 9 | display: none; 10 | visibility: hidden; 11 | } 12 | .math:hover .headerlink { 13 | display: inline-block; 14 | visibility: visible; 15 | margin-right: -0.7em; 16 | } 17 | /* fix for property line spacing 18 | * https://github.com/rtfd/sphinx_rtd_theme/issues/1301 19 | */ 20 | .property { 21 | display: block !important; 22 | padding-right: 8px; 23 | max-width: 100%; 24 | } -------------------------------------------------------------------------------- /doc/source/_templates/layout.html: -------------------------------------------------------------------------------- 1 | {# Import the theme's layout. #} 2 | {% extends "!layout.html" %} 3 | 4 | {% block htmltitle %} 5 | {% if title == '' or title == 'Home' %} 6 | {{ docstitle|e }} 7 | {% else %} 8 | {{ title|striptags|e }}{{ titlesuffix }} 9 | {% endif %} 10 | {% endblock %} 11 | 12 | {% block menu %} 13 | {{ super() }} 14 | 15 | {% if menu_links %} 16 |

17 | External links 18 |

19 |
    20 | {% for text, link in menu_links %} 21 |
  • {{ text }}
    • 22 | {% endfor %} 23 |
24 | {% endif %} 25 | {% endblock %} 26 | -------------------------------------------------------------------------------- /doc/source/api_reference/SLR/C20.rst: -------------------------------------------------------------------------------- 1 | ======= 2 | SLR.C20 3 | ======= 4 | 5 | - Reads monthly oblateness (degree 2 zonal) spherical harmonic data files from satellite laser ranging (SLR) 6 | 7 | * RL04: ``TN-05_C20_SLR.txt`` 8 | * RL05: ``TN-07_C20_SLR.txt`` 9 | * RL06: ``TN-11_C20_SLR.txt`` 10 | * CSR: ``C20_RL05.txt`` 11 | * GSFC: ``TN-14_C30_C30_GSFC_SLR.txt`` 12 | 13 | Calling Sequence 14 | ################ 15 | 16 | .. code-block:: python 17 | 18 | import gravity_toolkit.SLR 19 | SLR_C20 = gravity_toolkit.SLR.C20(SLR_file) 20 | 21 | `Source code`__ 22 | 23 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/SLR/C20.py 24 | 25 | .. autofunction:: gravity_toolkit.SLR.C20 26 | -------------------------------------------------------------------------------- /doc/source/api_reference/SLR/C30.rst: -------------------------------------------------------------------------------- 1 | ======= 2 | SLR.C30 3 | ======= 4 | 5 | - Reads monthly degree 3 zonal spherical harmonic data files from satellite laser ranging (SLR) 6 | 7 | * CSR: ``CSR_Monthly_5x5_Gravity_Harmonics.txt`` 8 | * GFZ: ``GRAVIS-2B_GFZOP_GRACE+SLR_LOW_DEGREES_0002.dat`` 9 | * GSFC: ``TN-14_C30_C30_GSFC_SLR.txt`` 10 | * LARES: ``C30_LARES_filtered.txt`` 11 | 12 | Calling Sequence 13 | ################ 14 | 15 | .. code-block:: python 16 | 17 | import gravity_toolkit.SLR 18 | SLR_C30 = gravity_toolkit.SLR.C30(SLR_file) 19 | 20 | `Source code`__ 21 | 22 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/SLR/C30.py 23 | 24 | .. autofunction:: gravity_toolkit.SLR.C30 25 | -------------------------------------------------------------------------------- /doc/source/api_reference/SLR/C40.rst: -------------------------------------------------------------------------------- 1 | ======= 2 | SLR.C40 3 | ======= 4 | 5 | - Reads monthly degree 4 zonal spherical harmonic data files from satellite laser ranging (SLR) 6 | 7 | * CSR: ``CSR_Monthly_5x5_Gravity_Harmonics.txt`` 8 | * GSFC: ``gsfc_slr_5x5c61s61.txt`` 9 | * LARES: ``C40_LARES_filtered.txt`` 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. code-block:: python 15 | 16 | import gravity_toolkit.SLR 17 | SLR_C40 = gravity_toolkit.SLR.C40(SLR_file) 18 | 19 | `Source code`__ 20 | 21 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/SLR/C40.py 22 | 23 | .. autofunction:: gravity_toolkit.SLR.C40 24 | -------------------------------------------------------------------------------- /doc/source/api_reference/SLR/C50.rst: -------------------------------------------------------------------------------- 1 | ======= 2 | SLR.C50 3 | ======= 4 | 5 | - Reads monthly degree 5 zonal spherical harmonic data files from satellite laser ranging (SLR) 6 | 7 | * CSR: ``CSR_Monthly_5x5_Gravity_Harmonics.txt`` 8 | * GSFC: ``gsfc_slr_5x5c61s61.txt`` 9 | * LARES: ``C50_LARES_filtered.txt`` 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. code-block:: python 15 | 16 | import gravity_toolkit.SLR 17 | SLR_C50 = gravity_toolkit.SLR.C50(SLR_file) 18 | 19 | `Source code`__ 20 | 21 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/SLR/C50.py 22 | 23 | .. autofunction:: gravity_toolkit.SLR.C50 24 | -------------------------------------------------------------------------------- /doc/source/api_reference/SLR/CS2.rst: -------------------------------------------------------------------------------- 1 | ======= 2 | SLR.CS2 3 | ======= 4 | 5 | - Reads monthly degree 2,m (figure axis and azimuthal dependence) spherical harmonic data files from satellite laser ranging (SLR) 6 | 7 | * CSR 2,1: ``C21_S21_RL06.txt`` 8 | * CSR 2,2: ``C22_S22_RL06.txt`` 9 | * GFZ: ``GRAVIS-2B_GFZOP_GRACE+SLR_LOW_DEGREES_0002.dat`` 10 | * GSFC: ``gsfc_slr_5x5c61s61.txt`` 11 | 12 | Calling Sequence 13 | ################ 14 | 15 | .. code-block:: python 16 | 17 | import gravity_toolkit.SLR 18 | SLR_CS2 = gravity_toolkit.SLR.CS2(SLR_file) 19 | 20 | `Source code`__ 21 | 22 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/SLR/CS2.py 23 | 24 | .. autofunction:: gravity_toolkit.SLR.CS2 25 | -------------------------------------------------------------------------------- /doc/source/api_reference/aod1b_geocenter.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | aod1b_geocenter.py 3 | ================== 4 | 5 | - Reads GRACE/GRACE-FO level-1b dealiasing data files for a specific product 6 | 7 | * ``'atm'``: atmospheric loading from ECMWF 8 | * ``'ocn'``: oceanic loading from OMCT/MPIOM 9 | * ``'glo'``: global atmospheric and oceanic loading 10 | * ``'oba'``: ocean bottom pressure from OMCT/MPIOM 11 | - Creates monthly files of geocenter variations at 3 or 6-hour intervals 12 | 13 | `Source code`__ 14 | 15 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/aod1b_geocenter.py 16 | 17 | Calling Sequence 18 | ################ 19 | 20 | .. argparse:: 21 | :filename: aod1b_geocenter.py 22 | :func: arguments 23 | :prog: aod1b_geocenter.py 24 | :nodescription: 25 | :nodefault: 26 | -------------------------------------------------------------------------------- /doc/source/api_reference/aod1b_oblateness.rst: -------------------------------------------------------------------------------- 1 | =================== 2 | aod1b_oblateness.py 3 | =================== 4 | 5 | - Reads GRACE/GRACE-FO level-1b dealiasing data files for a specific product 6 | 7 | * ``'atm'``: atmospheric loading from ECMWF 8 | * ``'ocn'``: oceanic loading from OMCT/MPIOM 9 | * ``'glo'``: global atmospheric and oceanic loading 10 | * ``'oba'``: ocean bottom pressure from OMCT/MPIOM 11 | - Creates monthly files of oblateness variations at 3 or 6-hour intervals 12 | 13 | `Source code`__ 14 | 15 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/aod1b_oblateness.py 16 | 17 | Calling Sequence 18 | ################ 19 | 20 | .. argparse:: 21 | :filename: aod1b_oblateness.py 22 | :func: arguments 23 | :prog: aod1b_oblateness.py 24 | :nodescription: 25 | :nodefault: 26 | -------------------------------------------------------------------------------- /doc/source/api_reference/associated_legendre.rst: -------------------------------------------------------------------------------- 1 | =================== 2 | associated_legendre 3 | =================== 4 | 5 | - Computes fully-normalized associated Legendre Polynomials and their first derivative for a vector of ``x`` values 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | import gravity_toolkit.associated_legendre 13 | PLM, dPLM = gravtk.associated_legendre.polynomials(LMAX, x, method='holmes') 14 | 15 | `Source code`__ 16 | 17 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/associated_legendre.py 18 | 19 | .. autofunction:: gravity_toolkit.associated_legendre 20 | 21 | .. autofunction:: gravity_toolkit.plm_colombo 22 | 23 | .. autofunction:: gravity_toolkit.plm_holmes 24 | 25 | .. autofunction:: gravity_toolkit.plm_mohlenkamp 26 | -------------------------------------------------------------------------------- /doc/source/api_reference/calc_degree_one.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | calc_degree_one.py 3 | ================== 4 | 5 | - Calculates degree 1 variations using GRACE/GRACE-FO coefficients of degree 2 and greater, and modeled ocean bottom pressure variations :cite:p:`Swenson:2008cr,Sutterley:2019bx`. 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/calc_degree_one.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: calc_degree_one.py 16 | :func: arguments 17 | :prog: calc_degree_one.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | --love -n : @after 22 | * ``0``: Han and Wahr (1995) values from PREM :cite:p:`Han:1995go` 23 | * ``1``: Gegout (2005) values from PREM :cite:p:`Gegout:2010gc` 24 | * ``2``: Wang et al. (2012) values from PREM :cite:p:`Wang:2012gc` 25 | * ``3``: Wang et al. (2012) values from PREM with hard sediment :cite:p:`Wang:2012gc` 26 | * ``4``: Wang et al. (2012) values from PREM with soft sediment :cite:p:`Wang:2012gc` 27 | 28 | --kl -k : @after 29 | * ``None``: use derived values from :cite:p:`Trupin:1992kp,Blewitt:2003bz`. 30 | 31 | --gia -G : @after 32 | * ``'IJ05-R2'``: Ivins R2 GIA Models :cite:p:`Ivins:2013cq` 33 | * ``'W12a'``: Whitehouse GIA Models :cite:p:`Whitehouse:2012jj` 34 | * ``'SM09'``: Simpson/Milne GIA Models :cite:p:`Simpson:2009hg` 35 | * ``'ICE6G'``: ICE-6G GIA Models :cite:p:`Peltier:2015bo` 36 | * ``'Wu10'``: Wu (2010) GIA Correction :cite:p:`Wu:2010dq` 37 | * ``'AW13-ICE6G'``: Geruo A ICE-6G GIA Models :cite:p:`A:2013kh` 38 | * ``'AW13-IJ05'``: Geruo A IJ05-R2 GIA Models :cite:p:`A:2013kh` 39 | * ``'Caron'``: Caron JPL GIA Assimilation :cite:p:`Caron:2018ba` 40 | * ``'ICE6G-D'``: ICE-6G Version-D GIA Models :cite:p:`Peltier:2018dp` 41 | * ``'ascii'``: reformatted GIA in ascii format 42 | * ``'netCDF4'``: reformatted GIA in netCDF4 format 43 | * ``'HDF5'``: reformatted GIA in HDF5 format 44 | 45 | --slr-c20 : @replace 46 | Replace *C*\ :sub:`20` coefficients with SLR values 47 | 48 | * ``None``: use original values 49 | * ``'CSR'``: use values from CSR (TN-07, TN-09, TN-11) 50 | * ``'GFZ'``: use values from GFZ 51 | * ``'GSFC'``: use values from GSFC (TN-14) 52 | 53 | --slr-21 X : @replace 54 | Replace *C*\ :sub:`21` and *S*\ :sub:`21` coefficients with SLR values 55 | 56 | * ``None``: use original values 57 | * ``'CSR'``: use values from CSR 58 | * ``'GFZ'``: use values from GFZ GravIS 59 | * ``'GSFC'``: use values from GSFC 60 | 61 | --slr-22 : @replace 62 | Replace *C*\ :sub:`22` and *S*\ :sub:`22` coefficients with SLR values 63 | 64 | * ``None``: use original values 65 | * ``'CSR'``: use values from CSR 66 | * ``'GSFC'``: use values from GSFC 67 | 68 | --slr-c30 : @replace 69 | Replace *C*\ :sub:`30` coefficients with SLR values 70 | 71 | * ``None``: use original values 72 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 73 | * ``'GFZ'``: use values from GFZ GravIS 74 | * ``'GSFC'``: use values from GSFC (TN-14) 75 | * ``'LARES'``: use filtered values from CSR 76 | 77 | --slr-c40 : @replace 78 | Replace *C*\ :sub:`40` coefficients with SLR values 79 | 80 | * ``None``: use original values 81 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 82 | * ``'GSFC'``: use values from GSFC 83 | * ``'LARES'``: use filtered values from CSR 84 | 85 | --slr-c50 : @replace 86 | Replace *C*\ :sub:`50` coefficients with SLR values 87 | 88 | * ``None``: use original values 89 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 90 | * ``'GSFC'``: use values from GSFC 91 | * ``'LARES'``: use filtered values from CSR 92 | 93 | --solver -s : @replace 94 | Least squares solver for degree one solutions 95 | 96 | * ``'inv'``: matrix inversion 97 | * ``'lstsq'``: least squares solution 98 | * ``'gelsy'``: complete orthogonal factorization solution 99 | * ``'gelss'``: singular value decomposition (SVD) solution 100 | * ``'gelsd'``: singular value decomposition (SVD) solution with a divide and conquer method 101 | 102 | .. |times| unicode:: U+00D7 .. MULTIPLICATION SIGN 103 | -------------------------------------------------------------------------------- /doc/source/api_reference/calc_harmonic_resolution.rst: -------------------------------------------------------------------------------- 1 | =========================== 2 | calc_harmonic_resolution.py 3 | =========================== 4 | 5 | - Calculates the spatial resolution that can be resolved by the spherical harmonics of a certain degree :cite:p:`Barthelmes:2013fy,HofmannWellenhof:2006hy` 6 | - Default method uses the smallest half-wavelength that can be resolved 7 | - Secondary method calculates the smallest possible bump that can be resolved 8 | 9 | `Source code`__ 10 | 11 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/calc_harmonic_resolution.py 12 | 13 | Calling Sequence 14 | ################ 15 | 16 | .. argparse:: 17 | :filename: calc_harmonic_resolution.py 18 | :func: arguments 19 | :prog: calc_harmonic_resolution.py 20 | :nodescription: 21 | :nodefault: 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/calc_mascon.rst: -------------------------------------------------------------------------------- 1 | ============== 2 | calc_mascon.py 3 | ============== 4 | 5 | - Reads in GRACE/GRACE-FO spherical harmonic coefficients 6 | - Correct spherical harmonics with the specified GIA model group 7 | - Filters and smooths data with specified processing algorithms :cite:p:`Jekeli:1981vj,Swenson:2006hu` 8 | - Calculates a time-series of regional mass anomalies through a least-squares mascon procedure following :cite:t:`Tiwari:2009bx,Jacob:2012gv` 9 | - Calculates the regional mascon errors following :cite:t:`Wahr:2006bx` 10 | 11 | `Source code`__ 12 | 13 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/calc_mascon.py 14 | 15 | Calling Sequence 16 | ################ 17 | 18 | .. argparse:: 19 | :filename: calc_mascon.py 20 | :func: arguments 21 | :prog: calc_mascon.py 22 | :nodescription: 23 | :nodefault: 24 | 25 | --love -n : @after 26 | * ``0``: Han and Wahr (1995) values from PREM :cite:p:`Han:1995go` 27 | * ``1``: Gegout (2005) values from PREM :cite:p:`Gegout:2010gc` 28 | * ``2``: Wang et al. (2012) values from PREM :cite:p:`Wang:2012gc` 29 | * ``3``: Wang et al. (2012) values from PREM with hard sediment :cite:p:`Wang:2012gc` 30 | * ``4``: Wang et al. (2012) values from PREM with soft sediment :cite:p:`Wang:2012gc` 31 | 32 | --reference : @after 33 | * ``'CF'``: Center of Surface Figure 34 | * ``'CM'``: Center of Mass of Earth System 35 | * ``'CE'``: Center of Mass of Solid Earth 36 | 37 | --gia -G : @after 38 | * ``'IJ05-R2'``: Ivins R2 GIA Models :cite:p:`Ivins:2013cq` 39 | * ``'W12a'``: Whitehouse GIA Models :cite:p:`Whitehouse:2012jj` 40 | * ``'SM09'``: Simpson/Milne GIA Models :cite:p:`Simpson:2009hg` 41 | * ``'ICE6G'``: ICE-6G GIA Models :cite:p:`Peltier:2015bo` 42 | * ``'Wu10'``: Wu (2010) GIA Correction :cite:p:`Wu:2010dq` 43 | * ``'AW13-ICE6G'``: Geruo A ICE-6G GIA Models :cite:p:`A:2013kh` 44 | * ``'AW13-IJ05'``: Geruo A IJ05-R2 GIA Models :cite:p:`A:2013kh` 45 | * ``'Caron'``: Caron JPL GIA Assimilation :cite:p:`Caron:2018ba` 46 | * ``'ICE6G-D'``: ICE-6G Version-D GIA Models :cite:p:`Peltier:2018dp` 47 | * ``'ascii'``: reformatted GIA in ascii format 48 | * ``'netCDF4'``: reformatted GIA in netCDF4 format 49 | * ``'HDF5'``: reformatted GIA in HDF5 format 50 | 51 | --geocenter : @after 52 | * ``None`` 53 | * ``'Tellus'``: GRACE/GRACE-FO TN-13 coefficients from PO.DAAC 54 | * ``'SLR'``: satellite laser ranging coefficients from CSR 55 | * ``'UCI'``: Sutterley and Velicogna coefficients, Remote Sensing (2019) 56 | * ``'Swenson'``: GRACE-derived coefficients from Sean Swenson 57 | * ``'GFZ'``: GRACE/SLR derived coefficients from GFZ GravIS 58 | 59 | --slr-c20 : @replace 60 | Replace *C*\ :sub:`20` coefficients with SLR values 61 | 62 | * ``None``: use original values 63 | * ``'CSR'``: use values from CSR (TN-07, TN-09, TN-11) 64 | * ``'GFZ'``: use values from GFZ 65 | * ``'GSFC'``: use values from GSFC (TN-14) 66 | 67 | --slr-21 X : @replace 68 | Replace *C*\ :sub:`21` and *S*\ :sub:`21` coefficients with SLR values 69 | 70 | * ``None``: use original values 71 | * ``'CSR'``: use values from CSR 72 | * ``'GFZ'``: use values from GFZ GravIS 73 | * ``'GSFC'``: use values from GSFC 74 | 75 | --slr-22 : @replace 76 | Replace *C*\ :sub:`22` and *S*\ :sub:`22` coefficients with SLR values 77 | 78 | * ``None``: use original values 79 | * ``'CSR'``: use values from CSR 80 | * ``'GSFC'``: use values from GSFC 81 | 82 | --slr-c30 : @replace 83 | Replace *C*\ :sub:`30` coefficients with SLR values 84 | 85 | * ``None``: use original values 86 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 87 | * ``'GFZ'``: use values from GFZ GravIS 88 | * ``'GSFC'``: use values from GSFC (TN-14) 89 | * ``'LARES'``: use filtered values from CSR 90 | 91 | --slr-c40 : @replace 92 | Replace *C*\ :sub:`40` coefficients with SLR values 93 | 94 | * ``None``: use original values 95 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 96 | * ``'GSFC'``: use values from GSFC 97 | * ``'LARES'``: use filtered values from CSR 98 | 99 | --slr-c50 : @replace 100 | Replace *C*\ :sub:`50` coefficients with SLR values 101 | 102 | * ``None``: use original values 103 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 104 | * ``'GSFC'``: use values from GSFC 105 | * ``'LARES'``: use filtered values from CSR 106 | 107 | --fit-method : @after 108 | * ``1``: mass coefficients 109 | * ``2``: geoid coefficients 110 | 111 | --solver -s : @replace 112 | Least squares solver for sensitivity kernels 113 | 114 | * ``'inv'``: matrix inversion 115 | * ``'lstsq'``: least squares solution 116 | * ``'gelsy'``: complete orthogonal factorization solution 117 | * ``'gelss'``: singular value decomposition (SVD) solution 118 | * ``'gelsd'``: singular value decomposition (SVD) solution with a divide and conquer method 119 | 120 | .. |times| unicode:: U+00D7 .. MULTIPLICATION SIGN 121 | -------------------------------------------------------------------------------- /doc/source/api_reference/calc_sensitivity_kernel.rst: -------------------------------------------------------------------------------- 1 | ========================== 2 | calc_sensitivity_kernel.py 3 | ========================== 4 | 5 | - Calculates spatial sensitivity kernels through a least-squares mascon procedure following :cite:t:`Tiwari:2009bx,Jacob:2012gv` 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/calc_sensitivity_kernel.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: calc_sensitivity_kernel.py 16 | :func: arguments 17 | :prog: calc_sensitivity_kernel.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | --love -n : @after 22 | * ``0``: Han and Wahr (1995) values from PREM :cite:p:`Han:1995go` 23 | * ``1``: Gegout (2005) values from PREM :cite:p:`Gegout:2010gc` 24 | * ``2``: Wang et al. (2012) values from PREM :cite:p:`Wang:2012gc` 25 | * ``3``: Wang et al. (2012) values from PREM with hard sediment :cite:p:`Wang:2012gc` 26 | * ``4``: Wang et al. (2012) values from PREM with soft sediment :cite:p:`Wang:2012gc` 27 | 28 | --reference : @after 29 | * ``'CF'``: Center of Surface Figure 30 | * ``'CM'``: Center of Mass of Earth System 31 | * ``'CE'``: Center of Mass of Solid Earth 32 | 33 | --fit-method : @after 34 | * ``1``: mass coefficients 35 | * ``2``: geoid coefficients 36 | 37 | --solver -s : @replace 38 | Least squares solver for sensitivity kernels 39 | 40 | * ``'inv'``: matrix inversion 41 | * ``'lstsq'``: least squares solution 42 | * ``'gelsy'``: complete orthogonal factorization solution 43 | * ``'gelss'``: singular value decomposition (SVD) solution 44 | * ``'gelsd'``: singular value decomposition (SVD) solution with a divide and conquer method 45 | -------------------------------------------------------------------------------- /doc/source/api_reference/clenshaw_summation.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | clenshaw_summation 3 | ================== 4 | 5 | - Returns the spatial field for a series of spherical harmonics at a sequence of ungridded points 6 | - Uses a Clenshaw summation to calculate the spherical harmonic summation 7 | 8 | Calling Sequence 9 | ################ 10 | 11 | .. code-block:: python 12 | 13 | from gravity_toolkit.clenshaw_summation import clenshaw_summation 14 | spatial = clenshaw_summation(clm,slm,lon,lat,UNITS=1,LMAX=60,LOVE=LOVE) 15 | 16 | `Source code`__ 17 | 18 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/clenshaw_summation.py 19 | 20 | .. autofunction:: gravity_toolkit.clenshaw_summation 21 | -------------------------------------------------------------------------------- /doc/source/api_reference/cnes_grace_sync.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | cnes_grace_sync.py 3 | ================== 4 | 5 | - Syncs GRACE/GRACE-FO and auxiliary data from the `CNES Server `_ 6 | - Creates an index file for each data product 7 | 8 | `Source code`__ 9 | 10 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/cnes_grace_sync.py 11 | 12 | Calling Sequence 13 | ################ 14 | 15 | .. argparse:: 16 | :filename: cnes_grace_sync.py 17 | :func: arguments 18 | :prog: cnes_grace_sync.py 19 | :nodescription: 20 | :nodefault: 21 | -------------------------------------------------------------------------------- /doc/source/api_reference/combine_harmonics.rst: -------------------------------------------------------------------------------- 1 | ==================== 2 | combine_harmonics.py 3 | ==================== 4 | 5 | - Converts a file from the spherical harmonic domain into the spatial domain :cite:p:`Wahr:1998hy` 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/combine_harmonics.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: combine_harmonics.py 16 | :func: arguments 17 | :prog: combine_harmonics.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | --love -n : @after 22 | * ``0``: Han and Wahr (1995) values from PREM :cite:p:`Han:1995go` 23 | * ``1``: Gegout (2005) values from PREM :cite:p:`Gegout:2010gc` 24 | * ``2``: Wang et al. (2012) values from PREM :cite:p:`Wang:2012gc` 25 | * ``3``: Wang et al. (2012) values from PREM with hard sediment :cite:p:`Wang:2012gc` 26 | * ``4``: Wang et al. (2012) values from PREM with soft sediment :cite:p:`Wang:2012gc` 27 | 28 | --reference : @after 29 | * ``'CF'``: Center of Surface Figure 30 | * ``'CM'``: Center of Mass of Earth System 31 | * ``'CE'``: Center of Mass of Solid Earth 32 | 33 | --units -U : @after 34 | * ``0``: no unit conversion 35 | * ``1``: cm of water thickness 36 | * ``2``: mm of geoid height 37 | * ``3``: mm of elastic crustal deformation 38 | * ``4``: |mu|\ Gal gravitational perturbation 39 | * ``5``: mbar equivalent surface pressure 40 | 41 | --interval -I : @after 42 | * ``1``: (0:360, 90:-90) 43 | * ``2``: (degree spacing/2) 44 | * ``3``: non-global grid (set with defined bounds) 45 | 46 | .. |mu| unicode:: U+03BC .. GREEK SMALL LETTER MU 47 | -------------------------------------------------------------------------------- /doc/source/api_reference/convert_harmonics.rst: -------------------------------------------------------------------------------- 1 | ==================== 2 | convert_harmonics.py 3 | ==================== 4 | 5 | - Converts a file from the spatial domain into the spherical harmonic domain :cite:p:`Wahr:1998hy` 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/convert_harmonics.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: convert_harmonics.py 16 | :func: arguments 17 | :prog: convert_harmonics.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | --love -n : @after 22 | * ``0``: Han and Wahr (1995) values from PREM :cite:p:`Han:1995go` 23 | * ``1``: Gegout (2005) values from PREM :cite:p:`Gegout:2010gc` 24 | * ``2``: Wang et al. (2012) values from PREM :cite:p:`Wang:2012gc` 25 | * ``3``: Wang et al. (2012) values from PREM with hard sediment :cite:p:`Wang:2012gc` 26 | * ``4``: Wang et al. (2012) values from PREM with soft sediment :cite:p:`Wang:2012gc` 27 | 28 | --reference : @after 29 | * ``'CF'``: Center of Surface Figure 30 | * ``'CM'``: Center of Mass of Earth System 31 | * ``'CE'``: Center of Mass of Solid Earth 32 | 33 | --units -U : @after 34 | * ``1``: cm of water thickness (cm.w.e., g/cm\ :sup:`2`) 35 | * ``2``: Gigatonnes (Gt) 36 | * ``3``: mm of water thickness (kg/m\ :sup:`2`) 37 | 38 | --interval -I : @after 39 | * ``1``: (0:360, 90:-90) 40 | * ``2``: (degree spacing/2) 41 | -------------------------------------------------------------------------------- /doc/source/api_reference/dealiasing_global_uplift.rst: -------------------------------------------------------------------------------- 1 | =========================== 2 | dealiasing_global_uplift.py 3 | =========================== 4 | 5 | - Reads GRACE/GRACE-FO level-1b dealiasing data files for global atmospheric and oceanic loading and estimates anomalies in elastic crustal uplift :cite:p:`Davis:2004il,Wahr:1998hy` 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/dealiasing_global_uplift.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: dealiasing_global_uplift.py 16 | :func: arguments 17 | :prog: dealiasing_global_uplift.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | --love -n : @after 22 | * ``0``: Han and Wahr (1995) values from PREM :cite:p:`Han:1995go` 23 | * ``1``: Gegout (2005) values from PREM :cite:p:`Gegout:2010gc` 24 | * ``2``: Wang et al. (2012) values from PREM :cite:p:`Wang:2012gc` 25 | * ``3``: Wang et al. (2012) values from PREM with hard sediment :cite:p:`Wang:2012gc` 26 | * ``4``: Wang et al. (2012) values from PREM with soft sediment :cite:p:`Wang:2012gc` 27 | 28 | --reference : @after 29 | * ``'CF'``: Center of Surface Figure 30 | * ``'CM'``: Center of Mass of Earth System 31 | * ``'CE'``: Center of Mass of Solid Earth 32 | 33 | --interval -I : @after 34 | * ``1``: (0:360, 90:-90) 35 | * ``2``: (degree spacing/2) 36 | * ``3``: non-global grid (set with defined bounds) 37 | -------------------------------------------------------------------------------- /doc/source/api_reference/dealiasing_monthly_mean.rst: -------------------------------------------------------------------------------- 1 | ========================== 2 | dealiasing_monthly_mean.py 3 | ========================== 4 | 5 | - Reads GRACE/GRACE-FO level-1b dealiasing data files for a specific product and outputs monthly the mean for a specific GRACE/GRACE-FO processing center and data release 6 | 7 | * ``'GAA'``: atmospheric loading from ECMWF 8 | * ``'GAB'``: oceanic loading from OMCT/MPIOM 9 | * ``'GAC'``: global atmospheric and oceanic loading 10 | * ``'GAD'``: ocean bottom pressure from OMCT/MPIOM 11 | - Creates monthly files of oblateness variations at 3 or 6-hour intervals 12 | 13 | `Source code`__ 14 | 15 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/dealiasing_monthly_mean.py 16 | 17 | Calling Sequence 18 | ################ 19 | 20 | .. argparse:: 21 | :filename: dealiasing_monthly_mean.py 22 | :func: arguments 23 | :prog: dealiasing_monthly_mean.py 24 | :nodescription: 25 | :nodefault: 26 | -------------------------------------------------------------------------------- /doc/source/api_reference/degree_amplitude.rst: -------------------------------------------------------------------------------- 1 | ================ 2 | degree_amplitude 3 | ================ 4 | 5 | - Calculates the amplitude of each spherical harmonic degree 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | from gravity_toolkit.degree_amplitude import degree_amplitude 13 | amp = degree_amplitude(clm,slm,LMAX=60) 14 | 15 | `Source code`__ 16 | 17 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/degree_amplitude.py 18 | 19 | .. autofunction:: gravity_toolkit.degree_amplitude 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/destripe_harmonics.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | destripe_harmonics 3 | ================== 4 | 5 | - Filters spherical harmonic coefficients for correlated "striping" errors following :cite:t:`Swenson:2006hu` 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | from gravity_toolkit.destripe_harmonics import destripe_harmonics 13 | Ylms = destripe_harmonics(clm,slm,LMAX=60) 14 | 15 | `Source code`__ 16 | 17 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/destripe_harmonics.py 18 | 19 | .. autofunction:: gravity_toolkit.destripe_harmonics 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/esa_costg_swarm_sync.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | esa_costg_swarm_sync.py 3 | ======================= 4 | 5 | - Syncs Swarm gravity field products from the `ESA Swarm Science Server `_ 6 | - Creates an index file for each data product 7 | 8 | `Source code`__ 9 | 10 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/esa_costg_swarm_sync.py 11 | 12 | Calling Sequence 13 | ################ 14 | 15 | .. argparse:: 16 | :filename: esa_costg_swarm_sync.py 17 | :func: arguments 18 | :prog: esa_costg_swarm_sync.py 19 | :nodescription: 20 | :nodefault: 21 | -------------------------------------------------------------------------------- /doc/source/api_reference/fourier_legendre.rst: -------------------------------------------------------------------------------- 1 | ================ 2 | fourier_legendre 3 | ================ 4 | 5 | - Computes Fourier coefficients of the associated Legendre functions 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | from gravity_toolkit.fourier_legendre import fourier_legendre 13 | plm = fourier_legendre(lmax, mmax) 14 | 15 | `Source code`__ 16 | 17 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/fourier_legendre.py 18 | 19 | .. autofunction:: gravity_toolkit.fourier_legendre 20 | 21 | .. autofunction:: gravity_toolkit.legendre_gradient 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/gauss_weights.rst: -------------------------------------------------------------------------------- 1 | ============= 2 | gauss_weights 3 | ============= 4 | 5 | - Computes the Gaussian weights as a function of degree 6 | - A normalized version of Christopher Jekeli's Gaussian averaging function 7 | 8 | Calling Sequence 9 | ################ 10 | 11 | .. code-block:: python 12 | 13 | from gravity_toolkit.gauss_weights import gauss_weights 14 | wl = 2.0*np.pi*gauss_weights(hw,LMAX) 15 | 16 | `Source code`__ 17 | 18 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/gauss_weights.py 19 | 20 | .. autofunction:: gravity_toolkit.gauss_weights 21 | -------------------------------------------------------------------------------- /doc/source/api_reference/gen_averaging_kernel.rst: -------------------------------------------------------------------------------- 1 | ==================== 2 | gen_averaging_kernel 3 | ==================== 4 | 5 | - Generates averaging kernel coefficients which minimize the total error 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | from gravity_toolkit.gen_averaging_kernel import gen_averaging_kernel 13 | Wlms = gen_averaging_kernel(gclm,gslm,eclm,eslm,sigma,hw,UNITS=0,LOVE=(hl,kl,ll)) 14 | 15 | `Source code`__ 16 | 17 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/gen_averaging_kernel.py 18 | 19 | .. autofunction:: gravity_toolkit.gen_averaging_kernel 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/gen_disc_load.rst: -------------------------------------------------------------------------------- 1 | ============= 2 | gen_disc_load 3 | ============= 4 | 5 | - Calculates gravitational spherical harmonic coefficients for a uniform disc load 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | from gravity_toolkit.gen_disc_load import gen_disc_load 13 | from gravity_toolkit.associated_legendre import plm_holmes 14 | PLM, dPLM = plm_holmes(LMAX, np.cos(th)) 15 | Ylms = gen_disc_load(data, lon, lat, area, LMAX=LMAX, PLM=PLM, LOVE=(hl,kl,ll)) 16 | 17 | `Source code`__ 18 | 19 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/gen_disc_load.py 20 | 21 | .. autofunction:: gravity_toolkit.gen_disc_load 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/gen_harmonics.rst: -------------------------------------------------------------------------------- 1 | ============= 2 | gen_harmonics 3 | ============= 4 | 5 | - Converts data from the spatial domain to spherical harmonic coefficients 6 | - Does not compute the solid Earth elastic response or convert units 7 | 8 | Calling Sequence 9 | ################ 10 | 11 | .. code-block:: python 12 | 13 | from gravity_toolkit.gen_harmonics import gen_harmonics 14 | from gravity_toolkit.associated_legendre import plm_holmes 15 | PLM, dPLM = plm_holmes(LMAX, np.cos(th)) 16 | Ylms = gen_harmonics(data, lon, lat, LMAX=LMAX, PLM=PLM) 17 | 18 | `Source code`__ 19 | 20 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/gen_harmonics.py 21 | 22 | .. autofunction:: gravity_toolkit.gen_harmonics 23 | 24 | .. autofunction:: gravity_toolkit.gen_harmonics.integration 25 | 26 | .. autofunction:: gravity_toolkit.gen_harmonics.fourier 27 | -------------------------------------------------------------------------------- /doc/source/api_reference/gen_point_load.rst: -------------------------------------------------------------------------------- 1 | ============== 2 | gen_point_load 3 | ============== 4 | 5 | - Calculates gravitational spherical harmonic coefficients for point masses 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | from gravity_toolkit.gen_point_load import gen_point_load 13 | Ylms = gen_point_load(data, lon, lat, UNITS=1, LMAX=LMAX, LOVE=(hl,kl,ll)) 14 | 15 | `Source code`__ 16 | 17 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/gen_point_load.py 18 | 19 | .. autofunction:: gravity_toolkit.gen_point_load 20 | 21 | .. autofunction:: gravity_toolkit.gen_point_load.spherical_harmonic_matrix 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/gen_spherical_cap.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | gen_spherical_cap 3 | ================= 4 | 5 | - Calculates gravitational spherical harmonic coefficients for a spherical cap 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | from gravity_toolkit.gen_spherical_cap import gen_spherical_cap 13 | from gravity_toolkit.associated_legendre import plm_holmes 14 | PLM, dPLM = plm_holmes(LMAX, np.cos(th)) 15 | Ylms = gen_spherical_cap(data, lon, lat, UNITS=1, LMAX=LMAX, PLM=PLM, LOVE=(hl,kl,ll)) 16 | 17 | `Source code`__ 18 | 19 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/gen_spherical_cap.py 20 | 21 | .. autofunction:: gravity_toolkit.gen_spherical_cap 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/gen_stokes.rst: -------------------------------------------------------------------------------- 1 | ========== 2 | gen_stokes 3 | ========== 4 | 5 | - Converts data from the spatial domain to spherical harmonic coefficients 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | from gravity_toolkit.gen_stokes import gen_stokes 13 | from gravity_toolkit.associated_legendre import plm_holmes 14 | PLM, dPLM = plm_holmes(LMAX, np.cos(th)) 15 | Ylms = gen_stokes(data, lon, lat, UNITS=1, LMAX=LMAX, PLM=PLM, LOVE=(hl,kl,ll)) 16 | 17 | `Source code`__ 18 | 19 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/gen_stokes.py 20 | 21 | .. autofunction:: gravity_toolkit.gen_stokes 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/geocenter.rst: -------------------------------------------------------------------------------- 1 | ========= 2 | geocenter 3 | ========= 4 | 5 | Data class for reading and processing geocenter data 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/geocenter.py 10 | 11 | General Attributes and Methods 12 | ============================== 13 | 14 | .. autoclass:: gravity_toolkit.geocenter 15 | :members: 16 | -------------------------------------------------------------------------------- /doc/source/api_reference/gfz_icgem_costg_ftp.rst: -------------------------------------------------------------------------------- 1 | ====================== 2 | gfz_icgem_costg_ftp.py 3 | ====================== 4 | 5 | - Syncs GRACE/GRACE-FO/Swarm COST-G data from the `GFZ International Centre for Global Earth Models (ICGEM) `_ 6 | - Creates an index file for each data product 7 | 8 | `Source code`__ 9 | 10 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/gfz_icgem_costg_ftp.py 11 | 12 | Calling Sequence 13 | ################ 14 | 15 | .. argparse:: 16 | :filename: gfz_icgem_costg_ftp.py 17 | :func: arguments 18 | :prog: gfz_icgem_costg_ftp.py 19 | :nodescription: 20 | :nodefault: 21 | -------------------------------------------------------------------------------- /doc/source/api_reference/gfz_isdc_dealiasing_ftp.rst: -------------------------------------------------------------------------------- 1 | ========================== 2 | gfz_isdc_dealiasing_ftp.py 3 | ========================== 4 | 5 | - Syncs GRACE Level-1b dealiasing products from the `GFZ Information System and Data Center (ISDC) `_ 6 | - Optionally outputs as monthly tar files 7 | 8 | `Source code`__ 9 | 10 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/gfz_isdc_dealiasing_ftp.py 11 | 12 | Calling Sequence 13 | ################ 14 | 15 | .. argparse:: 16 | :filename: gfz_isdc_dealiasing_ftp.py 17 | :func: arguments 18 | :prog: gfz_isdc_dealiasing_ftp.py 19 | :nodescription: 20 | :nodefault: 21 | -------------------------------------------------------------------------------- /doc/source/api_reference/gfz_isdc_grace_ftp.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | gfz_isdc_grace_ftp.py 3 | ===================== 4 | 5 | - Syncs GRACE/GRACE-FO and auxiliary data from the `GFZ Information System and Data Center (ISDC) `_ 6 | - Syncs CSR/GFZ/JPL Level-2 spherical harmonic files 7 | - Gets the latest technical note (TN) files 8 | - Gets the monthly GRACE/GRACE-FO newsletters 9 | - Creates an index file for each data product 10 | 11 | `Source code`__ 12 | 13 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/gfz_isdc_grace_ftp.py 14 | 15 | Calling Sequence 16 | ################ 17 | 18 | .. argparse:: 19 | :filename: gfz_isdc_grace_ftp.py 20 | :func: arguments 21 | :prog: gfz_isdc_grace_ftp.py 22 | :nodescription: 23 | :nodefault: 24 | -------------------------------------------------------------------------------- /doc/source/api_reference/grace_date.rst: -------------------------------------------------------------------------------- 1 | ========== 2 | grace_date 3 | ========== 4 | 5 | - Reads GRACE/GRACE-FO index file from `podaac_cumulus.py` or `gfz_isdc_grace_ftp.py` 6 | - Parses dates of each GRACE/GRACE-FO file and assigns the month number 7 | - Creates an index of dates for GRACE/GRACE-FO files 8 | 9 | Calling Sequence 10 | ################ 11 | 12 | .. code-block:: python 13 | 14 | from gravity_toolkit.grace_date import grace_date 15 | grace_files = grace_date(base_dir, PROC=PROC, DREL=DREL, DSET=DSET) 16 | 17 | `Source code`__ 18 | 19 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/grace_date.py 20 | 21 | .. autofunction:: gravity_toolkit.grace_date 22 | 23 | -------------------------------------------------------------------------------- /doc/source/api_reference/grace_find_months.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | grace_find_months 3 | ================= 4 | 5 | - Finds the months available for a GRACE/GRACE-FO/Swarm product 6 | - Finds the all months missing from the product 7 | 8 | Calling Sequence 9 | ################ 10 | 11 | .. code-block:: python 12 | 13 | from gravity_toolkit.grace_find_months import grace_find_months 14 | grace_months = grace_find_months(base_dir, PROC, DREL, DSET=DSET) 15 | 16 | `Source code`__ 17 | 18 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/grace_find_months.py 19 | 20 | .. autofunction:: gravity_toolkit.grace_find_months 21 | -------------------------------------------------------------------------------- /doc/source/api_reference/grace_input_months.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | grace_input_months 3 | ================== 4 | 5 | - Reads GRACE/GRACE-FO/Swarm files for a specified spherical harmonic degree and order and for a specified date range 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | from gravity_toolkit.grace_input_months import grace_input_months 13 | GRACE_Ylms = grace_input_months(base_dir, PROC, DREL, DSET, LMAX, 14 | start_mon, end_mon, missing, SLR_C20, DEG1, SLR_C30=SLR_C30) 15 | 16 | `Source code`__ 17 | 18 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/grace_input_months.py 19 | 20 | .. autofunction:: gravity_toolkit.grace_input_months 21 | 22 | .. autofunction:: gravity_toolkit.grace_input_months.read_ecmwf_corrections 23 | 24 | .. autofunction:: gravity_toolkit.grace_input_months.regress_model -------------------------------------------------------------------------------- /doc/source/api_reference/grace_mean_harmonics.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | grace_mean_harmonics.py 3 | ======================= 4 | 5 | - Calculates the temporal mean of the GRACE/GRACE-FO spherical harmonics for a specified date range 6 | - Used to estimate the static gravitational field over a given date rage 7 | 8 | `Source code`__ 9 | 10 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/grace_mean_harmonics.py 11 | 12 | Calling Sequence 13 | ################ 14 | 15 | .. argparse:: 16 | :filename: grace_mean_harmonics.py 17 | :func: arguments 18 | :prog: grace_mean_harmonics.py 19 | :nodescription: 20 | :nodefault: 21 | 22 | --geocenter : @after 23 | * ``None`` 24 | * ``'Tellus'``: GRACE/GRACE-FO TN-13 coefficients from PO.DAAC 25 | * ``'SLR'``: satellite laser ranging coefficients from CSR 26 | * ``'UCI'``: Sutterley and Velicogna coefficients, Remote Sensing (2019) 27 | * ``'Swenson'``: GRACE-derived coefficients from Sean Swenson 28 | * ``'GFZ'``: GRACE/SLR derived coefficients from GFZ GravIS 29 | 30 | --slr-c20 : @replace 31 | Replace *C*\ :sub:`20` coefficients with SLR values 32 | 33 | * ``None``: use original values 34 | * ``'CSR'``: use values from CSR (TN-07, TN-09, TN-11) 35 | * ``'GFZ'``: use values from GFZ 36 | * ``'GSFC'``: use values from GSFC (TN-14) 37 | 38 | --slr-21 X : @replace 39 | Replace *C*\ :sub:`21` and *S*\ :sub:`21` coefficients with SLR values 40 | 41 | * ``None``: use original values 42 | * ``'CSR'``: use values from CSR 43 | * ``'GFZ'``: use values from GFZ GravIS 44 | * ``'GSFC'``: use values from GSFC 45 | 46 | --slr-22 : @replace 47 | Replace *C*\ :sub:`22` and *S*\ :sub:`22` coefficients with SLR values 48 | 49 | * ``None``: use original values 50 | * ``'CSR'``: use values from CSR 51 | * ``'GSFC'``: use values from GSFC 52 | 53 | --slr-c30 : @replace 54 | Replace *C*\ :sub:`30` coefficients with SLR values 55 | 56 | * ``None``: use original values 57 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 58 | * ``'GFZ'``: use values from GFZ GravIS 59 | * ``'GSFC'``: use values from GSFC (TN-14) 60 | * ``'LARES'``: use filtered values from CSR 61 | 62 | --slr-c40 : @replace 63 | Replace *C*\ :sub:`40` coefficients with SLR values 64 | 65 | * ``None``: use original values 66 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 67 | * ``'GSFC'``: use values from GSFC 68 | * ``'LARES'``: use filtered values from CSR 69 | 70 | --slr-c50 : @replace 71 | Replace *C*\ :sub:`50` coefficients with SLR values 72 | 73 | * ``None``: use original values 74 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 75 | * ``'GSFC'``: use values from GSFC 76 | * ``'LARES'``: use filtered values from CSR 77 | 78 | .. |times| unicode:: U+00D7 .. MULTIPLICATION SIGN 79 | -------------------------------------------------------------------------------- /doc/source/api_reference/grace_months_index.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | grace_months_index 3 | ================== 4 | 5 | - Creates an index of dates for all GRACE/GRACE-FO processing centers 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | from gravity_toolkit.grace_months_index import grace_months_index 13 | grace_months_index(base_dir, DREL=DREL, MODE=0o775) 14 | 15 | `Source code`__ 16 | 17 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/grace_months_index.py) 18 | 19 | .. autofunction:: gravity_toolkit.grace_months_index 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/grace_raster_grids.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | grace_raster_grids.py 3 | ===================== 4 | 5 | - Reads in GRACE/GRACE-FO spherical harmonic coefficients and exports projected spatial fields 6 | - Correct spherical harmonics with the specified GIA model group 7 | - Filters and smooths data with specified processing algorithms :cite:p:`Jekeli:1981vj,Swenson:2006hu` 8 | - Converts data to specified units and performs a Clenshaw harmonic summation to convert to the spatial domain :cite:p:`Holmes:2002ff,Tscherning:1982tu` 9 | 10 | `Source code`__ 11 | 12 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/grace_raster_grids.py 13 | 14 | Calling Sequence 15 | ################ 16 | 17 | .. argparse:: 18 | :filename: grace_raster_grids.py 19 | :func: arguments 20 | :prog: grace_raster_grids.py 21 | :nodescription: 22 | :nodefault: 23 | 24 | --love -n : @after 25 | * ``0``: Han and Wahr (1995) values from PREM :cite:p:`Han:1995go` 26 | * ``1``: Gegout (2005) values from PREM :cite:p:`Gegout:2010gc` 27 | * ``2``: Wang et al. (2012) values from PREM :cite:p:`Wang:2012gc` 28 | * ``3``: Wang et al. (2012) values from PREM with hard sediment :cite:p:`Wang:2012gc` 29 | * ``4``: Wang et al. (2012) values from PREM with soft sediment :cite:p:`Wang:2012gc` 30 | 31 | --reference : @after 32 | * ``'CF'``: Center of Surface Figure 33 | * ``'CM'``: Center of Mass of Earth System 34 | * ``'CE'``: Center of Mass of Solid Earth 35 | 36 | --gia -G : @after 37 | * ``'IJ05-R2'``: Ivins R2 GIA Models :cite:p:`Ivins:2013cq` 38 | * ``'W12a'``: Whitehouse GIA Models :cite:p:`Whitehouse:2012jj` 39 | * ``'SM09'``: Simpson/Milne GIA Models :cite:p:`Simpson:2009hg` 40 | * ``'ICE6G'``: ICE-6G GIA Models :cite:p:`Peltier:2015bo` 41 | * ``'Wu10'``: Wu (2010) GIA Correction :cite:p:`Wu:2010dq` 42 | * ``'AW13-ICE6G'``: Geruo A ICE-6G GIA Models :cite:p:`A:2013kh` 43 | * ``'AW13-IJ05'``: Geruo A IJ05-R2 GIA Models :cite:p:`A:2013kh` 44 | * ``'Caron'``: Caron JPL GIA Assimilation :cite:p:`Caron:2018ba` 45 | * ``'ICE6G-D'``: ICE-6G Version-D GIA Models :cite:p:`Peltier:2018dp` 46 | * ``'ascii'``: reformatted GIA in ascii format 47 | * ``'netCDF4'``: reformatted GIA in netCDF4 format 48 | * ``'HDF5'``: reformatted GIA in HDF5 format 49 | 50 | --geocenter : @after 51 | * ``None`` 52 | * ``'Tellus'``: GRACE/GRACE-FO TN-13 coefficients from PO.DAAC 53 | * ``'SLR'``: satellite laser ranging coefficients from CSR 54 | * ``'UCI'``: Sutterley and Velicogna coefficients, Remote Sensing (2019) 55 | * ``'Swenson'``: GRACE-derived coefficients from Sean Swenson 56 | * ``'GFZ'``: GRACE/SLR derived coefficients from GFZ GravIS 57 | 58 | --slr-c20 : @replace 59 | Replace *C*\ :sub:`20` coefficients with SLR values 60 | 61 | * ``None``: use original values 62 | * ``'CSR'``: use values from CSR (TN-07, TN-09, TN-11) 63 | * ``'GFZ'``: use values from GFZ 64 | * ``'GSFC'``: use values from GSFC (TN-14) 65 | 66 | --slr-21 X : @replace 67 | Replace *C*\ :sub:`21` and *S*\ :sub:`21` coefficients with SLR values 68 | 69 | * ``None``: use original values 70 | * ``'CSR'``: use values from CSR 71 | * ``'GFZ'``: use values from GFZ GravIS 72 | * ``'GSFC'``: use values from GSFC 73 | 74 | --slr-22 : @replace 75 | Replace *C*\ :sub:`22` and *S*\ :sub:`22` coefficients with SLR values 76 | 77 | * ``None``: use original values 78 | * ``'CSR'``: use values from CSR 79 | * ``'GSFC'``: use values from GSFC 80 | 81 | --slr-c30 : @replace 82 | Replace *C*\ :sub:`30` coefficients with SLR values 83 | 84 | * ``None``: use original values 85 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 86 | * ``'GFZ'``: use values from GFZ GravIS 87 | * ``'GSFC'``: use values from GSFC (TN-14) 88 | * ``'LARES'``: use filtered values from CSR 89 | 90 | --slr-c40 : @replace 91 | Replace *C*\ :sub:`40` coefficients with SLR values 92 | 93 | * ``None``: use original values 94 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 95 | * ``'GSFC'``: use values from GSFC 96 | * ``'LARES'``: use filtered values from CSR 97 | 98 | --slr-c50 : @replace 99 | Replace *C*\ :sub:`50` coefficients with SLR values 100 | 101 | * ``None``: use original values 102 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 103 | * ``'GSFC'``: use values from GSFC 104 | * ``'LARES'``: use filtered values from CSR 105 | 106 | --units -U : @after 107 | * ``1``: cm of water thickness 108 | * ``2``: mm of geoid height 109 | * ``3``: mm of elastic crustal deformation 110 | * ``4``: |mu|\ Gal gravitational perturbation 111 | * ``5``: mbar equivalent surface pressure 112 | 113 | --projection : @after 114 | * ``4326``: latitude and longitude coordinates on WGS84 reference ellipsoid 115 | 116 | .. |mu| unicode:: U+03BC .. GREEK SMALL LETTER MU 117 | 118 | .. |times| unicode:: U+00D7 .. MULTIPLICATION SIGN 119 | -------------------------------------------------------------------------------- /doc/source/api_reference/grace_spatial_error.rst: -------------------------------------------------------------------------------- 1 | ====================== 2 | grace_spatial_error.py 3 | ====================== 4 | 5 | - Reads in GRACE/GRACE-FO spherical harmonic coefficients and exports spatial error field following :cite:t:`Wahr:2006bx` 6 | - Filters and smooths data with specified processing algorithms :cite:p:`Jekeli:1981vj,Swenson:2006hu` 7 | - Converts data to specified units and performs a spherical harmonic summation to convert error field to the spatial domain :cite:p:`Wahr:1998hy` 8 | 9 | `Source code`__ 10 | 11 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/grace_spatial_error.py 12 | 13 | Calling Sequence 14 | ################ 15 | 16 | .. argparse:: 17 | :filename: grace_spatial_error.py 18 | :func: arguments 19 | :prog: grace_spatial_error.py 20 | :nodescription: 21 | :nodefault: 22 | 23 | --love -n : @after 24 | * ``0``: Han and Wahr (1995) values from PREM :cite:p:`Han:1995go` 25 | * ``1``: Gegout (2005) values from PREM :cite:p:`Gegout:2010gc` 26 | * ``2``: Wang et al. (2012) values from PREM :cite:p:`Wang:2012gc` 27 | * ``3``: Wang et al. (2012) values from PREM with hard sediment :cite:p:`Wang:2012gc` 28 | * ``4``: Wang et al. (2012) values from PREM with soft sediment :cite:p:`Wang:2012gc` 29 | 30 | --reference : @after 31 | * ``'CF'``: Center of Surface Figure 32 | * ``'CM'``: Center of Mass of Earth System 33 | * ``'CE'``: Center of Mass of Solid Earth 34 | 35 | --geocenter : @after 36 | * ``None`` 37 | * ``'Tellus'``: GRACE/GRACE-FO TN-13 coefficients from PO.DAAC 38 | * ``'SLR'``: satellite laser ranging coefficients from CSR 39 | * ``'UCI'``: Sutterley and Velicogna coefficients, Remote Sensing (2019) 40 | * ``'Swenson'``: GRACE-derived coefficients from Sean Swenson 41 | * ``'GFZ'``: GRACE/SLR derived coefficients from GFZ GravIS 42 | 43 | --slr-c20 : @replace 44 | Replace *C*\ :sub:`20` coefficients with SLR values 45 | 46 | * ``None``: use original values 47 | * ``'CSR'``: use values from CSR (TN-07, TN-09, TN-11) 48 | * ``'GFZ'``: use values from GFZ 49 | * ``'GSFC'``: use values from GSFC (TN-14) 50 | 51 | --slr-21 X : @replace 52 | Replace *C*\ :sub:`21` and *S*\ :sub:`21` coefficients with SLR values 53 | 54 | * ``None``: use original values 55 | * ``'CSR'``: use values from CSR 56 | * ``'GFZ'``: use values from GFZ GravIS 57 | * ``'GSFC'``: use values from GSFC 58 | 59 | --slr-22 : @replace 60 | Replace *C*\ :sub:`22` and *S*\ :sub:`22` coefficients with SLR values 61 | 62 | * ``None``: use original values 63 | * ``'CSR'``: use values from CSR 64 | * ``'GSFC'``: use values from GSFC 65 | 66 | --slr-c30 : @replace 67 | Replace *C*\ :sub:`30` coefficients with SLR values 68 | 69 | * ``None``: use original values 70 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 71 | * ``'GFZ'``: use values from GFZ GravIS 72 | * ``'GSFC'``: use values from GSFC (TN-14) 73 | * ``'LARES'``: use filtered values from CSR 74 | 75 | --slr-c50 : @replace 76 | Replace *C*\ :sub:`50` coefficients with SLR values 77 | 78 | * ``None``: use original values 79 | * ``'CSR'``: use values from CSR (\ |times|\ 5 with 6,1) 80 | * ``'GSFC'``: use values from GSFC 81 | * ``'LARES'``: use filtered values from CSR 82 | 83 | --units -U : @after 84 | * ``1``: cm of water thickness 85 | * ``2``: mm of geoid height 86 | * ``3``: mm of elastic crustal deformation 87 | * ``4``: |mu|\ Gal gravitational perturbation 88 | * ``5``: mbar equivalent surface pressure 89 | 90 | --interval : @replace 91 | Output grid interval 92 | 93 | * ``1``: (0:360, 90:-90) 94 | * ``2``: (degree spacing/2) 95 | * ``3``: non-global grid (set with defined bounds) 96 | 97 | .. |mu| unicode:: U+03BC .. GREEK SMALL LETTER MU 98 | 99 | .. |times| unicode:: U+00D7 .. MULTIPLICATION SIGN 100 | -------------------------------------------------------------------------------- /doc/source/api_reference/grace_spatial_maps.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | grace_spatial_maps.py 3 | ===================== 4 | 5 | - Reads in GRACE/GRACE-FO spherical harmonic coefficients and exports monthly spatial fields 6 | - Correct spherical harmonics with the specified GIA model group 7 | - Filters and smooths data with specified processing algorithms :cite:p:`Jekeli:1981vj,Swenson:2006hu` 8 | - Converts data to specified units and performs a spherical harmonic summation to convert to the spatial domain :cite:p:`Wahr:1998hy` 9 | 10 | `Source code`__ 11 | 12 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/grace_spatial_maps.py 13 | 14 | Calling Sequence 15 | ################ 16 | 17 | .. argparse:: 18 | :filename: grace_spatial_maps.py 19 | :func: arguments 20 | :prog: grace_spatial_maps.py 21 | :nodescription: 22 | :nodefault: 23 | 24 | --love -n : @after 25 | * ``0``: Han and Wahr (1995) values from PREM :cite:p:`Han:1995go` 26 | * ``1``: Gegout (2005) values from PREM :cite:p:`Gegout:2010gc` 27 | * ``2``: Wang et al. (2012) values from PREM :cite:p:`Wang:2012gc` 28 | * ``3``: Wang et al. (2012) values from PREM with hard sediment :cite:p:`Wang:2012gc` 29 | * ``4``: Wang et al. (2012) values from PREM with soft sediment :cite:p:`Wang:2012gc` 30 | 31 | --reference : @after 32 | * ``'CF'``: Center of Surface Figure 33 | * ``'CM'``: Center of Mass of Earth System 34 | * ``'CE'``: Center of Mass of Solid Earth 35 | 36 | --gia -G : @after 37 | * ``'IJ05-R2'``: Ivins R2 GIA Models :cite:p:`Ivins:2013cq` 38 | * ``'W12a'``: Whitehouse GIA Models :cite:p:`Whitehouse:2012jj` 39 | * ``'SM09'``: Simpson/Milne GIA Models :cite:p:`Simpson:2009hg` 40 | * ``'ICE6G'``: ICE-6G GIA Models :cite:p:`Peltier:2015bo` 41 | * ``'Wu10'``: Wu (2010) GIA Correction :cite:p:`Wu:2010dq` 42 | * ``'AW13-ICE6G'``: Geruo A ICE-6G GIA Models :cite:p:`A:2013kh` 43 | * ``'AW13-IJ05'``: Geruo A IJ05-R2 GIA Models :cite:p:`A:2013kh` 44 | * ``'Caron'``: Caron JPL GIA Assimilation :cite:p:`Caron:2018ba` 45 | * ``'ICE6G-D'``: ICE-6G Version-D GIA Models :cite:p:`Peltier:2018dp` 46 | * ``'ascii'``: reformatted GIA in ascii format 47 | * ``'netCDF4'``: reformatted GIA in netCDF4 format 48 | * ``'HDF5'``: reformatted GIA in HDF5 format 49 | 50 | --geocenter : @after 51 | * ``None`` 52 | * ``'Tellus'``: GRACE/GRACE-FO TN-13 coefficients from PO.DAAC 53 | * ``'SLR'``: satellite laser ranging coefficients from CSR 54 | * ``'UCI'``: Sutterley and Velicogna coefficients, Remote Sensing (2019) 55 | * ``'Swenson'``: GRACE-derived coefficients from Sean Swenson 56 | * ``'GFZ'``: GRACE/SLR derived coefficients from GFZ GravIS 57 | 58 | --slr-c20 : @replace 59 | Replace *C*\ :sub:`20` coefficients with SLR values 60 | 61 | * ``None``: use original values 62 | * ``'CSR'``: use values from CSR (TN-07, TN-09, TN-11) 63 | * ``'GFZ'``: use values from GFZ 64 | * ``'GSFC'``: use values from GSFC (TN-14) 65 | 66 | --slr-21 X : @replace 67 | Replace *C*\ :sub:`21` and *S*\ :sub:`21` coefficients with SLR values 68 | 69 | * ``None``: use original values 70 | * ``'CSR'``: use values from CSR 71 | * ``'GFZ'``: use values from GFZ GravIS 72 | * ``'GSFC'``: use values from GSFC 73 | 74 | --slr-22 : @replace 75 | Replace *C*\ :sub:`22` and *S*\ :sub:`22` coefficients with SLR values 76 | 77 | * ``None``: use original values 78 | * ``'CSR'``: use values from CSR 79 | * ``'GSFC'``: use values from GSFC 80 | 81 | --slr-c30 : @replace 82 | Replace *C*\ :sub:`30` coefficients with SLR values 83 | 84 | * ``None``: use original values 85 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 86 | * ``'GFZ'``: use values from GFZ GravIS 87 | * ``'GSFC'``: use values from GSFC (TN-14) 88 | * ``'LARES'``: use filtered values from CSR 89 | 90 | --slr-c40 : @replace 91 | Replace *C*\ :sub:`40` coefficients with SLR values 92 | 93 | * ``None``: use original values 94 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 95 | * ``'GSFC'``: use values from GSFC 96 | * ``'LARES'``: use filtered values from CSR 97 | 98 | --slr-c50 : @replace 99 | Replace *C*\ :sub:`50` coefficients with SLR values 100 | 101 | * ``None``: use original values 102 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 103 | * ``'GSFC'``: use values from GSFC 104 | * ``'LARES'``: use filtered values from CSR 105 | 106 | --units -U : @after 107 | * ``1``: cm of water thickness 108 | * ``2``: mm of geoid height 109 | * ``3``: mm of elastic crustal deformation 110 | * ``4``: |mu|\ Gal gravitational perturbation 111 | * ``5``: mbar equivalent surface pressure 112 | 113 | --interval : @replace 114 | Output grid interval 115 | 116 | * ``1``: (0:360, 90:-90) 117 | * ``2``: (degree spacing/2) 118 | * ``3``: non-global grid (set with defined bounds) 119 | 120 | .. |mu| unicode:: U+03BC .. GREEK SMALL LETTER MU 121 | 122 | .. |times| unicode:: U+00D7 .. MULTIPLICATION SIGN 123 | -------------------------------------------------------------------------------- /doc/source/api_reference/harmonic_gradients.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | harmonic_gradients 3 | ================== 4 | 5 | - Calculates the zonal and meridional gradients of a scalar field from a series of spherical harmonics 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | from gravity_toolkit.harmonic_gradients import harmonic_gradients 13 | gradients = harmonic_gradients(clm,slm,lon,lat,LMAX=60) 14 | 15 | `Source code`__ 16 | 17 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/harmonic_gradients.py 18 | 19 | .. autofunction:: gravity_toolkit.harmonic_gradients 20 | 21 | .. autofunction:: gravity_toolkit.geostrophic_currents 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/harmonic_summation.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | harmonic_summation 3 | ================== 4 | 5 | - Returns the spatial field for a series of spherical harmonics 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | from gravity_toolkit.harmonic_summation import harmonic_summation 13 | spatial = harmonic_summation(clm,slm,lon,lat,LMAX=60) 14 | 15 | `Source code`__ 16 | 17 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/harmonic_summation.py 18 | 19 | .. autofunction:: gravity_toolkit.harmonic_summation 20 | 21 | .. autofunction:: gravity_toolkit.harmonic_transform 22 | 23 | .. autofunction:: gravity_toolkit.stokes_summation 24 | -------------------------------------------------------------------------------- /doc/source/api_reference/harmonics.rst: -------------------------------------------------------------------------------- 1 | ========= 2 | harmonics 3 | ========= 4 | 5 | Spherical harmonic data class for processing GRACE/GRACE-FO Level-2 data 6 | 7 | - Can read ascii, netCDF4, HDF5 files 8 | - Can read from an index of the above file types 9 | - Can merge a list of ``harmonics`` objects into a single object 10 | - Can subset to a list of GRACE/GRACE-FO months 11 | - Can calculate the mean field of a ``harmonics`` object 12 | - Can filter ``harmonics`` for correlated "striping" errors 13 | - Can output ``harmonics`` objects to ascii, netCDF4 or HDF5 files 14 | 15 | Calling Sequence 16 | ================ 17 | 18 | Reading a netCDF4 file 19 | 20 | .. code-block:: python 21 | 22 | from gravity_toolkit.harmonics import harmonics 23 | Ylms = harmonics().from_netCDF4(path_to_netCDF4_file) 24 | 25 | Reading a HDF5 file 26 | 27 | .. code-block:: python 28 | 29 | from gravity_toolkit.harmonics import harmonics 30 | Ylms = harmonics().from_HDF5(path_to_HDF5_file) 31 | 32 | Reading an index file of netCDF4 files and then outputting as a single file 33 | 34 | .. code-block:: python 35 | 36 | from gravity_toolkit.harmonics import harmonics 37 | Ylms = harmonics().from_index(path_to_index_file,'netCDF4') 38 | Ylms.to_netCDF4(path_to_netCDF4_file) 39 | 40 | Reading an index file of HDF5 files and subsetting to specific months 41 | 42 | .. code-block:: python 43 | 44 | from gravity_toolkit.harmonics import harmonics 45 | Ylms = harmonics().from_index(path_to_index_file,'HDF5').subset(months) 46 | 47 | Reading an index file of ascii files and truncating to a new degree and order 48 | 49 | .. code-block:: python 50 | 51 | from gravity_toolkit.harmonics import harmonics 52 | Ylms = harmonics().from_index(path_to_index_file,'ascii').truncate(lmax) 53 | 54 | Converting a dictionary object to a harmonics object and removing the mean field 55 | 56 | .. code-block:: python 57 | 58 | from gravity_toolkit.harmonics import harmonics 59 | Ylms = harmonics().from_dict(Ylms_dict) 60 | Ylms.mean(apply=True) 61 | 62 | 63 | `Source code`__ 64 | 65 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/harmonics.py 66 | 67 | General Attributes and Methods 68 | ============================== 69 | 70 | .. autoclass:: gravity_toolkit.harmonics 71 | :members: 72 | -------------------------------------------------------------------------------- /doc/source/api_reference/itsg_graz_grace_sync.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | itsg_graz_grace_sync.py 3 | ======================= 4 | 5 | - Syncs GRACE/GRACE-FO and auxiliary data from the `ITSG GRAZ server `_ 6 | - Creates an index file for each data product 7 | 8 | `Source code`__ 9 | 10 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/itsg_graz_grace_sync.py 11 | 12 | Calling Sequence 13 | ################ 14 | 15 | .. argparse:: 16 | :filename: itsg_graz_grace_sync.py 17 | :func: arguments 18 | :prog: itsg_graz_grace_sync.py 19 | :nodescription: 20 | :nodefault: 21 | -------------------------------------------------------------------------------- /doc/source/api_reference/legendre.rst: -------------------------------------------------------------------------------- 1 | ======== 2 | legendre 3 | ======== 4 | 5 | - Computes associated Legendre functions of degree ``l`` evaluated for elements ``x`` 6 | - ``l`` must be a scalar integer and ``x`` must contain real values ranging -1 <= ``x`` <= 1 7 | - Unnormalized associated Legendre function values will overflow for ``l`` > 150 8 | 9 | Calling Sequence 10 | ################ 11 | 12 | .. code-block:: python 13 | 14 | from gravity_toolkit.legendre import legendre 15 | Pl = legendre(l, x) 16 | 17 | `Source code`__ 18 | 19 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/legendre.py 20 | 21 | .. autofunction:: gravity_toolkit.legendre 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/legendre_polynomials.rst: -------------------------------------------------------------------------------- 1 | ==================== 2 | legendre_polynomials 3 | ==================== 4 | 5 | - Computes fully-normalized Legendre polynomials for an array of ``x`` values and their first derivative 6 | - Calculates Legendre polynomials for zonal harmonics (order 0) 7 | 8 | Calling Sequence 9 | ################ 10 | 11 | .. code-block:: python 12 | 13 | from gravity_toolkit.legendre_polynomials import legendre_polynomials 14 | pl,dpl = legendre_polynomials(LMAX, x) 15 | 16 | `Source code`__ 17 | 18 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/legendre_polynomials.py 19 | 20 | .. autofunction:: gravity_toolkit.legendre_polynomials -------------------------------------------------------------------------------- /doc/source/api_reference/make_grace_index.rst: -------------------------------------------------------------------------------- 1 | =================== 2 | make_grace_index.py 3 | =================== 4 | 5 | - Creates index files of GRACE/GRACE-FO Level-2 spherical harmonic data files 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/make_grace_index.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: make_grace_index.py 16 | :func: arguments 17 | :prog: make_grace_index.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/mascon_reconstruct.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | mascon_reconstruct.py 3 | ===================== 4 | 5 | - Calculates the equivalent spherical harmonics from a mascon time series 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/mascon_reconstruct.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: mascon_reconstruct.py 16 | :func: arguments 17 | :prog: mascon_reconstruct.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | --love -n : @after 22 | * ``0``: Han and Wahr (1995) values from PREM :cite:p:`Han:1995go` 23 | * ``1``: Gegout (2005) values from PREM :cite:p:`Gegout:2010gc` 24 | * ``2``: Wang et al. (2012) values from PREM :cite:p:`Wang:2012gc` 25 | * ``3``: Wang et al. (2012) values from PREM with hard sediment :cite:p:`Wang:2012gc` 26 | * ``4``: Wang et al. (2012) values from PREM with soft sediment :cite:p:`Wang:2012gc` 27 | 28 | --reference : @after 29 | * ``'CF'``: Center of Surface Figure 30 | * ``'CM'``: Center of Mass of Earth System 31 | * ``'CE'``: Center of Mass of Solid Earth 32 | 33 | --gia -G : @after 34 | * ``'IJ05-R2'``: Ivins R2 GIA Models :cite:p:`Ivins:2013cq` 35 | * ``'W12a'``: Whitehouse GIA Models :cite:p:`Whitehouse:2012jj` 36 | * ``'SM09'``: Simpson/Milne GIA Models :cite:p:`Simpson:2009hg` 37 | * ``'ICE6G'``: ICE-6G GIA Models :cite:p:`Peltier:2015bo` 38 | * ``'Wu10'``: Wu (2010) GIA Correction :cite:p:`Wu:2010dq` 39 | * ``'AW13-ICE6G'``: Geruo A ICE-6G GIA Models :cite:p:`A:2013kh` 40 | * ``'AW13-IJ05'``: Geruo A IJ05-R2 GIA Models :cite:p:`A:2013kh` 41 | * ``'Caron'``: Caron JPL GIA Assimilation :cite:p:`Caron:2018ba` 42 | * ``'ICE6G-D'``: ICE-6G Version-D GIA Models :cite:p:`Peltier:2018dp` 43 | * ``'ascii'``: reformatted GIA in ascii format 44 | * ``'netCDF4'``: reformatted GIA in netCDF4 format 45 | * ``'HDF5'``: reformatted GIA in HDF5 format 46 | 47 | --fit-method : @after 48 | * ``1``: mass coefficients 49 | * ``2``: geoid coefficients 50 | 51 | -------------------------------------------------------------------------------- /doc/source/api_reference/mascons.rst: -------------------------------------------------------------------------------- 1 | ======= 2 | mascons 3 | ======= 4 | 5 | Conversion routines for publicly available GRACE/GRACE-FO mascon solutions 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/mascons.py 10 | 11 | 12 | General Methods 13 | =============== 14 | 15 | .. autofunction:: gravity_toolkit.mascons.to_gsfc 16 | 17 | .. autofunction:: gravity_toolkit.mascons.to_jpl 18 | 19 | .. autofunction:: gravity_toolkit.mascons.from_gsfc 20 | 21 | .. autofunction:: gravity_toolkit.mascons.from_jpl 22 | 23 | -------------------------------------------------------------------------------- /doc/source/api_reference/monte_carlo_degree_one.rst: -------------------------------------------------------------------------------- 1 | ========================= 2 | monte_carlo_degree_one.py 3 | ========================= 4 | 5 | - Estimates uncertainties in degree 1 using GRACE/GRACE-FO coefficients of degree 2 and greater, and modeled ocean bottom pressure variations in a Monte Carlo scheme :cite:p:`Swenson:2008cr,Sutterley:2019bx`. 6 | - Calculates the estimated spherical harmonic errors following :cite:t:`Wahr:2006bx` 7 | 8 | `Source code`__ 9 | 10 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/monte_carlo_degree_one.py 11 | 12 | Calling Sequence 13 | ################ 14 | 15 | .. argparse:: 16 | :filename: monte_carlo_degree_one.py 17 | :func: arguments 18 | :prog: monte_carlo_degree_one.py 19 | :nodescription: 20 | :nodefault: 21 | 22 | --love -n : @after 23 | * ``0``: Han and Wahr (1995) values from PREM :cite:p:`Han:1995go` 24 | * ``1``: Gegout (2005) values from PREM :cite:p:`Gegout:2010gc` 25 | * ``2``: Wang et al. (2012) values from PREM :cite:p:`Wang:2012gc` 26 | * ``3``: Wang et al. (2012) values from PREM with hard sediment :cite:p:`Wang:2012gc` 27 | * ``4``: Wang et al. (2012) values from PREM with soft sediment :cite:p:`Wang:2012gc` 28 | 29 | --kl -k : @after 30 | * ``None``: use derived values from :cite:p:`Trupin:1992kp,Blewitt:2003bz`. 31 | 32 | --gia -G : @after 33 | * ``'IJ05-R2'``: Ivins R2 GIA Models :cite:p:`Ivins:2013cq` 34 | * ``'W12a'``: Whitehouse GIA Models :cite:p:`Whitehouse:2012jj` 35 | * ``'SM09'``: Simpson/Milne GIA Models :cite:p:`Simpson:2009hg` 36 | * ``'ICE6G'``: ICE-6G GIA Models :cite:p:`Peltier:2015bo` 37 | * ``'Wu10'``: Wu (2010) GIA Correction :cite:p:`Wu:2010dq` 38 | * ``'AW13-ICE6G'``: Geruo A ICE-6G GIA Models :cite:p:`A:2013kh` 39 | * ``'AW13-IJ05'``: Geruo A IJ05-R2 GIA Models :cite:p:`A:2013kh` 40 | * ``'Caron'``: Caron JPL GIA Assimilation :cite:p:`Caron:2018ba` 41 | * ``'ICE6G-D'``: ICE-6G Version-D GIA Models :cite:p:`Peltier:2018dp` 42 | * ``'ascii'``: reformatted GIA in ascii format 43 | * ``'netCDF4'``: reformatted GIA in netCDF4 format 44 | * ``'HDF5'``: reformatted GIA in HDF5 format 45 | 46 | --slr-c20 : @replace 47 | Replace *C*\ :sub:`20` coefficients with SLR values 48 | 49 | * ``None``: use original values 50 | * ``'CSR'``: use values from CSR (TN-07, TN-09, TN-11) 51 | * ``'GFZ'``: use values from GFZ 52 | * ``'GSFC'``: use values from GSFC (TN-14) 53 | 54 | --slr-21 X : @replace 55 | Replace *C*\ :sub:`21` and *S*\ :sub:`21` coefficients with SLR values 56 | 57 | * ``None``: use original values 58 | * ``'CSR'``: use values from CSR 59 | * ``'GFZ'``: use values from GFZ GravIS 60 | * ``'GSFC'``: use values from GSFC 61 | 62 | --slr-22 : @replace 63 | Replace *C*\ :sub:`22` and *S*\ :sub:`22` coefficients with SLR values 64 | 65 | * ``None``: use original values 66 | * ``'CSR'``: use values from CSR 67 | * ``'GSFC'``: use values from GSFC 68 | 69 | --slr-c30 : @replace 70 | Replace *C*\ :sub:`30` coefficients with SLR values 71 | 72 | * ``None``: use original values 73 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 74 | * ``'GFZ'``: use values from GFZ GravIS 75 | * ``'GSFC'``: use values from GSFC (TN-14) 76 | * ``'LARES'``: use filtered values from CSR 77 | 78 | --slr-c40 : @replace 79 | Replace *C*\ :sub:`40` coefficients with SLR values 80 | 81 | * ``None``: use original values 82 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 83 | * ``'GSFC'``: use values from GSFC 84 | * ``'LARES'``: use filtered values from CSR 85 | 86 | --slr-c50 : @replace 87 | Replace *C*\ :sub:`50` coefficients with SLR values 88 | 89 | * ``None``: use original values 90 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 91 | * ``'GSFC'``: use values from GSFC 92 | * ``'LARES'``: use filtered values from CSR 93 | 94 | --solver -s : @replace 95 | Least squares solver for degree one solutions 96 | 97 | * ``'inv'``: matrix inversion 98 | * ``'lstsq'``: least squares solution 99 | * ``'gelsy'``: complete orthogonal factorization solution 100 | * ``'gelss'``: singular value decomposition (SVD) solution 101 | * ``'gelsd'``: singular value decomposition (SVD) solution with a divide and conquer method 102 | 103 | .. |times| unicode:: U+00D7 .. MULTIPLICATION SIGN 104 | -------------------------------------------------------------------------------- /doc/source/api_reference/ocean_stokes.rst: -------------------------------------------------------------------------------- 1 | ============ 2 | ocean_stokes 3 | ============ 4 | 5 | - Reads a land-sea mask and converts to a series of spherical harmonics 6 | - `netCDF4 land-sea mask files `_ from :cite:p:`Sutterley:2020js` 7 | * updated 1.0, 0.5 and 0.25 degree masks from `ORNL as part of ISLSCP `_ 8 | 9 | Calling Sequence 10 | ################ 11 | 12 | .. code-block:: python 13 | 14 | from gravity_toolkit.ocean_stokes import ocean_stokes 15 | ocean_Ylms = ocean_stokes(LANDMASK, LMAX, MMAX=MMAX, LOVE=(hl,kl,ll)) 16 | 17 | `Source code`__ 18 | 19 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/ocean_stokes.py) 20 | 21 | .. autofunction:: gravity_toolkit.ocean_stokes 22 | 23 | .. autofunction:: gravity_toolkit.ocean_stokes.find_isolated_points 24 | -------------------------------------------------------------------------------- /doc/source/api_reference/piecewise_grace_maps.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | piecewise_grace_maps.py 3 | ======================= 4 | 5 | - Reads in GRACE/GRACE-FO spatial files and fits a piecewise regression model at each grid point for breakpoint analysis 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/piecewise_grace_maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: piecewise_grace_maps.py 16 | :func: arguments 17 | :prog: piecewise_grace_maps.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | --units -U : @after 22 | * ``1``: cm of water thickness 23 | * ``2``: mm of geoid height 24 | * ``3``: mm of elastic crustal deformation 25 | * ``4``: |mu|\ Gal gravitational perturbation 26 | * ``5``: mbar equivalent surface pressure 27 | 28 | --interval : @replace 29 | Output grid interval 30 | 31 | * ``1``: (0:360, 90:-90) 32 | * ``2``: (degree spacing/2) 33 | * ``3``: non-global grid (set with defined bounds) 34 | 35 | .. |mu| unicode:: U+03BC .. GREEK SMALL LETTER MU 36 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_AIS_GrIS_maps.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | plot_AIS_GrIS_maps.py 3 | ===================== 4 | 5 | - Creates GMT-like plots for the Greenland and Antarctic ice sheets 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_GrIS_maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_AIS_GrIS_maps.py 16 | :func: arguments 17 | :prog: plot_AIS_GrIS_maps.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_AIS_grid_3maps.rst: -------------------------------------------------------------------------------- 1 | ====================== 2 | plot_AIS_grid_3maps.py 3 | ====================== 4 | 5 | - Creates 3 GMT-like plots for the Antarctic Ice Sheet on a polar stereographic south (3031) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_grid_3maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_AIS_grid_3maps.py 16 | :func: arguments 17 | :prog: plot_AIS_grid_3maps.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_AIS_grid_4maps.rst: -------------------------------------------------------------------------------- 1 | ====================== 2 | plot_AIS_grid_4maps.py 3 | ====================== 4 | 5 | - Creates 4 GMT-like plots for the Antarctic Ice Sheet on a polar stereographic south (3031) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_grid_4maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_AIS_grid_4maps.py 16 | :func: arguments 17 | :prog: plot_AIS_grid_4maps.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_AIS_grid_maps.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | plot_AIS_grid_maps.py 3 | ===================== 4 | 5 | - Creates GMT-like plots for the Antarctic Ice Sheet on a polar stereographic south (3031) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_grid_maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_AIS_grid_maps.py 16 | :func: arguments 17 | :prog: plot_AIS_grid_maps.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_AIS_grid_movie.rst: -------------------------------------------------------------------------------- 1 | ====================== 2 | plot_AIS_grid_movie.py 3 | ====================== 4 | 5 | - Creates GMT-like anomations for the Antarctic Ice Sheet on a polar stereographic south (3031) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_grid_movie.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_AIS_grid_movie.py 16 | :func: arguments 17 | :prog: plot_AIS_grid_movie.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_AIS_regional_maps.rst: -------------------------------------------------------------------------------- 1 | ========================= 2 | plot_AIS_regional_maps.py 3 | ========================= 4 | 5 | - Creates GMT-like plots for sub-regions of Antarctica on a polar stereographic south (3031) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_regional_maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_AIS_regional_maps.py 16 | :func: arguments 17 | :prog: plot_AIS_regional_maps.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_AIS_regional_movie.rst: -------------------------------------------------------------------------------- 1 | ========================== 2 | plot_AIS_regional_movie.py 3 | ========================== 4 | 5 | - Creates GMT-like animations for sub-regions of Antarctica on a polar stereographic south (3031) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_regional_movie.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_AIS_regional_movie.py 16 | :func: arguments 17 | :prog: plot_AIS_regional_movie.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_GrIS_grid_3maps.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | plot_GrIS_grid_3maps.py 3 | ======================= 4 | 5 | - Creates 3 GMT-like plots for the Greenland Ice Sheet on a NSIDC polar stereographic north (3413) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_GrIS_grid_3maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_GrIS_grid_3maps.py 16 | :func: arguments 17 | :prog: plot_GrIS_grid_3maps.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_GrIS_grid_5maps.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | plot_GrIS_grid_5maps.py 3 | ======================= 4 | 5 | - Creates 5 GMT-like plots for the Greenland Ice Sheet on a NSIDC polar stereographic north (3413) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_GrIS_grid_5maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_GrIS_grid_5maps.py 16 | :func: arguments 17 | :prog: plot_GrIS_grid_5maps.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_GrIS_grid_maps.rst: -------------------------------------------------------------------------------- 1 | ====================== 2 | plot_GrIS_grid_maps.py 3 | ====================== 4 | 5 | - Creates GMT-like plots for the Greenland Ice Sheet on a NSIDC polar stereographic north (3413) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_GrIS_grid_maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_GrIS_grid_maps.py 16 | :func: arguments 17 | :prog: plot_GrIS_grid_maps.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_GrIS_grid_movie.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | plot_GrIS_grid_movie.py 3 | ======================= 4 | 5 | - Creates GMT-like animations for the Greenland Ice Sheet on a NSIDC polar stereographic north (3413) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_GrIS_grid_movie.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_GrIS_grid_movie.py 16 | :func: arguments 17 | :prog: plot_GrIS_grid_movie.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_global_grid_3maps.rst: -------------------------------------------------------------------------------- 1 | ========================= 2 | plot_global_grid_3maps.py 3 | ========================= 4 | 5 | - Creates 3 GMT-like plots on a global Plate Carr\ |eacute|\e (Equirectangular) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_global_grid_3maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_global_grid_3maps.py 16 | :func: arguments 17 | :prog: plot_global_grid_3maps.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | .. |eacute| unicode:: U+00E9 .. LATIN SMALL LETTER E WITH ACUTE 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_global_grid_4maps.rst: -------------------------------------------------------------------------------- 1 | ========================= 2 | plot_global_grid_4maps.py 3 | ========================= 4 | 5 | - Creates 4 GMT-like plots on a global Plate Carr\ |eacute|\e (Equirectangular) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_global_grid_4maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_global_grid_4maps.py 16 | :func: arguments 17 | :prog: plot_global_grid_4maps.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | .. |eacute| unicode:: U+00E9 .. LATIN SMALL LETTER E WITH ACUTE 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_global_grid_5maps.rst: -------------------------------------------------------------------------------- 1 | ========================= 2 | plot_global_grid_5maps.py 3 | ========================= 4 | 5 | - Creates 5 GMT-like plots on a global Plate Carr\ |eacute|\e (Equirectangular) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_global_grid_5maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_global_grid_5maps.py 16 | :func: arguments 17 | :prog: plot_global_grid_5maps.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | .. |eacute| unicode:: U+00E9 .. LATIN SMALL LETTER E WITH ACUTE 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_global_grid_9maps.rst: -------------------------------------------------------------------------------- 1 | ========================= 2 | plot_global_grid_9maps.py 3 | ========================= 4 | 5 | - Creates 9 GMT-like plots on a global Plate Carr\ |eacute|\e (Equirectangular) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_global_grid_9maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_global_grid_9maps.py 16 | :func: arguments 17 | :prog: plot_global_grid_9maps.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | .. |eacute| unicode:: U+00E9 .. LATIN SMALL LETTER E WITH ACUTE 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_global_grid_maps.rst: -------------------------------------------------------------------------------- 1 | ======================== 2 | plot_global_grid_maps.py 3 | ======================== 4 | 5 | - Creates GMT-like plots on a global Plate Carr\ |eacute|\e (Equirectangular) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_global_grid_maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_global_grid_maps.py 16 | :func: arguments 17 | :prog: plot_global_grid_maps.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | .. |eacute| unicode:: U+00E9 .. LATIN SMALL LETTER E WITH ACUTE 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/plot_global_grid_movie.rst: -------------------------------------------------------------------------------- 1 | ========================= 2 | plot_global_grid_movie.py 3 | ========================= 4 | 5 | - Creates GMT-like animations on a global Plate Carr\ |eacute|\e (Equirectangular) projection 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_global_grid_movie.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: plot_global_grid_movie.py 16 | :func: arguments 17 | :prog: plot_global_grid_movie.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | .. |eacute| unicode:: U+00E9 .. LATIN SMALL LETTER E WITH ACUTE 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/podaac_cumulus.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | podaac_cumulus.py 3 | ================= 4 | 5 | - Syncs GRACE/GRACE-FO data from `NASA JPL PO.DAAC Cumulus AWS S3 bucket `_ 6 | - S3 Cumulus syncs are only available in AWS instances in ``us-west-2`` 7 | - Creates an index file for each data product 8 | 9 | `Source code`__ 10 | 11 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/podaac_cumulus.py 12 | 13 | Calling Sequence 14 | ################ 15 | 16 | .. argparse:: 17 | :filename: podaac_cumulus.py 18 | :func: arguments 19 | :prog: podaac_cumulus.py 20 | :nodescription: 21 | :nodefault: 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/quick_mascon_plot.rst: -------------------------------------------------------------------------------- 1 | ==================== 2 | quick_mascon_plot.py 3 | ==================== 4 | 5 | - Plots a mascon time series file for a particular format 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/quick_mascon_plot.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: quick_mascon_plot.py 16 | :func: arguments 17 | :prog: quick_mascon_plot.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/quick_mascon_regress.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | quick_mascon_regress.py 3 | ======================= 4 | 5 | - Creates a regression summary file for a mascon time series file 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/quick_mascon_regress.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: quick_mascon_regress.py 16 | :func: arguments 17 | :prog: quick_mascon_regress.py 18 | :nodescription: 19 | :nodefault: 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/read_GIA_model.rst: -------------------------------------------------------------------------------- 1 | ============== 2 | read_GIA_model 3 | ============== 4 | 5 | - Reads Glacial Isostatic Adjustment (GIA) files for given modeling group formats 6 | - Outputs spherical harmonics for the GIA rates and the GIA model parameters 7 | - Can also output fully normalized harmonics to netCDF4 or HDF5 formats 8 | 9 | Calling Sequence 10 | ################ 11 | 12 | .. code-block:: python 13 | 14 | from gravity_toolkit.read_GIA_model import read_GIA_model 15 | GIA_Ylms = read_GIA_model('Stokes.R2_65_.2_1.5_L120',GIA='IJ05-R2',LMAX=60) 16 | 17 | `Source code`__ 18 | 19 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/read_GIA_model.py 20 | 21 | .. autofunction:: gravity_toolkit.read_GIA_model 22 | 23 | .. autoclass:: gravity_toolkit.gia 24 | :members: 25 | -------------------------------------------------------------------------------- /doc/source/api_reference/read_GRACE_harmonics.rst: -------------------------------------------------------------------------------- 1 | ==================== 2 | read_GRACE_harmonics 3 | ==================== 4 | 5 | - Reads GRACE/GRACE-FO files and extracts spherical harmonic data and drift rates (RL04) 6 | - Adds drift rates to clm and slm for Release-4 harmonics 7 | - Correct Release-5 GSM data for drift in pole tide 8 | - Extracts start and end date of GRACE/GRACE-FO files and calculates mean of range 9 | 10 | Calling Sequence 11 | ################ 12 | 13 | .. code-block:: python 14 | 15 | from gravity_toolkit.read_GRACE_harmonics import read_GRACE_harmonics 16 | CSR_L2_input = read_GRACE_harmonics('GSM-2_2002095-2002120_0021_UTCSR_0060_0005.gz',60) 17 | GFZ_L2_input = read_GRACE_harmonics('GSM-2_2002094-2002120_0024_EIGEN_G---_005a.gz',90) 18 | JPL_L2_input = read_GRACE_harmonics('GSM-2_2002091-2002120_0018_JPLEM_0001_0005.gz',60) 19 | JPLMSC_input = read_GRACE_harmonics('GSM-2_2003001-2003031_0029_JPLMSC_0719_0005',719) 20 | 21 | `Source code`__ 22 | 23 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/read_GRACE_harmonics.py 24 | 25 | .. autofunction:: gravity_toolkit.read_GRACE_harmonics 26 | 27 | .. autofunction:: gravity_toolkit.read_GRACE_harmonics.parse_file 28 | 29 | .. autofunction:: gravity_toolkit.read_GRACE_harmonics.extract_file 30 | -------------------------------------------------------------------------------- /doc/source/api_reference/read_SLR_harmonics.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | read_SLR_harmonics 3 | ================== 4 | 5 | - Reads 5\ |times|\ 5 spherical harmonic coefficients with 1 coefficient from degree 6 all calculated from satellite laser ranging (SLR) measurements 6 | - Calculated by the University of Texas Center for Space Research (CSR) and NASA Goddard Space Flight Center (GSFC) 7 | 8 | * CSR: ``CSR_Monthly_5x5_Gravity_Harmonics.txt`` 9 | * GSFC: ``gsfc_slr_5x5c61s61.txt`` 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. code-block:: python 15 | 16 | from gravity_toolkit.read_SLR_harmonics import read_SLR_harmonics 17 | Ylms = read_SLR_harmonics(input_file) 18 | 19 | `Source code`__ 20 | 21 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/read_SLR_harmonics.py 22 | 23 | .. autofunction:: gravity_toolkit.read_SLR_harmonics 24 | 25 | .. autofunction:: gravity_toolkit.read_SLR_harmonics.read_CSR_monthly_6x1 26 | 27 | .. autofunction:: gravity_toolkit.read_SLR_harmonics.read_GSFC_weekly_6x1 28 | 29 | .. autofunction:: gravity_toolkit.read_SLR_harmonics.convert_weekly 30 | 31 | .. |times| unicode:: U+00D7 .. MULTIPLICATION SIGN 32 | -------------------------------------------------------------------------------- /doc/source/api_reference/read_gfc_harmonics.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | read_gfc_harmonics 3 | ================== 4 | 5 | - Reads gfc files and extracts spherical harmonics for Swarm and GRAZ GRACE/GRACE-FO data 6 | - Parses date of GRACE/GRACE-FO data from filename 7 | 8 | Calling Sequence 9 | ################ 10 | 11 | .. code-block:: python 12 | 13 | from gravity_toolkit.read_gfc_harmonics import read_gfc_harmonics 14 | Ylms = read_gfc_harmonics(input_file, TIDE='tide_free') 15 | 16 | `Source code`__ 17 | 18 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/read_gfc_harmonics.py 19 | 20 | .. autofunction:: gravity_toolkit.read_gfc_harmonics 21 | -------------------------------------------------------------------------------- /doc/source/api_reference/read_love_numbers.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | read_love_numbers 3 | ================= 4 | 5 | - Reads sets of load Love/Shida numbers computed using outputs from the Preliminary Reference Earth Model (PREM) or other Earth models 6 | - Linearly interpolates load Love/Shida numbers for missing degrees 7 | - Linearly extrapolates load Love/Shida numbers beyond maximum degree of dataset 8 | - Applies isomorphic parameters for different reference frames 9 | 10 | Calling Sequence 11 | ################ 12 | 13 | .. code-block:: python 14 | 15 | from gravity_toolkit.utilities import get_data_path 16 | from gravity_toolkit.read_love_numbers import read_love_numbers 17 | love_numbers_file = get_data_path(['data','love_numbers']) 18 | hl,kl,ll = read_love_numbers(love_numbers_file, FORMAT='tuple', REFERENCE='CF') 19 | 20 | `Source code`__ 21 | 22 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/read_love_numbers.py 23 | 24 | .. autofunction:: gravity_toolkit.read_love_numbers 25 | 26 | .. autofunction:: gravity_toolkit.read_love_numbers.love_number_formatter 27 | 28 | .. autofunction:: gravity_toolkit.read_love_numbers.extract_love_numbers 29 | 30 | .. autofunction:: gravity_toolkit.read_love_numbers.load_love_numbers 31 | 32 | .. autoclass:: gravity_toolkit.love_numbers 33 | :members: 34 | -------------------------------------------------------------------------------- /doc/source/api_reference/regress_grace_maps.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | regress_grace_maps.py 3 | ===================== 4 | 5 | - Reads in GRACE/GRACE-FO spatial files and fits a regression model at each grid point 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/regress_grace_maps.py 10 | 11 | Calling Sequence 12 | ################ 13 | 14 | .. argparse:: 15 | :filename: regress_grace_maps.py 16 | :func: arguments 17 | :prog: regress_grace_maps.py 18 | :nodescription: 19 | :nodefault: 20 | 21 | --units -U : @after 22 | * ``1``: cm of water thickness 23 | * ``2``: mm of geoid height 24 | * ``3``: mm of elastic crustal deformation 25 | * ``4``: |mu|\ Gal gravitational perturbation 26 | * ``5``: mbar equivalent surface pressure 27 | 28 | --interval : @replace 29 | Output grid interval 30 | 31 | * ``1``: (0:360, 90:-90) 32 | * ``2``: (degree spacing/2) 33 | * ``3``: non-global grid (set with defined bounds) 34 | 35 | .. |mu| unicode:: U+03BC .. GREEK SMALL LETTER MU 36 | -------------------------------------------------------------------------------- /doc/source/api_reference/run_grace_date.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | run_grace_date.py 3 | ================= 4 | 5 | - Wrapper program for running GRACE date and months programs 6 | - Reads GRACE/GRACE-FO index files 7 | - Reads dates of each GRACE/GRACE-FO file and assigns the month number 8 | - Creates an index of dates for GRACE/GRACE-FO files 9 | - Creates an index of dates for all GRACE/GRACE-FO processing centers 10 | 11 | `Source code`__ 12 | 13 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/run_grace_date.py 14 | 15 | Calling Sequence 16 | ################ 17 | 18 | .. argparse:: 19 | :filename: run_grace_date.py 20 | :func: arguments 21 | :prog: run_grace_date.py 22 | :nodescription: 23 | :nodefault: 24 | -------------------------------------------------------------------------------- /doc/source/api_reference/run_sea_level_equation.rst: -------------------------------------------------------------------------------- 1 | ========================= 2 | run_sea_level_equation.py 3 | ========================= 4 | 5 | - Solves the sea level equation with the option of including polar motion feedback :cite:p:`Farrell:1976hm,Kendall:2005ds,Mitrovica:2003cq` 6 | - Uses a Clenshaw summation to calculate the spherical harmonic summation :cite:p:`Holmes:2002ff,Tscherning:1982tu` 7 | 8 | `Source code`__ 9 | 10 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/run_sea_level_equation.py 11 | 12 | 13 | Calling Sequence 14 | ################ 15 | 16 | .. argparse:: 17 | :filename: run_sea_level_equation.py 18 | :func: arguments 19 | :prog: run_sea_level_equation.py 20 | :nodescription: 21 | :nodefault: 22 | 23 | --love -n : @after 24 | * ``0``: Han and Wahr (1995) values from PREM :cite:p:`Han:1995go` 25 | * ``1``: Gegout (2005) values from PREM :cite:p:`Gegout:2010gc` 26 | * ``2``: Wang et al. (2012) values from PREM :cite:p:`Wang:2012gc` 27 | * ``3``: Wang et al. (2012) values from PREM with hard sediment :cite:p:`Wang:2012gc` 28 | * ``4``: Wang et al. (2012) values from PREM with soft sediment :cite:p:`Wang:2012gc` 29 | 30 | --body -b : @after 31 | * ``0``: :cite:p:`Wahr:1981ea` and :cite:p:`Wahr:1985gr` values from PREM 32 | * ``1``: :cite:p:`Farrell:1972cm` values from Gutenberg-Bullen oceanic mantle model 33 | 34 | --fluid -f : @after 35 | * ``0``: :cite:p:`Han:1989kj` fluid love number 36 | * ``1``: :cite:p:`Munk:1960uk` secular love number 37 | * ``2``: :cite:p:`Munk:1960uk` fluid love number 38 | * ``3``: :cite:p:`Lambeck:1980um` fluid love number 39 | 40 | --polar-feedback : @replace 41 | Include polar feedback :cite:p:`Wahr:1985gr` 42 | 43 | --reference : @after 44 | * ``'CF'``: Center of Surface Figure 45 | * ``'CM'``: Center of Mass of Earth System 46 | * ``'CE'``: Center of Mass of Solid Earth 47 | -------------------------------------------------------------------------------- /doc/source/api_reference/scale_grace_maps.rst: -------------------------------------------------------------------------------- 1 | =================== 2 | scale_grace_maps.py 3 | =================== 4 | 5 | - Reads in GRACE/GRACE-FO spherical harmonic coefficients and exports scaled spatial fields 6 | - Correct spherical harmonics with the specified GIA model group 7 | - Filters and smooths data with specified processing algorithms :cite:p:`Jekeli:1981vj,Swenson:2006hu` 8 | - Converts data to centimeters water equivalent, performs a spherical harmonic summation to convert to the spatial domain :cite:p:`Wahr:1998hy` 9 | - Scales the spatial fields following :cite:t:`Landerer:2012kf` 10 | - Calculates the scaled spatial error field following :cite:t:`Wahr:2006bx` 11 | 12 | `Source code`__ 13 | 14 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/scale_grace_maps.py 15 | 16 | Calling Sequence 17 | ################ 18 | 19 | .. argparse:: 20 | :filename: scale_grace_maps.py 21 | :func: arguments 22 | :prog: scale_grace_maps.py 23 | :nodescription: 24 | :nodefault: 25 | 26 | --love -n : @after 27 | * ``0``: Han and Wahr (1995) values from PREM :cite:p:`Han:1995go` 28 | * ``1``: Gegout (2005) values from PREM :cite:p:`Gegout:2010gc` 29 | * ``2``: Wang et al. (2012) values from PREM :cite:p:`Wang:2012gc` 30 | * ``3``: Wang et al. (2012) values from PREM with hard sediment :cite:p:`Wang:2012gc` 31 | * ``4``: Wang et al. (2012) values from PREM with soft sediment :cite:p:`Wang:2012gc` 32 | 33 | --reference : @after 34 | * ``'CF'``: Center of Surface Figure 35 | * ``'CM'``: Center of Mass of Earth System 36 | * ``'CE'``: Center of Mass of Solid Earth 37 | 38 | --gia -G : @after 39 | * ``'IJ05-R2'``: Ivins R2 GIA Models :cite:p:`Ivins:2013cq` 40 | * ``'W12a'``: Whitehouse GIA Models :cite:p:`Whitehouse:2012jj` 41 | * ``'SM09'``: Simpson/Milne GIA Models :cite:p:`Simpson:2009hg` 42 | * ``'ICE6G'``: ICE-6G GIA Models :cite:p:`Peltier:2015bo` 43 | * ``'Wu10'``: Wu (2010) GIA Correction :cite:p:`Wu:2010dq` 44 | * ``'AW13-ICE6G'``: Geruo A ICE-6G GIA Models :cite:p:`A:2013kh` 45 | * ``'AW13-IJ05'``: Geruo A IJ05-R2 GIA Models :cite:p:`A:2013kh` 46 | * ``'Caron'``: Caron JPL GIA Assimilation :cite:p:`Caron:2018ba` 47 | * ``'ICE6G-D'``: ICE-6G Version-D GIA Models :cite:p:`Peltier:2018dp` 48 | * ``'ascii'``: reformatted GIA in ascii format 49 | * ``'netCDF4'``: reformatted GIA in netCDF4 format 50 | * ``'HDF5'``: reformatted GIA in HDF5 format 51 | 52 | --geocenter : @after 53 | * ``None`` 54 | * ``'Tellus'``: GRACE/GRACE-FO TN-13 coefficients from PO.DAAC 55 | * ``'SLR'``: satellite laser ranging coefficients from CSR 56 | * ``'UCI'``: Sutterley and Velicogna coefficients, Remote Sensing (2019) 57 | * ``'Swenson'``: GRACE-derived coefficients from Sean Swenson 58 | * ``'GFZ'``: GRACE/SLR derived coefficients from GFZ GravIS 59 | 60 | --slr-c20 : @replace 61 | Replace *C*\ :sub:`20` coefficients with SLR values 62 | 63 | * ``None``: use original values 64 | * ``'CSR'``: use values from CSR (TN-07, TN-09, TN-11) 65 | * ``'GFZ'``: use values from GFZ 66 | * ``'GSFC'``: use values from GSFC (TN-14) 67 | 68 | --slr-21 X : @replace 69 | Replace *C*\ :sub:`21` and *S*\ :sub:`21` coefficients with SLR values 70 | 71 | * ``None``: use original values 72 | * ``'CSR'``: use values from CSR 73 | * ``'GFZ'``: use values from GFZ GravIS 74 | * ``'GSFC'``: use values from GSFC 75 | 76 | --slr-22 : @replace 77 | Replace *C*\ :sub:`22` and *S*\ :sub:`22` coefficients with SLR values 78 | 79 | * ``None``: use original values 80 | * ``'CSR'``: use values from CSR 81 | * ``'GSFC'``: use values from GSFC 82 | 83 | --slr-c30 : @replace 84 | Replace *C*\ :sub:`30` coefficients with SLR values 85 | 86 | * ``None``: use original values 87 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 88 | * ``'GFZ'``: use values from GFZ GravIS 89 | * ``'GSFC'``: use values from GSFC (TN-14) 90 | * ``'LARES'``: use filtered values from CSR 91 | 92 | --slr-c40 : @replace 93 | Replace *C*\ :sub:`40` coefficients with SLR values 94 | 95 | * ``None``: use original values 96 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 97 | * ``'GSFC'``: use values from GSFC 98 | * ``'LARES'``: use filtered values from CSR 99 | 100 | --slr-c50 : @replace 101 | Replace *C*\ :sub:`50` coefficients with SLR values 102 | 103 | * ``None``: use original values 104 | * ``'CSR'``: use values from CSR (5\ |times|\ 5 with 6,1) 105 | * ``'GSFC'``: use values from GSFC 106 | * ``'LARES'``: use filtered values from CSR 107 | 108 | --interval : @replace 109 | Output grid interval 110 | 111 | * ``1``: (0:360, 90:-90) 112 | * ``2``: (degree spacing/2) 113 | * ``3``: non-global grid (set with defined bounds) 114 | 115 | .. |times| unicode:: U+00D7 .. MULTIPLICATION SIGN 116 | -------------------------------------------------------------------------------- /doc/source/api_reference/sea_level_equation.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | sea_level_equation 3 | ================== 4 | 5 | - Solves the sea level equation with the option of including polar motion feedback 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | from gravity_toolkit.associated_legendre import plm_holmes 13 | from gravity_toolkit.sea_level_equation import sea_level_equation 14 | PLM, dPLM = plm_holmes(LMAX, np.cos(th)) 15 | Ylms = sea_level_equation(loadClm, loadSlm, lon, lat, land_function, 16 | LMAX=LMAX, PLM=PLM, LOVE=(hl,kl,ll), ITERATIONS=6, POLAR=True) 17 | 18 | `Source code`__ 19 | 20 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/sea_level_equation.py 21 | 22 | .. autofunction:: gravity_toolkit.sea_level_equation 23 | -------------------------------------------------------------------------------- /doc/source/api_reference/spatial.rst: -------------------------------------------------------------------------------- 1 | ======= 2 | spatial 3 | ======= 4 | 5 | Spatial data class for reading, writing and processing spatial data 6 | 7 | - Can read ascii, netCDF4, HDF5 files 8 | - Can read from an index of the above file types 9 | - Can merge a list of ``spatial`` objects into a single object 10 | - Can subset to a list of GRACE/GRACE-FO months 11 | - Can calculate the mean field of a ``spatial`` object 12 | - Can output ``spatial`` objects to ascii, netCDF4 or HDF5 files 13 | 14 | Calling Sequence 15 | ================ 16 | 17 | Reading a netCDF4 file 18 | 19 | .. code-block:: python 20 | 21 | from gravity_toolkit.spatial import spatial 22 | grid = spatial().from_netCDF4(path_to_netCDF4_file) 23 | 24 | Reading a HDF5 file 25 | 26 | .. code-block:: python 27 | 28 | from gravity_toolkit.spatial import spatial 29 | grid = spatial().from_HDF5(path_to_HDF5_file) 30 | 31 | Reading an index file of netCDF4 files and then outputting as a single file 32 | 33 | .. code-block:: python 34 | 35 | from gravity_toolkit.spatial import spatial 36 | grid = spatial().from_index(path_to_index_file,'netCDF4') 37 | grid.to_netCDF4(path_to_netCDF4_file) 38 | 39 | Reading an index file of HDF5 files and subsetting to specific months 40 | 41 | .. code-block:: python 42 | 43 | from gravity_toolkit.spatial import spatial 44 | grid = spatial().from_index(path_to_index_file,'HDF5').subset(months) 45 | 46 | Converting a dictionary object to a spatial object and removing the mean field 47 | 48 | .. code-block:: python 49 | 50 | from gravity_toolkit.spatial import spatial 51 | grid = spatial().from_dict(grid_dict) 52 | grid.mean(apply=True) 53 | 54 | 55 | `Source code`__ 56 | 57 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/spatial.py 58 | 59 | General Attributes and Methods 60 | ============================== 61 | 62 | .. autoclass:: gravity_toolkit.spatial 63 | :members: 64 | 65 | .. autoclass:: gravity_toolkit.scaling_factors 66 | :members: 67 | -------------------------------------------------------------------------------- /doc/source/api_reference/time.rst: -------------------------------------------------------------------------------- 1 | ==== 2 | time 3 | ==== 4 | 5 | Utilities for calculating time operations 6 | 7 | - Can convert delta time from seconds since an epoch to time since a different epoch 8 | - Can calculate the time in days since epoch from calendar dates 9 | 10 | Calling Sequence 11 | ================ 12 | 13 | Convert a time from seconds since 1980-01-06T00:00:00 to Modified Julian Days (MJD) 14 | 15 | .. code-block:: python 16 | 17 | import gravity_toolkit.time 18 | MJD = gravity_toolkit.time.convert_delta_time(delta_time, epoch1=(1980,1,6,0,0,0), 19 | epoch2=(1858,11,17,0,0,0), scale=1.0/86400.0) 20 | 21 | Convert from Julian Days into calendar dates 22 | 23 | .. code-block:: python 24 | 25 | import gravity_toolkit.time 26 | JD = MJD + 2400000.5 27 | YEAR,MONTH,DAY,HOUR,MINUTE,SECOND = gravity_toolkit.time.convert_julian(JD, 28 | format='tuple') 29 | 30 | Convert a calendar date into Modified Julian Days (MJD) 31 | 32 | .. code-block:: python 33 | 34 | import gravity_toolkit.time 35 | MJD = gravity_toolkit.time.convert_calendar_dates(YEAR,MONTH,DAY,hour=HOUR, 36 | minute=MINUTE,second=SECOND,epoch=(1858,11,17,0,0,0)) 37 | 38 | Convert a calendar date into decimal years 39 | 40 | .. code-block:: python 41 | 42 | import gravity_toolkit.time 43 | t_date = gravity_toolkit.time.convert_calendar_decimal(YEAR,MOMTH,day=DAY, 44 | hour=HOUR,minute=MINUTE,second=SECOND) 45 | 46 | `Source code`__ 47 | 48 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/time.py 49 | 50 | 51 | General Methods 52 | =============== 53 | 54 | .. autofunction:: gravity_toolkit.time.parse_date_string 55 | 56 | .. autofunction:: gravity_toolkit.time.split_date_string 57 | 58 | .. autofunction:: gravity_toolkit.time.datetime_to_list 59 | 60 | .. autofunction:: gravity_toolkit.time.parse_grace_file 61 | 62 | .. autofunction:: gravity_toolkit.time.parse_gfc_file 63 | 64 | .. autofunction:: gravity_toolkit.time.reduce_by_date 65 | 66 | .. autofunction:: gravity_toolkit.time.adjust_months 67 | 68 | .. autofunction:: gravity_toolkit.time.calendar_to_grace 69 | 70 | .. autofunction:: gravity_toolkit.time.grace_to_calendar 71 | 72 | .. autofunction:: gravity_toolkit.time.calendar_to_julian 73 | 74 | .. autofunction:: gravity_toolkit.time.calendar_days 75 | 76 | .. autofunction:: gravity_toolkit.time.convert_datetime 77 | 78 | .. autofunction:: gravity_toolkit.time.convert_delta_time 79 | 80 | .. autofunction:: gravity_toolkit.time.convert_calendar_dates 81 | 82 | .. autofunction:: gravity_toolkit.time.convert_calendar_decimal 83 | 84 | .. autofunction:: gravity_toolkit.time.convert_julian 85 | -------------------------------------------------------------------------------- /doc/source/api_reference/time_series/amplitude.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | time_series.amplitude 3 | ===================== 4 | 5 | - Calculate the amplitude and phase of a harmonic function from calculated sine and cosine of a series of measurements 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | import gravity_toolkit.time_series 13 | ampl,ph = gravity_toolkit.time_series.amplitude(bsin,bcos) 14 | 15 | `Source code`__ 16 | 17 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/time_series/amplitude.py 18 | 19 | .. autofunction:: gravity_toolkit.time_series.amplitude 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/time_series/fit.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | time_series.fit 3 | =============== 4 | 5 | - Utilities for fitting time-series data with regression models 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/time_series/fit.py 10 | 11 | .. autofunction:: gravity_toolkit.time_series.aliasing_terms 12 | -------------------------------------------------------------------------------- /doc/source/api_reference/time_series/lomb_scargle.rst: -------------------------------------------------------------------------------- 1 | ======================== 2 | time_series.lomb_scargle 3 | ======================== 4 | 5 | - Wrapper function for computing Lomb-Scargle periodograms using ``scipy.signal.lombscargle`` 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/time_series/lomb_scargle.py 10 | 11 | .. autofunction:: gravity_toolkit.time_series.lomb_scargle 12 | -------------------------------------------------------------------------------- /doc/source/api_reference/time_series/piecewise.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | time_series.piecewise 3 | ===================== 4 | 5 | - Fits a synthetic signal to data over a time period by ordinary or weighted least-squares for breakpoint analysis 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | import gravity_toolkit.time_series 13 | tsbeta = gravity_toolkit.time_series.piecewise(t_in, d_in, BREAKPOINT=len(t_in)//2, CYCLES=[0.5,1.0]) 14 | 15 | `Source code`__ 16 | 17 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/time_series/piecewise.py 18 | 19 | .. autofunction:: gravity_toolkit.time_series.piecewise 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/time_series/regress.rst: -------------------------------------------------------------------------------- 1 | =================== 2 | time_series.regress 3 | =================== 4 | 5 | - Fits a synthetic signal to data over a time period by ordinary or weighted least-squares 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | import gravity_toolkit.time_series 13 | tsbeta = gravity_toolkit.time_series.regress(t_in, d_in, ORDER=1, CYCLES=[0.5,1.0], CONF=0.95) 14 | 15 | `Source code`__ 16 | 17 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/time_series/regress.py 18 | 19 | .. autofunction:: gravity_toolkit.time_series.regress 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/time_series/savitzky_golay.rst: -------------------------------------------------------------------------------- 1 | ========================== 2 | time_series.savitzky_golay 3 | ========================== 4 | 5 | - Smooth and optionally differentiate data of non-uniform sampling with a Savitzky-Golay filter 6 | - A type of low-pass filter, particularly suited for smoothing noisy data 7 | - For each point makes a least-square fit of a polynomial over an odd-sized window centered at the point 8 | 9 | Calling Sequence 10 | ################ 11 | 12 | .. code-block:: python 13 | 14 | import gravity_toolkit.time_series 15 | sg = gravity_toolkit.time_series.savitzky_golay(t_in, d_in, WINDOW=13, ORDER=2) 16 | 17 | `Source code`__ 18 | 19 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/time_series/savitzky_golay.py 20 | 21 | .. autofunction:: gravity_toolkit.time_series.savitzky_golay 22 | -------------------------------------------------------------------------------- /doc/source/api_reference/time_series/smooth.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | time_series.smooth 3 | ================== 4 | 5 | - Computes the moving average of a time-series 6 | 7 | Calling Sequence 8 | ################ 9 | 10 | .. code-block:: python 11 | 12 | import gravity_toolkit.time_series 13 | smth = gravity_toolkit.time_series.smooth(t_in, d_in, HFWTH=6) 14 | 15 | `Source code`__ 16 | 17 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/time_series/smooth.py 18 | 19 | .. autofunction:: gravity_toolkit.time_series.smooth 20 | -------------------------------------------------------------------------------- /doc/source/api_reference/tools.rst: -------------------------------------------------------------------------------- 1 | ===== 2 | tools 3 | ===== 4 | 5 | `User interface `_ and plotting tools for use in `Jupyter notebooks `_ 6 | 7 | `Source code`__ 8 | 9 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/tools.py 10 | 11 | General Attributes and Methods 12 | ============================== 13 | 14 | .. autoclass:: gravity_toolkit.tools.widgets 15 | :members: 16 | 17 | .. autoclass:: gravity_toolkit.tools.colormap 18 | :members: 19 | 20 | .. autofunction:: gravity_toolkit.tools.from_cpt 21 | 22 | .. autofunction:: gravity_toolkit.tools.custom_colormap 23 | 24 | .. autofunction:: gravity_toolkit.tools.shift_grid 25 | 26 | .. autofunction:: gravity_toolkit.tools.interp_grid 27 | 28 | .. autofunction:: gravity_toolkit.tools.mask_oceans 29 | -------------------------------------------------------------------------------- /doc/source/api_reference/units.rst: -------------------------------------------------------------------------------- 1 | ===== 2 | units 3 | ===== 4 | 5 | Class for converting GRACE/GRACE-FO Level-2 data to specific units 6 | 7 | Calling Sequence 8 | ================ 9 | 10 | Calculating the degree dependent factors for converting harmonic units 11 | 12 | .. code-block:: python 13 | 14 | from gravity_toolkit.units import units 15 | from gravity_toolkit.read_love_numbers import read_love_numbers 16 | hl,kl,ll = read_love_numbers(love_numbers_file, REFERENCE='CF') 17 | dfactor = units(lmax=lmax).harmonic(hl,kl,ll) 18 | to_cmwe = dfactor.cmwe 19 | 20 | Calculating the degree dependent factors for converting spatial units 21 | 22 | .. code-block:: python 23 | 24 | from gravity_toolkit.units import units 25 | from gravity_toolkit.read_love_numbers import read_love_numbers 26 | hl,kl,ll = read_love_numbers(love_numbers_file, REFERENCE='CF') 27 | dfactor = units(lmax=lmax).spatial(hl,kl,ll) 28 | from_cmwe = dfactor.cmwe 29 | 30 | `Source code`__ 31 | 32 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/units.py 33 | 34 | General Attributes and Methods 35 | ============================== 36 | 37 | .. autoclass:: gravity_toolkit.units 38 | :members: 39 | 40 | -------------------------------------------------------------------------------- /doc/source/api_reference/utilities.rst: -------------------------------------------------------------------------------- 1 | ========= 2 | utilities 3 | ========= 4 | 5 | Download and management utilities for syncing time and auxiliary files 6 | 7 | - Can list a directory on a ftp host 8 | - Can download a file from a ftp or http host 9 | - Can download a file from PO.DAAC via https when WebDAV credentials are supplied 10 | - Checks ``MD5`` or ``sha1`` hashes between local and remote files 11 | 12 | `Source code`__ 13 | 14 | .. __: https://github.com/tsutterley/gravity-toolkit/blob/main/gravity_toolkit/utilities.py 15 | 16 | 17 | General Methods 18 | =============== 19 | 20 | .. autofunction:: gravity_toolkit.utilities.get_data_path 21 | 22 | .. autoclass:: gravity_toolkit.utilities.reify 23 | :members: 24 | 25 | .. autofunction:: gravity_toolkit.utilities.get_hash 26 | 27 | .. autofunction:: gravity_toolkit.utilities.get_git_revision_hash 28 | 29 | .. autofunction:: gravity_toolkit.utilities.get_git_status 30 | 31 | .. autofunction:: gravity_toolkit.utilities.url_split 32 | 33 | .. autofunction:: gravity_toolkit.utilities.convert_arg_line_to_args 34 | 35 | .. autofunction:: gravity_toolkit.utilities.get_unix_time 36 | 37 | .. autofunction:: gravity_toolkit.utilities.isoformat 38 | 39 | .. autofunction:: gravity_toolkit.utilities.even 40 | 41 | .. autofunction:: gravity_toolkit.utilities.ceil 42 | 43 | .. autofunction:: gravity_toolkit.utilities.copy 44 | 45 | .. autofunction:: gravity_toolkit.utilities.create_unique_file 46 | 47 | .. autofunction:: gravity_toolkit.utilities.check_ftp_connection 48 | 49 | .. autofunction:: gravity_toolkit.utilities.ftp_list 50 | 51 | .. autofunction:: gravity_toolkit.utilities.from_ftp 52 | 53 | .. autofunction:: gravity_toolkit.utilities._create_default_ssl_context 54 | 55 | .. autofunction:: gravity_toolkit.utilities._create_ssl_context_no_verify 56 | 57 | .. autofunction:: gravity_toolkit.utilities._set_ssl_context_options 58 | 59 | .. autofunction:: gravity_toolkit.utilities.check_connection 60 | 61 | .. autofunction:: gravity_toolkit.utilities.http_list 62 | 63 | .. autofunction:: gravity_toolkit.utilities.from_http 64 | 65 | .. autofunction:: gravity_toolkit.utilities.from_json 66 | 67 | .. autofunction:: gravity_toolkit.utilities.attempt_login 68 | 69 | .. autofunction:: gravity_toolkit.utilities.build_opener 70 | 71 | .. autofunction:: gravity_toolkit.utilities.get_token 72 | 73 | .. autofunction:: gravity_toolkit.utilities.list_tokens 74 | 75 | .. autofunction:: gravity_toolkit.utilities.revoke_token 76 | 77 | .. autofunction:: gravity_toolkit.utilities.s3_client 78 | 79 | .. autofunction:: gravity_toolkit.utilities.s3_bucket 80 | 81 | .. autofunction:: gravity_toolkit.utilities.s3_key 82 | 83 | .. autofunction:: gravity_toolkit.utilities.check_credentials 84 | 85 | .. autofunction:: gravity_toolkit.utilities.drive_list 86 | 87 | .. autofunction:: gravity_toolkit.utilities.from_drive 88 | 89 | .. autofunction:: gravity_toolkit.utilities.cmr_product_shortname 90 | 91 | .. autofunction:: gravity_toolkit.utilities.cmr_readable_granules 92 | 93 | .. autofunction:: gravity_toolkit.utilities.cmr_filter_json 94 | 95 | .. autofunction:: gravity_toolkit.utilities.cmr_metadata_json 96 | 97 | .. autofunction:: gravity_toolkit.utilities.cmr 98 | 99 | .. autofunction:: gravity_toolkit.utilities.cmr_metadata 100 | 101 | .. autofunction:: gravity_toolkit.utilities.compile_regex_pattern 102 | 103 | .. autofunction:: gravity_toolkit.utilities.from_figshare 104 | 105 | .. autofunction:: gravity_toolkit.utilities.to_figshare 106 | 107 | .. autofunction:: gravity_toolkit.utilities.from_csr 108 | 109 | .. autofunction:: gravity_toolkit.utilities.from_gsfc 110 | 111 | .. autofunction:: gravity_toolkit.utilities.from_gfz 112 | 113 | .. autofunction:: gravity_toolkit.utilities.icgem_list 114 | -------------------------------------------------------------------------------- /doc/source/conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # This file only contains a selection of the most common options. For a full 4 | # list see the documentation: 5 | # https://www.sphinx-doc.org/en/master/usage/configuration.html 6 | 7 | # -- Path setup -------------------------------------------------------------- 8 | 9 | # If extensions (or modules to document with autodoc) are in another directory, 10 | # add these directories to sys.path here. If the directory is relative to the 11 | # documentation root, use os.path.abspath to make it absolute, like shown here. 12 | # 13 | import os 14 | # import sys 15 | import datetime 16 | # sys.path.insert(0, os.path.abspath('.')) 17 | import importlib.metadata 18 | 19 | 20 | # -- Project information ----------------------------------------------------- 21 | 22 | # package metadata 23 | metadata = importlib.metadata.metadata("gravity-toolkit") 24 | project = metadata["Name"] 25 | year = datetime.date.today().year 26 | copyright = f"2019\u2013{year}, Tyler C. Sutterley" 27 | author = 'Tyler C. Sutterley' 28 | 29 | # The full version, including alpha/beta/rc tags 30 | version = metadata["version"] 31 | # append "v" before the version 32 | release = f"v{version}" 33 | 34 | # -- General configuration --------------------------------------------------- 35 | 36 | # Add any Sphinx extension module names here, as strings. They can be 37 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 38 | # ones. 39 | extensions = [ 40 | "numpydoc", 41 | 'sphinxcontrib.bibtex', 42 | "sphinx.ext.autodoc", 43 | "sphinx.ext.graphviz", 44 | "sphinx.ext.viewcode", 45 | "sphinxarg.ext" 46 | ] 47 | 48 | # Add any paths that contain templates here, relative to this directory. 49 | templates_path = ['_templates'] 50 | 51 | # List of patterns, relative to source directory, that match files and 52 | # directories to ignore when looking for source files. 53 | # This pattern also affects html_static_path and html_extra_path. 54 | exclude_patterns = ['**.ipynb_checkpoints'] 55 | 56 | # location of master document (by default sphinx looks for contents.rst) 57 | master_doc = 'index' 58 | 59 | # -- Configuration options --------------------------------------------------- 60 | autosummary_generate = True 61 | autodoc_member_order = 'bysource' 62 | numpydoc_show_class_members = False 63 | pygments_style = 'native' 64 | bibtex_bibfiles = ['_assets/gravity-refs.bib'] 65 | bibtex_default_style = 'plain' 66 | 67 | # -- Options for HTML output ------------------------------------------------- 68 | 69 | # html_title = "gravity-toolkit" 70 | html_short_title = "gravity-toolkit" 71 | html_show_sourcelink = False 72 | html_show_sphinx = True 73 | html_show_copyright = True 74 | 75 | # The theme to use for HTML and HTML Help pages. See the documentation for 76 | # a list of builtin themes. 77 | # 78 | html_theme = 'sphinx_rtd_theme' 79 | html_theme_options = {} 80 | 81 | # Add any paths that contain custom static files (such as style sheets) here, 82 | # relative to this directory. They are copied after the builtin static files, 83 | # so a file named "default.css" will overwrite the builtin "default.css". 84 | html_static_path = ['_static'] 85 | repository_url = f"https://github.com/tsutterley/gravity-toolkit" 86 | html_context = { 87 | "menu_links": [ 88 | ( 89 | ' Source Code', 90 | repository_url, 91 | ), 92 | ( 93 | ' License', 94 | f"{repository_url}/blob/main/LICENSE", 95 | ), 96 | ], 97 | } 98 | 99 | # Load the custom CSS files (needs sphinx >= 1.6 for this to work) 100 | def setup(app): 101 | app.add_css_file("style.css") 102 | -------------------------------------------------------------------------------- /doc/source/getting_started/Bibliography.rst: -------------------------------------------------------------------------------- 1 | ============ 2 | Bibliography 3 | ============ 4 | 5 | .. bibliography:: 6 | -------------------------------------------------------------------------------- /doc/source/getting_started/Citations.rst: -------------------------------------------------------------------------------- 1 | ==================== 2 | Citation Information 3 | ==================== 4 | 5 | References 6 | ########## 7 | 8 | The programs included in this software have contributed 9 | most recently to the following work: 10 | 11 | I. Velicogna, Y. Mohajerani, G. A, F. Landerer, J. Mouginot, B. No\ |euml|\ l, 12 | E. Rignot, T. C. Sutterley, M. van den Broeke, J. M. van Wessem, and D. Wiese, 13 | "Continuity of ice sheet mass loss in Greenland and Antarctica from the GRACE 14 | and GRACE Follow-On missions", *Geophysical Research Letters*, 47, 15 | (2020). `doi: 10.1029/2020GL087291 `_ 16 | 17 | T. C. Sutterley, I. Velicogna, and C.-W. Hsu, "Self-Consistent Ice Mass Balance 18 | and Regional Sea Level From Time-Variable Gravity", *Earth and Space Science*, 7, 19 | (2020). `doi: 10.1029/2019EA000860 `_ 20 | 21 | T. C. Sutterley and I. Velicogna, "Improved estimates of geocenter variability 22 | from time-variable gravity and ocean model outputs", *Remote Sensing*, 11(18), 23 | 2108, (2019). `doi: 10.3390/rs11182108 `_ 24 | 25 | Some of the text within this documentation are modifications from these 26 | original works, which is allowed under the 27 | `publisher's permissions policies for authors `_ 28 | or through the `Creative Commons licensing `_ of the work. 29 | 30 | If you have used ``gravity-toolkit`` in your work, please consider citing our library: 31 | 32 | T. C. Sutterley, et al., "gravity-toolkit: Python tools for obtaining and 33 | working with data from the GRACE and GRACE Follow-On missions", (2020). 34 | `doi: 10.5281/zenodo.5156864 `_ 35 | 36 | Contributors 37 | ############ 38 | 39 | .. include:: ../../../CONTRIBUTORS.rst 40 | 41 | Development 42 | ########### 43 | This is an open source project. 44 | We welcome any help in maintaining and developing the software and documentation. 45 | Anyone at any career stage and with any level of coding experience can contribute. 46 | Please see the `Contribution Guidelines <./Contributing.html>`_ for more information. 47 | 48 | Problem Reports 49 | ############### 50 | If you have found a problem in these programs, or you would like to suggest 51 | an improvement or modification, please submit a 52 | `GitHub issue `_ 53 | and we will get back to you. 54 | 55 | Dependencies 56 | ############ 57 | This software is also dependent on other commonly used Python packages: 58 | 59 | - `cartopy: Python package designed for geospatial data processing `_ 60 | - `future: Compatibility layer between Python 2 and Python 3 `_ 61 | - `h5py: Python interface for Hierarchal Data Format 5 (HDF5) `_ 62 | - `ipywidgets: interactive HTML widgets for Jupyter notebooks and IPython `_ 63 | - `lxml: processing XML and HTML in Python `_ 64 | - `matplotlib: Python 2D plotting library `_ 65 | - `netCDF4: Python interface to the netCDF C library `_ 66 | - `numpy: Scientific Computing Tools For Python `_ 67 | - `python-dateutil: powerful extensions to datetime `_ 68 | - `PyYAML: YAML parser and emitter for Python `_ 69 | - `scipy: Scientific Tools for Python `_ 70 | - `tkinter: Python interface to the Tcl/Tk GUI toolkit `_ 71 | 72 | Disclaimer 73 | ########## 74 | This program is not sponsored or maintained by the Universities Space Research Association (USRA), 75 | the Center for Space Research at the University of Texas (UTCSR), 76 | the Jet Propulsion Laboratory (JPL), 77 | the German Research Centre for Geosciences (GeoForschungsZentrum, GFZ) or NASA. 78 | It is provided here for your convenience but *with no guarantees whatsoever*. 79 | 80 | This product includes software developed at: 81 | 82 | - University of California, Irvine, Department of Earth System Science 83 | - Jet Propulsion Laboratory, California Institute of Technology 84 | - National Aeronautics and Space Administration, Goddard Space Flight Center 85 | - University of Washington, Applied Physics Laboratory, Polar Science Center 86 | 87 | Acknowledgements 88 | ################ 89 | Much of this software stems from the work of the late `John Wahr (1951--2015) `_, 90 | who made immeasurable contributions towards time-variable gravity research and was an inspiration. 91 | 92 | .. |euml| unicode:: U+00EB .. LATIN SMALL LETTER E WITH DIAERESIS 93 | -------------------------------------------------------------------------------- /doc/source/getting_started/Contributing.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | Contribution Guidelines 3 | ======================= 4 | 5 | We welcome and invite contributions from anyone at any career stage and with any amount of coding experience towards the development of ``gravity-toolkit``. 6 | We appreciate any and all contributions made to the project. 7 | You will be recognized for your work by being listed as one of the `project contributors <./Citations.html#contributors>`_. 8 | 9 | Ways to Contribute 10 | ------------------ 11 | 12 | 1) Fixing typographical or coding errors 13 | 2) Submitting bug reports or feature requests through the use of `GitHub issues `_ 14 | 3) Improving documentation and testing 15 | 4) Sharing use cases and examples (such as `Jupyter Notebooks <../user_guide/Examples.html>`_) 16 | 5) Providing code for everyone to use 17 | 18 | Requesting a Feature 19 | -------------------- 20 | Check the `project issues tab `_ to see if the feature has already been suggested. 21 | If not, please submit a new issue describing your requested feature or enhancement . 22 | Please give your feature request both a clear title and description. 23 | Let us know if this is something you would like to contribute to ``gravity-toolkit`` in your description as well. 24 | 25 | Reporting a Bug 26 | --------------- 27 | Check the `project issues tab `_ to see if the problem has already been reported. 28 | If not, *please* submit a new issue so that we are made aware of the problem. 29 | Please provide as much detail as possible when writing the description of your bug report. 30 | Providing information and examples will help us resolve issues faster. 31 | 32 | Contributing Code or Examples 33 | ----------------------------- 34 | We follow a standard Forking Workflow for code changes and additions. 35 | Submitted code goes through the pull request process for `continuous integration (CI) testing <./Contributing.html#continuous-integration>`_ and comments. 36 | 37 | General Guidelines 38 | ^^^^^^^^^^^^^^^^^^ 39 | 40 | - Make each pull request as small and simple as possible 41 | - `Commit messages should be clear and describe the changes <./Contributing.html#semantic-commit-messages>`_ 42 | - Larger changes should be broken down into their basic components and integrated separately 43 | - Bug fixes should be their own pull requests with an associated `GitHub issue `_ 44 | - Write a descriptive pull request message with a clear title 45 | - Be patient as reviews of pull requests take time 46 | 47 | Steps to Contribute 48 | ^^^^^^^^^^^^^^^^^^^ 49 | 50 | 1) Fork the repository to your personal GitHub account by clicking the "Fork" button on the project `main page `_. This creates your own server-side copy of the repository. 51 | 2) Either by cloning to your local system or working in `GitHub Codespaces `_, create a work environment to make your changes. 52 | 3) Add your fork as the ``origin`` remote and the original project repository as the ``upstream`` remote. While this step isn't a necessary, it allows you to keep your fork up to date in the future. 53 | 4) Create a new branch to do your work. 54 | 5) Make your changes on the new branch and add yourself to the list of project `contributors `_. 55 | 6) Push your work to GitHub under your fork of the project. 56 | 7) Submit a `Pull Request `_ from your forked branch to the project repository. 57 | 58 | Adding Examples 59 | ^^^^^^^^^^^^^^^ 60 | Examples may be in the form of executable scripts or interactive `Jupyter Notebooks <../user_guide/Examples.html>`_. 61 | Fully working (but unrendered) examples should be submitted with the same steps as above. 62 | 63 | Continuous Integration 64 | ^^^^^^^^^^^^^^^^^^^^^^ 65 | We use `GitHub Actions `_ continuous integration (CI) services to build and test the project on Linux (Ubuntu) and Mac Operating Systems. 66 | The configuration files for this service are in `.github/workflows `_. 67 | The workflows rely on the `environment.yml `_ and test `requirements.txt `_ files to install the required dependencies. 68 | 69 | The GitHub Actions jobs include: 70 | 71 | * Running `flake8 `_ to check the code for style and compilation errors 72 | * Running the test suite on multiple combinations of OS and Python version 73 | 74 | Semantic Commit Messages 75 | ^^^^^^^^^^^^^^^^^^^^^^^^ 76 | 77 | Commit messages should follow the `Conventional Commits `_ specification: 78 | 79 | .. code-block:: bash 80 | 81 | : 82 | 83 | [optional message body] 84 | 85 | where ```` is one of the following: 86 | 87 | - ``feat``: adding new features or programs 88 | - ``fix``: fixing bugs or problems 89 | - ``docs``: changing the documentation 90 | - ``style``: changing the line order or adding comments 91 | - ``refactor``: changing the names of variables or programs 92 | - ``ci``: changing the `continuous integration <./Contributing.html#continuous-integration>`_ configuration files or scripts 93 | - ``test``: adding or updating `continuous integration tests <./Contributing.html#continuous-integration>`_ 94 | -------------------------------------------------------------------------------- /doc/source/getting_started/Geocenter-Variations.rst: -------------------------------------------------------------------------------- 1 | ==================== 2 | Geocenter Variations 3 | ==================== 4 | 5 | Variations in the Earth's geocenter reflect the largest scale 6 | variability of mass within the Earth system, and are essential 7 | inclusions for the complete recovery of surface mass change from 8 | time-variable gravity. 9 | The Earth's geocenter is the translation between the Earth's 10 | center of mass (CM) and center of figure (CF) reference frames. 11 | Measurements of time-variable gravity from GRACE and GRACE Follow-On 12 | (GRACE-FO) are set in an instantaneous center of mass (CM) reference frame. 13 | For most science applications of time-variable gravity, a coordinate 14 | system with an origin coinciding with the Earth's center of figure 15 | (CF) is required. 16 | Geocenter variations are represented by the degree one spherical harmonic terms. 17 | The exclusion of degree one terms can have a significant impact on estimates 18 | of ocean mass, ice sheet mass change, and terrestrial hydrology due to 19 | far-field signals leaking into each regional estimate :cite:p:`Velicogna:2009ft`. 20 | 21 | ``calc_degree_one.py`` calculates coefficients of degree one by combining 22 | GRACE/GRACE-FO spherical harmonic products with estimates of 23 | ocean bottom pressure (OBP) following :cite:t:`Swenson:2008cr,Sutterley:2019bx`. 24 | The method assumes that the change in global surface mass density, 25 | :math:`\Delta\sigma(\theta,\phi)`, can be separated into individual 26 | land and ocean components using a land-function 27 | :math:`\vartheta(\theta,\phi)` :cite:p:`Swenson:2008cr`. 28 | 29 | .. math:: 30 | :label: 4 31 | 32 | \Delta\sigma(\theta,\phi) &= \Delta\sigma_{land}(\theta,\phi) + \Delta\sigma_{ocean}(\theta,\phi)\\ 33 | \Delta\sigma_{ocean}(\theta,\phi) &= \vartheta(\theta,\phi)~\Delta\sigma(\theta,\phi) 34 | 35 | The oceanic components of the change in degree one spherical harmonics 36 | (:math:`\Delta C^{ocean}_{10}`, :math:`\Delta C^{ocean}_{11}`, and :math:`\Delta S^{ocean}_{11}`) 37 | can then be calculated from the changes in ocean mass, 38 | :math:`\Delta\sigma_{ocean}(\theta,\phi),Swenson:2008cr,Wahr:1998hy`. 39 | If the oceanic contributions to degree one variability 40 | (:math:`\Delta C^{ocean}_{10}`, :math:`\Delta C^{ocean}_{11}`, and :math:`\Delta S^{ocean}_{11}`) 41 | can be estimated from an ocean model, then the unknown complete degree one terms 42 | (:math:`\Delta C_{10}`, :math:`\Delta C_{11}`, and :math:`\Delta S_{11}`) can be 43 | calculated from the residual between the oceanic degree one terms and the 44 | measured mass change over the ocean calculated using all other degrees of 45 | the global spherical harmonics from GRACE/GRACE-FO :cite:p:`Swenson:2008cr,Sutterley:2019bx`. 46 | 47 | The ``calc_degree_one.py`` program will output geocenter files in ascii format 48 | for each GRACE/GRACE-FO month following :cite:t:`Sutterley:2019bx`. 49 | Uncertainties in geocenter due to a combination of error sources can be 50 | estimated using the ``monte_carlo_degree_one.py`` program. 51 | 52 | Load Love Numbers 53 | ################# 54 | 55 | The degree one Love number of gravitational potential :math:`k_1` is defined so 56 | that the degree one terms describe the offset between the center of mass (CM) 57 | of the combined surface mass and deformed solid Earth, and the center of figure (CF) 58 | of the deformed solid Earth surface :cite:p:`Trupin:1992kp,Blewitt:2003bz`. 59 | For the CF coordinate system, this means 60 | 61 | .. math:: 62 | :label: 5 63 | 64 | k_1 = -(h_1 + 2\ell_1)/3 65 | 66 | where :math:`h_1` and :math:`\ell_1` are the degree one vertical and 67 | horizontal displacement Love numbers. 68 | 69 | Geocenter and Degree One 70 | ######################## 71 | 72 | Fully-normalized degree one variations can be converted to 73 | cartesian geocenter variations using the following relation: 74 | 75 | .. math:: 76 | :label: 6 77 | 78 | \Delta X &= a\sqrt{3}~\Delta C_{11} \\ 79 | \Delta Y &= a\sqrt{3}~\Delta S_{11} \\ 80 | \Delta Z &= a\sqrt{3}~\Delta C_{10} 81 | 82 | 83 | The ``geocenter`` class has utilities for converting between 84 | spherical harmonics and geocenter variation along with 85 | readers for different geocenter datasets. 86 | -------------------------------------------------------------------------------- /doc/source/getting_started/Getting-Started.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | Getting Started 3 | =============== 4 | 5 | - `Register at NASA Earthdata <./NASA-Earthdata.rst>`_ 6 | - Run `podaac_cumulus.py `_ program with your NASA Earthdata credentials to acquire GRACE/GRACE-FO and auxiliary data 7 | 8 | .. code-block:: bash 9 | 10 | python podaac_cumulus.py --user= --directory= --release RL06 11 | 12 | - Run `cnes_grace_sync.py `_ program to acquire CNES/GRGS GRACE/GRACE-FO data 13 | 14 | .. code-block:: bash 15 | 16 | python cnes_grace_sync.py --directory= --release RL05 17 | 18 | - Get geocenter results from `Sutterley and Velicogna (2019) `_ if wanting to use that dataset 19 | 20 | .. code-block:: python 21 | 22 | import gravity_toolkit.utilities 23 | gravity_toolkit.utilities.from_figshare(path_to_grace_directory,verbose=True) 24 | 25 | - If correcting for Glacial Isostatic Adjustment: have full path to data file known 26 | 27 | * These can be ascii files direct from many modeling groups or a reformatted ascii/netCDF4/HDF5 file 28 | 29 | - If correcting for other geophysical processes such as terrestrial water storage: have full path known 30 | 31 | * These can be a single netCDF4 or HDF5 file or an index of ascii/netCDF4/HDF5 files 32 | 33 | - Run Jupyter notebook `GRACE-Spatial-Maps.ipynb `_ to create monthly maps 34 | 35 | * This program uses `Jupyter widgets `_ to select `datasets <./GRACE-Data-File-Formats.html>`_ and processing parameters 36 | * Can also sync the data from within the Jupyter Notebook using `magics `_ 37 | * Can output monthly spatial maps to netCDF4 or HDF5 in specified units 38 | * Will create an animation of the GRACE/GRACE-FO monthly data in the specified units 39 | -------------------------------------------------------------------------------- /doc/source/getting_started/Install.rst: -------------------------------------------------------------------------------- 1 | ============ 2 | Installation 3 | ============ 4 | 5 | ``gravity-toolkit`` is available for download from the `GitHub repository `_, 6 | and the `Python Package Index (pypi) `_, 7 | The contents of the repository can be downloaded as a `zipped file `_ or cloned. 8 | 9 | To use this repository, please fork into your own account and then clone onto your system: 10 | 11 | .. code-block:: bash 12 | 13 | git clone https://github.com/tsutterley/gravity-toolkit.git 14 | 15 | Can then install using ``setuptools``: 16 | 17 | .. code-block:: bash 18 | 19 | python3 setup.py install 20 | 21 | or ``pip`` 22 | 23 | .. code-block:: bash 24 | 25 | python3 -m pip install --user . 26 | 27 | Alternatively can install the ``gravity_toolkit`` utilities directly from GitHub with ``pip``: 28 | 29 | .. code-block:: bash 30 | 31 | python3 -m pip install --user git+https://github.com/tsutterley/gravity-toolkit.git 32 | -------------------------------------------------------------------------------- /doc/source/getting_started/NASA-Earthdata.rst: -------------------------------------------------------------------------------- 1 | ============== 2 | NASA Earthdata 3 | ============== 4 | 5 | NASA Data Distribution Centers 6 | ############################## 7 | 8 | The NASA Earth Science Data Information Systems Project funds and operates 9 | `12 Distributed Active Archive Centers (DAACs) `_ throughout the United States. 10 | These centers have recently transitioned from ftp to https servers. 11 | The https updates are designed to increase performance and improve security during data retrieval. 12 | NASA Earthdata uses `OAuth2 `_, an approach to authentication that protects your personal information. 13 | 14 | - https://urs.earthdata.nasa.gov/documentation 15 | - https://wiki.earthdata.nasa.gov/display/EL/Knowledge+Base 16 | 17 | PO.DAAC 18 | ####### 19 | The `Physical Oceanography Distributed Active Archive Center (PO.DAAC) `_ 20 | provides data and related information pertaining to the physical processes and conditions of the global oceans, 21 | including measurements of ocean winds, temperature, topography, salinity, circulation and currents, and sea ice. 22 | PO.DAAC hosts 23 | 24 | PO.DAAC is `migrating its data archive to the Earthdata Cloud `_, 25 | which is hosted in Amazon Web Services (AWS). 26 | GRACE/GRACE-FO spherical harmonic data is currently scheduled to be "cloud enabled" 27 | during Phase 4 and Phase 5 of the transition, slated for April and July 2022 respectively. 28 | 29 | If any problems contact JPL PO.DAAC support at `podaac@podaac.jpl.nasa.gov `_ 30 | or the NASA EOSDIS support team `support@earthdata.nasa.gov `_. 31 | 32 | Steps to Sync from PO.DAAC 33 | -------------------------- 34 | 35 | 1. `Register with NASA Earthdata Login system `_ 36 | 2. `Sync time-variable gravity data using your Earthdata credentials `_ 37 | 38 | Can also create a ``.netrc`` file for permanently storing NASA Earthdata credentials: 39 | 40 | .. code-block:: bash 41 | 42 | echo "machine urs.earthdata.nasa.gov login password " >> ~/.netrc 43 | chmod 0600 ~/.netrc 44 | 45 | Or set environmental variables for your NASA Earthdata credentials: 46 | 47 | .. code-block:: bash 48 | 49 | export EARTHDATA_USERNAME= 50 | export EARTHDATA_PASSWORD= 51 | 52 | NASA Common Metadata Repository 53 | ############################### 54 | 55 | The NASA Common Metadata Repository (CMR) is a catalog of all data 56 | and service metadata records contained as part of NASA's Earth 57 | Observing System Data and Information System (EOSDIS). 58 | Querying the CMR system is a way of quickly performing a search 59 | through the NASA Earthdata archive. 60 | Basic queries for the granule names, PO.DAAC URLs and modification times 61 | of GRACE/GRACE-FO data are available through the ``cmr`` routine in the 62 | ``utilities`` module. 63 | For AWS instances in ``us-west-2``, CMR queries can access urls for S3 endpoints. 64 | 65 | .. code-block:: python 66 | 67 | ids,urls,mtimes = gravity_toolkit.utilities.cmr(mission='grace-fo', 68 | center='JPL', release='RL06', level='L2', product='GSM', 69 | solution='BA01', provider='POCLOUD', endpoint='s3', verbose=False) 70 | 71 | Other Data Access Examples 72 | ########################## 73 | - `Curl and Wget `_ 74 | - `Python `_ 75 | -------------------------------------------------------------------------------- /doc/source/getting_started/Resources.rst: -------------------------------------------------------------------------------- 1 | ========= 2 | Resources 3 | ========= 4 | 5 | Mission Information 6 | ################### 7 | 8 | - `NASA GRACE mission site `_ 9 | - `NASA GRACE-FO mission site `_ 10 | - `JPL GRACE Tellus site `_ 11 | - `JPL GRACE-FO site `_ 12 | - `UTCSR GRACE site `_ 13 | - `GFZ GRACE mission site `_ 14 | - `NASA GSFC GRACE site `_ 15 | - `CNES/GRGS GRACE and LAGEOS site `_ 16 | 17 | Data Archives 18 | ############# 19 | 20 | - `GRACE at the NASA Physical Oceanography Distributed Active Archive Center (PO.DAAC) `_ 21 | - `GRACE at the GFZ Information System and Data Center `_ 22 | - `Combined GRACE/SLR solutions at CNES/GRGS `_ 23 | - `GFZ International Centre for Global Earth Models (ICGEM) `_ 24 | 25 | Product Information 26 | ################### 27 | 28 | - `GRACE Level-2 Gravity Field Product User Handbook `_ 29 | - `GRACE-FO Level-2 Gravity Field Product User Handbook `_ 30 | - `GRACE Product Description Document for AOD1B Release 06 `_ 31 | 32 | Processing Standards 33 | #################### 34 | - `GRACE-FO CSR Level-2 Processing Standards Document `_ 35 | - `GRACE-FO GFZ Level-2 Processing Standards Document `_ 36 | - `GRACE-FO JPL Level-2 Processing Standards Document `_ 37 | 38 | Software 39 | ######## 40 | 41 | - `podaacpy: python utility library for interacting with NASA JPL's PO.DAAC `_ 42 | - `NASA PO.DAAC Tools and Services `_ 43 | - `GRACE_Tiles: GRACE gravity field inversion package `_ 44 | - `frommle: python/C++ software suite for geodesy and Earth Sciences `_ 45 | - `geoid-toolkit: python utilities for calculating geoid heights from static gravity field coefficients `_ 46 | - `model-harmonics: python tools for working with model synthetic spherical harmonic coefficients `_ 47 | - `dynamic_mascons: 3D global variable-size mascon development `_ -------------------------------------------------------------------------------- /doc/source/getting_started/Time-Series-Analysis.rst: -------------------------------------------------------------------------------- 1 | ==================== 2 | Time Series Analysis 3 | ==================== 4 | 5 | Least-squares mascons are a method of extracting a regional signal from the 6 | GRACE/GRACE-FO spherical harmonic data. 7 | The procedure was outlined in procedure outlined in 8 | :cite:p:`Tiwari:2009bx` and :cite:p:`Jacob:2012gv`. 9 | Least-squares mascons can be considered a post-processing technique for 10 | analyzing the GRACE/GRACE-FO data. 11 | The technique calculates the scaling factor between an input kernel and the 12 | GRACE/GRACE-FO data for a given month. 13 | In an ideal case, the input kernel is a spatially discrete, uniformly 14 | distributed layer of equivalent water height at colatitudes 15 | :math:`\theta` and longitudes :math:`\phi` :cite:p:`Rowlands:2010hj`. 16 | 17 | .. math:: 18 | :label: 3 19 | 20 | k(\theta,\phi) = 21 | \begin{cases} 22 | ~1~\text{cm w.e.} & \text{if}~(\theta,\phi)~\text{is in region}\\ 23 | ~0 & \text{if}~(\theta,\phi)~\text{is not in region} 24 | \end{cases} 25 | 26 | GRACE/GRACE-FO measurements over the region at any given time would be a 27 | scalar multiple of this uniform layer. 28 | For example, for a uniform kernel equivalent to 1 cm w.e., 29 | if GRACE/GRACE-FO measures 6 cm w.e. in the region, then the scaling factor would be 6. 30 | However, the GRACE/GRACE-FO harmonic solutions are truncated and typically smoothed, 31 | meaning that the sharp 0-to-1 transitions along regional boundaries cannot be 32 | resolved at the inherent GRACE/GRACE-FO resolution :cite:p:`Wahr:1998hy`. 33 | The mascon kernels are instead represented as sets of truncated spherical 34 | harmonics processed in the same manner as the GRACE/GRACE-FO data :cite:p:`Jacob:2012gv`. 35 | In this case, each mascon kernel is a smoothed function with a total 36 | mass equal to the idealized case. 37 | 38 | Ideally, the final solution for the recovered mascon mass, is equal 39 | to the true spatial average across the mascon :cite:p:`Jacob:2012gv`. 40 | Misfits in the regression or malformed initial kernels can lead to 41 | the leakage of GRACE/GRACE-FO signal in-between mascons or out of the system. 42 | The least squares mascon technique assumes that the GRACE/GRACE-FO signal are 43 | well represented as scalar multiples of the mascons at any given time. 44 | As the initial mascon parameters are designed with uniform mass distributions, 45 | the GRACE/GRACE-FO anomalies over each mascon must also be uniform to limit 46 | statistical misfit :cite:p:`Jacob:2012gv`. 47 | 48 | Hypothetically, we would want as small of kernels as possible to get as 49 | geophysically relevant as possible (perfect fit to region shape). 50 | However, GRACE/GRACE-FO data is limited to a specific spherical harmonic range 51 | with noise increasing with higher degree and order (data-to-noise ratio decreases). 52 | If the kernels are too small, there will be a higher degree of ringing when 53 | truncated (Gibbs phenomenon) and require more information at the higher degrees 54 | and orders to distinguish from the adjacent kernels. 55 | Thus there is a balance between wanting kernels as geophysically relevant as 56 | possible with wanting idealistic kernels which minimize ringing and are resolvable. 57 | Getting the kernels "just right" in order to isolate regions of interest takes some time. 58 | 59 | The set of least-squares mascon programs have been used in :cite:p:`Velicogna:2014km` 60 | and other publications for regional time series analysis. 61 | The ``calc_mascon.py`` program additionally calculates the GRACE/GRACE-FO error 62 | harmonics following :cite:t:`Wahr:2006bx`. 63 | 64 | The ``calc_mascon.py`` program will output a text file of the time series for each mascon 65 | (format: GRACE/GRACE-FO month, mid-month date in decimal-year format, 66 | estimated monthly mass anomaly [Gt], estimated monthly error [Gt], 67 | mascon area [km\ :sup:`2`]). 68 | -------------------------------------------------------------------------------- /doc/source/user_guide/Examples.rst: -------------------------------------------------------------------------------- 1 | .. _examples: 2 | 3 | ======== 4 | Examples 5 | ======== 6 | 7 | Jupyter Notebooks providing demonstrations of the functionality within ``gravity-toolkit``: 8 | 9 | - Creating Spatial Maps |github spatial| |nbviewer spatial| 10 | Creates an animation of spatial maps using data derived from the monthly GRACE/GRACE-FO Level-2 spherical harmonic product 11 | - Creating Spatial Error Maps |github error| |nbviewer error| 12 | Creates spatial maps of estimated GRACE/GRACE-FO errors derived from the monthly Level-2 spherical harmonic product 13 | - Creating Spatial Maps of Estimated Geostrophic Currents |github geostrophic| |nbviewer geostrophic| 14 | Creates an animation of geostrophic current maps using data derived from the monthly GRACE/GRACE-FO Level-2 spherical harmonic product 15 | - Creating Harmonic Plots |github harmonic| |nbviewer harmonic| 16 | Creates an animation of triangle plots that visualize the GRACE/GRACE-FO Level-2 spherical harmonic product 17 | 18 | .. |github spatial| image:: https://img.shields.io/badge/GitHub-view-6f42c1?style=flat&logo=Github 19 | :target: https://github.com/tsutterley/gravity-toolkit/blob/main/notebooks/GRACE-Spatial-Maps.ipynb 20 | 21 | .. |nbviewer spatial| image:: https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg 22 | :target: https://nbviewer.jupyter.org/github/tsutterley/gravity-toolkit/blob/main/notebooks/GRACE-Spatial-Maps.ipynb 23 | 24 | .. |github error| image:: https://img.shields.io/badge/GitHub-view-6f42c1?style=flat&logo=Github 25 | :target: https://github.com/tsutterley/gravity-toolkit/blob/main/notebooks/GRACE-Spatial-Error.ipynb 26 | 27 | .. |nbviewer error| image:: https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg 28 | :target: https://nbviewer.jupyter.org/github/tsutterley/gravity-toolkit/blob/main/notebooks/GRACE-Spatial-Error.ipynb 29 | 30 | .. |github geostrophic| image:: https://img.shields.io/badge/GitHub-view-6f42c1?style=flat&logo=Github 31 | :target: https://github.com/tsutterley/gravity-toolkit/blob/main/notebooks/GRACE-Geostrophic-Maps.ipynb 32 | 33 | .. |nbviewer geostrophic| image:: https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg 34 | :target: https://nbviewer.jupyter.org/github/tsutterley/gravity-toolkit/blob/main/notebooks/GRACE-Geostrophic-Maps.ipynb 35 | 36 | .. |github harmonic| image:: https://img.shields.io/badge/GitHub-view-6f42c1?style=flat&logo=Github 37 | :target: https://github.com/tsutterley/gravity-toolkit/blob/main/notebooks/GRACE-Harmonic-Plots.ipynb 38 | 39 | .. |nbviewer harmonic| image:: https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg 40 | :target: https://nbviewer.jupyter.org/github/tsutterley/gravity-toolkit/blob/main/notebooks/GRACE-Harmonic-Plots.ipynb 41 | -------------------------------------------------------------------------------- /gravity_toolkit/SLR/C40.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | u""" 3 | C40.py 4 | Written by Tyler Sutterley (05/2023) 5 | 6 | Reads monthly degree 4 zonal spherical harmonic data files from SLR 7 | 8 | Dataset distributed by CSR 9 | ftp://ftp.csr.utexas.edu/pub/slr/degree_5/ 10 | CSR_Monthly_5x5_Gravity_Harmonics.txt 11 | Dataset distributed by GSFC 12 | https://earth.gsfc.nasa.gov/geo/data/slr 13 | gsfc_slr_5x5c61s61.txt 14 | 15 | CALLING SEQUENCE: 16 | SLR_C40 = gravity_toolkit.SLR.C40(SLR_file) 17 | 18 | INPUTS: 19 | SLR_file: 20 | GSFC: gsfc_slr_5x5c61s61.txt 21 | CSR: CSR_Monthly_5x5_Gravity_Harmonics.txt 22 | 23 | OUTPUTS: 24 | data: SLR degree 4 order 0 cosine stokes coefficients (C40) 25 | error: SLR degree 4 order 0 cosine stokes coefficient error (eC40) 26 | month: GRACE/GRACE-FO month of measurement (April 2002 = 004) 27 | time: date of SLR measurement 28 | 29 | OPTIONS: 30 | HEADER: file contains header text to be skipped (default: True) 31 | C40_MEAN: mean C40 to add to LARES C40 anomalies 32 | DATE: mid-point of monthly solution for calculating 28-day arc averages 33 | 34 | PYTHON DEPENDENCIES: 35 | numpy: Scientific Computing Tools For Python 36 | https://numpy.org 37 | https://numpy.org/doc/stable/user/numpy-for-matlab-users.html 38 | dateutil: powerful extensions to datetime 39 | https://dateutil.readthedocs.io/en/stable/ 40 | 41 | PROGRAM DEPENDENCIES: 42 | time.py: utilities for calculating time operations 43 | read_SLR_harmonics.py: low-degree spherical harmonic coefficients from SLR 44 | 45 | UPDATE HISTORY: 46 | Updated 05/2023: use pathlib to define and operate on paths 47 | Updated 01/2023: refactored satellite laser ranging read functions 48 | Written 09/2022 49 | """ 50 | import re 51 | import pathlib 52 | import numpy as np 53 | import gravity_toolkit.time 54 | import gravity_toolkit.read_SLR_harmonics 55 | 56 | # PURPOSE: read Degree 4 zonal data from Satellite Laser Ranging (SLR) 57 | def C40(SLR_file, C40_MEAN=0.0, DATE=None, **kwargs): 58 | r""" 59 | Reads *C*\ :sub:`40` spherical harmonic coefficients from SLR measurements 60 | 61 | Parameters 62 | ---------- 63 | SLR_file: str 64 | Satellite Laser Ranging file 65 | C40_MEAN: float, default 0.0 66 | Mean *C*\ :sub:`40` to add to LARES *C*\ :sub:`40` anomalies 67 | DATE: float or NoneType, default None 68 | Mid-point of monthly solution for calculating 28-day arc averages 69 | 70 | Returns 71 | ------- 72 | data: float 73 | SLR degree 4 order 0 cosine stokes coefficients 74 | error: float 75 | SLR degree 4 order 0 cosine stokes coefficient error 76 | month: int 77 | GRACE/GRACE-FO month of measurement 78 | time: float 79 | date of SLR measurement 80 | """ 81 | 82 | # check that SLR file exists 83 | SLR_file = pathlib.Path(SLR_file).expanduser().absolute() 84 | if not SLR_file.exists(): 85 | raise FileNotFoundError(f'{str(SLR_file)} not found in file system') 86 | 87 | # output dictionary with data variables 88 | dinput = {} 89 | # determine source of input file 90 | if bool(re.search(r'gsfc_slr_5x5c61s61', SLR_file.name, re.I)): 91 | # read 5x5 + 6,1 file from GSFC and extract coefficients 92 | Ylms = gravity_toolkit.read_SLR_harmonics(SLR_file, HEADER=True) 93 | # calculate 28-day moving-average solution from 7-day arcs 94 | dinput.update(gravity_toolkit.convert_weekly(Ylms['time'], 95 | Ylms['clm'][4,0,:], DATE=DATE, NEIGHBORS=28)) 96 | # no estimated spherical harmonic errors 97 | dinput['error'] = np.zeros_like(DATE,dtype='f8') 98 | elif bool(re.search(r'C40_LARES', SLR_file.name, re.I)): 99 | # read LARES filtered values 100 | LARES_input = np.loadtxt(SLR_file, skiprows=1) 101 | dinput['time'] = LARES_input[:,0].copy() 102 | # convert C40 from anomalies to absolute 103 | dinput['data'] = 1e-10*LARES_input[:,1] + C40_MEAN 104 | # filtered data does not have errors 105 | dinput['error'] = np.zeros_like(LARES_input[:,1]) 106 | # calculate GRACE/GRACE-FO month 107 | dinput['month'] = gravity_toolkit.time.calendar_to_grace(dinput['time']) 108 | else: 109 | # read 5x5 + 6,1 file from CSR and extract C4,0 coefficients 110 | Ylms = gravity_toolkit.read_SLR_harmonics(SLR_file, HEADER=True) 111 | # extract dates, C40 harmonics and errors 112 | dinput['time'] = Ylms['time'].copy() 113 | dinput['data'] = Ylms['clm'][4,0,:].copy() 114 | dinput['error'] = Ylms['error']['clm'][4,0,:].copy() 115 | # converting from MJD into month, day and year 116 | YY,MM,DD,hh,mm,ss = gravity_toolkit.time.convert_julian( 117 | Ylms['MJD']+2400000.5, format='tuple') 118 | # calculate GRACE/GRACE-FO month 119 | dinput['month'] = gravity_toolkit.time.calendar_to_grace(YY,MM) 120 | 121 | # The 'Special Months' (Nov 2011, Dec 2011 and April 2012) with 122 | # Accelerometer shutoffs make the relation between month number 123 | # and date more complicated as days from other months are used 124 | # For CSR and GFZ: Nov 2011 (119) is centered in Oct 2011 (118) 125 | # For JPL: Dec 2011 (120) is centered in Jan 2012 (121) 126 | # For all: May 2015 (161) is centered in Apr 2015 (160) 127 | # For GSFC: Oct 2018 (202) is centered in Nov 2018 (203) 128 | dinput['month'] = gravity_toolkit.time.adjust_months(dinput['month']) 129 | 130 | # return the SLR-derived degree 4 zonal solutions 131 | return dinput 132 | -------------------------------------------------------------------------------- /gravity_toolkit/SLR/__init__.py: -------------------------------------------------------------------------------- 1 | from .C20 import * 2 | from .C30 import * 3 | from .C40 import * 4 | from .C50 import * 5 | from .CS2 import * 6 | -------------------------------------------------------------------------------- /gravity_toolkit/__init__.py: -------------------------------------------------------------------------------- 1 | """ 2 | A spherical harmonics toolkit for Python 3 | ======================================== 4 | 5 | gravity_toolkit contains Python tools for working with Level-2 6 | spherical harmonic coefficients from the NASA/DLR GRACE and 7 | NASA/GFZ GRACE-FO missions 8 | 9 | The package works using scientific Python packages (numpy and scipy) 10 | combined with data storage in ascii, netCDF4 and HDF5 and mapping with 11 | matplotlib and cartopy 12 | 13 | It aims to be a simple and efficient solution for using harmonic data from 14 | the GRACE/GRACE-FO missions and to support their science applications 15 | 16 | Documentation is available at https://gravity-toolkit.readthedocs.io 17 | """ 18 | import gravity_toolkit.geocenter 19 | import gravity_toolkit.mascons 20 | import gravity_toolkit.time 21 | import gravity_toolkit.tools 22 | import gravity_toolkit.utilities 23 | import gravity_toolkit.version 24 | from gravity_toolkit import SLR 25 | from gravity_toolkit import time_series 26 | from gravity_toolkit.associated_legendre import ( 27 | associated_legendre, 28 | plm_colombo, 29 | plm_holmes, 30 | plm_mohlenkamp 31 | ) 32 | from gravity_toolkit.clenshaw_summation import clenshaw_summation 33 | from gravity_toolkit.degree_amplitude import degree_amplitude 34 | from gravity_toolkit.destripe_harmonics import destripe_harmonics 35 | from gravity_toolkit.fourier_legendre import ( 36 | fourier_legendre, 37 | legendre_gradient 38 | ) 39 | from gravity_toolkit.gauss_weights import gauss_weights 40 | from gravity_toolkit.gen_averaging_kernel import gen_averaging_kernel 41 | from gravity_toolkit.gen_disc_load import gen_disc_load 42 | from gravity_toolkit.gen_harmonics import gen_harmonics 43 | from gravity_toolkit.gen_point_load import gen_point_load 44 | from gravity_toolkit.gen_spherical_cap import gen_spherical_cap 45 | from gravity_toolkit.gen_stokes import gen_stokes 46 | from gravity_toolkit.geocenter import geocenter 47 | from gravity_toolkit.grace_date import grace_date 48 | from gravity_toolkit.grace_find_months import grace_find_months 49 | from gravity_toolkit.grace_input_months import ( 50 | grace_input_months, 51 | read_ecmwf_corrections 52 | ) 53 | from gravity_toolkit.grace_months_index import grace_months_index 54 | from gravity_toolkit.harmonics import harmonics 55 | from gravity_toolkit.harmonic_gradients import ( 56 | harmonic_gradients, 57 | geostrophic_currents 58 | ) 59 | from gravity_toolkit.harmonic_summation import ( 60 | harmonic_summation, 61 | harmonic_transform, 62 | stokes_summation 63 | ) 64 | from gravity_toolkit.legendre_polynomials import legendre_polynomials 65 | from gravity_toolkit.legendre import legendre 66 | from gravity_toolkit.ocean_stokes import ocean_stokes, land_stokes 67 | from gravity_toolkit.read_gfc_harmonics import read_gfc_harmonics 68 | from gravity_toolkit.read_GIA_model import ( 69 | read_GIA_model, 70 | gia 71 | ) 72 | from gravity_toolkit.read_GRACE_harmonics import read_GRACE_harmonics 73 | from gravity_toolkit.read_love_numbers import ( 74 | read_love_numbers, 75 | load_love_numbers, 76 | love_numbers 77 | ) 78 | from gravity_toolkit.read_SLR_harmonics import ( 79 | read_SLR_harmonics, 80 | convert_weekly 81 | ) 82 | from gravity_toolkit.sea_level_equation import sea_level_equation 83 | from gravity_toolkit.spatial import ( 84 | spatial, 85 | scaling_factors 86 | ) 87 | from gravity_toolkit.units import units 88 | # get version number 89 | __version__ = gravity_toolkit.version.version 90 | -------------------------------------------------------------------------------- /gravity_toolkit/data/land_fcn_300km.nc: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:8479d12ebbea2855c4a2feb98a4cd772549a252fdfc40725496b53506b8bd05c 3 | size 17731 4 | -------------------------------------------------------------------------------- /gravity_toolkit/data/landsea_1d.nc: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:78b1227e168321c456370bc465f43ba71233296d0ea1a72d30da2782be89ebda 3 | size 30568 4 | -------------------------------------------------------------------------------- /gravity_toolkit/data/landsea_hd.nc: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:ed5c4f85ffdfe1f00f7150a0de4efd3348ea8ffb1a62ea15cd23b5bc2e35e37e 3 | size 48000 4 | -------------------------------------------------------------------------------- /gravity_toolkit/data/landsea_qd.nc: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:43bc5752e04b888262c484499d4a42fa4fb7d4aeda317fa6979b64f88ea630d9 3 | size 93489 4 | -------------------------------------------------------------------------------- /gravity_toolkit/degree_amplitude.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | u""" 3 | degree_amplitude.py 4 | Written Tyler Sutterley (03/2023) 5 | 6 | Calculates the amplitude of each spherical harmonic degree 7 | 8 | CALLING SEQUENCE: 9 | amp = degree_amplitude(clm,slm) 10 | 11 | INPUTS: 12 | clm: cosine spherical harmonic coefficients 13 | slm: sine spherical harmonic coefficients 14 | 15 | OPTIONS: 16 | LMAX: Upper bound of Spherical Harmonic Degrees 17 | MMAX: Upper bound of Spherical Harmonic Orders 18 | 19 | PYTHON DEPENDENCIES: 20 | numpy: Scientific Computing Tools For Python (https://numpy.org) 21 | 22 | UPDATE HISTORY: 23 | Updated 03/2023: improve typing for variables in docstrings 24 | Updated 05/2022: use numpy atleast_3d to add singleton dimensions 25 | Updated 04/2022: updated docstrings to numpy documentation format 26 | Updated 07/2020: added function docstrings 27 | Updated 05/2020: add singleton dimension to calculate time series amplitudes 28 | Updated 05/2015: added parameter MMAX for MMAX != LMAX 29 | Written 07/2013 30 | """ 31 | import numpy as np 32 | 33 | def degree_amplitude( 34 | clm, 35 | slm, 36 | LMAX=None, 37 | MMAX=None, 38 | ): 39 | """ 40 | Calculates the amplitude of each spherical harmonic degree 41 | 42 | Parameters 43 | ---------- 44 | clm: np.ndarray 45 | cosine spherical harmonic coefficients 46 | slm: np.ndarray 47 | sine spherical harmonic coefficients 48 | LMAX: int or NoneType, default None 49 | Upper bound of Spherical Harmonic Degrees 50 | MMAX: int or NoneType, default None 51 | Upper bound of Spherical Harmonic Orders 52 | 53 | Returns 54 | ------- 55 | amp: np.ndarray 56 | degree amplitude 57 | """ 58 | # add a singleton dimension to input harmonics 59 | clm = np.atleast_3d(clm) 60 | slm = np.atleast_3d(slm) 61 | # check shape 62 | LMp1,MMp1,nt = np.shape(clm) 63 | 64 | # upper bound of spherical harmonic degrees 65 | if LMAX is None: 66 | LMAX = LMp1 - 1 67 | # upper bound of spherical harmonic orders 68 | if MMAX is None: 69 | MMAX = MMp1 - 1 70 | 71 | # allocating for output array 72 | amp = np.zeros((LMAX+1,nt)) 73 | for l in range(LMAX+1): 74 | m = np.arange(0,MMAX+1) 75 | # degree amplitude of spherical harmonic degree 76 | amp[l,:] = np.sqrt(np.sum(clm[l,m,:]**2 + slm[l,m,:]**2,axis=0)) 77 | 78 | # return the degree amplitude with singleton dimensions removed 79 | return np.squeeze(amp) 80 | -------------------------------------------------------------------------------- /gravity_toolkit/gauss_weights.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | u""" 3 | gauss_weights.py 4 | Original IDL code gauss_weights.pro written by Sean Swenson 5 | Adapted by Tyler Sutterley (03/2023) 6 | 7 | Computes the Gaussian weights as a function of degree 8 | A normalized version of Jekeli's Gaussian averaging function 9 | 10 | Christopher Jekeli (1981) 11 | Alternative Methods to Smooth the Earth's Gravity Field 12 | http://www.geology.osu.edu/~jekeli.1/OSUReports/reports/report_327.pdf 13 | 14 | CALLING SEQUENCE: 15 | wl = gauss_weights(hw, LMAX) 16 | 17 | INPUTS: 18 | hw: Gaussian smoothing radius in kilometers 19 | Radius r corresponds to the distance at which the weight 20 | drops to half its peak value at the shortest wavelength 21 | LMAX: Maximum degree of spherical harmonic coefficients 22 | 23 | OPTIONS: 24 | CUTOFF: minimum value for tail of Gaussian averaging function 25 | 26 | OUTPUTS: 27 | wl: degree dependent weighting function 28 | 29 | PYTHON DEPENDENCIES: 30 | numpy: Scientific Computing Tools For Python (https://numpy.org) 31 | 32 | NOTES: 33 | Differences from recurs function in combine.mac.f: 34 | weighting from gauss_weights is normalized outside of the function 35 | wt = 2.0*pi*gauss_weights(rad,LMAX) 36 | weighting from recurs is normalized inside of the function 37 | call recurs(alpha,bcoef) calculates bcoef up to LMAX 150 (=wt[0:150]) 38 | alpha = alog(2.)/(1.-cos(rad/6371.)) 39 | 40 | UPDATE HISTORY: 41 | Updated 03/2023: improve typing for variables in docstrings 42 | Updated 04/2022: updated docstrings to numpy documentation format 43 | Updated 09/2021: added option for setting minimum value threshold 44 | Updated 07/2020: added function docstrings 45 | Updated 06/2015: adjusted threshold from 1e-9 to 1e-10 46 | Updated 12/2014: updated comments and header text updating full reference 47 | Updated 02/2014: changed variables from ints to floats to prevent truncation 48 | Written 05/2013 49 | """ 50 | import numpy as np 51 | 52 | def gauss_weights(hw, LMAX, CUTOFF=1e-10): 53 | """ 54 | Computes the Gaussian weights as a function of degree using 55 | a normalized form of :cite:p:`Jekeli:1981vj` 56 | 57 | Parameters 58 | ---------- 59 | hw: float 60 | Gaussian smoothing radius in kilometers 61 | LMAX: int 62 | Maximum degree of spherical harmonic coefficients 63 | CUTOFF: float, default 1e-10 64 | minimum value for tail of Gaussian averaging function 65 | 66 | Returns 67 | ------- 68 | wl: np.ndarray 69 | degree dependent weighting function 70 | """ 71 | # allocate for output weights 72 | wl = np.zeros((LMAX+1)) 73 | # radius of the Earth in km 74 | rad_e = 6371.0 75 | if (hw < CUTOFF): 76 | # distance is smaller than cutoff 77 | wl[:] = 1.0/(2.0*np.pi) 78 | else: 79 | # calculate gaussian weights using recursion 80 | b = np.log(2.0)/(1.0 - np.cos(hw/rad_e)) 81 | # weight for degree 0 82 | wl[0] = 1.0/(2.0*np.pi) 83 | # weight for degree 1 84 | wl[1] = wl[0]*((1.0+np.exp(-2.0*b))/(1.0-np.exp(-2.0*b))-1.0/b) 85 | # valid flag 86 | valid = True 87 | # spherical harmonic degree 88 | l = 2 89 | # while valid (within cutoff) 90 | # and spherical harmonic degree is less than LMAX 91 | while (valid and (l <= LMAX)): 92 | # calculate weight with recursion 93 | wl[l] = (1.0-2.0*l)/b*wl[l-1]+wl[l-2] 94 | # weight is less than cutoff 95 | if (wl[l] < CUTOFF): 96 | # set all weights to cutoff 97 | wl[l:LMAX+1] = CUTOFF 98 | # set valid flag 99 | valid = False 100 | # add 1 to l 101 | l += 1 102 | # return the gaussian weights 103 | return wl 104 | -------------------------------------------------------------------------------- /gravity_toolkit/legendre_polynomials.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | u""" 3 | legendre_polynomials.py 4 | Written by Tyler Sutterley (11/2024) 5 | 6 | Computes fully normalized Legendre polynomials for an array of x values 7 | and their first derivative 8 | Calculates Legendre polynomials for zonal harmonics (order 0) 9 | 10 | CALLING SEQUENCE: 11 | Pl,dPl = legendre_polynomials(lmax, np.cos(theta)) 12 | 13 | INPUTS: 14 | lmax: maximum degree of Legendre polynomials 15 | x: elements ranging from -1 to 1 16 | typically cos(theta), where theta is the colatitude in radians 17 | 18 | OUTPUT: 19 | pl: Legendre polynomials (geodesy normalization) 20 | dpl: first derivative of Legendre polynomials 21 | 22 | OPTIONS: 23 | ASTYPE: output variable type. Default is np.float64 24 | 25 | NOTES: 26 | ptemp is a dummy array of length (0:lmax) storing unnormalized pl values 27 | 28 | PYTHON DEPENDENCIES: 29 | numpy: Scientific Computing Tools For Python (https://numpy.org) 30 | 31 | REFERENCES: 32 | Hofmann-Wellenhof and Moritz, "Physical Geodesy" (2005) 33 | http://www.springerlink.com/content/978-3-211-33544-4 34 | 35 | UPDATE HISTORY: 36 | Updated 11/2024: add polar argument for x == +/-1 to prevent drift 37 | Updated 03/2023: improve typing for variables in docstrings 38 | Updated 04/2022: updated docstrings to numpy documentation format 39 | Updated 05/2021: define int/float precision to prevent deprecation warning 40 | Updated 09/2020: verify dimensions of x variable 41 | Updated 08/2020: prevent zero divisions by changing u==0 to eps of data type 42 | Updated 07/2020: added function docstrings 43 | Updated 07/2017: added first derivative of Legendre polynomials (dpl) 44 | added option ASTYPE to output as different variable types e.g. np.float64 45 | Written 03/2013 46 | """ 47 | import numpy as np 48 | 49 | def legendre_polynomials(lmax, x, ASTYPE=np.float64): 50 | """ 51 | Computes fully-normalized Legendre polynomials and their first derivative 52 | following :cite:t:`HofmannWellenhof:2006hy` 53 | 54 | Parameters 55 | ---------- 56 | lmax: int 57 | maximum degree of Legendre polynomials 58 | x: np.ndarray 59 | elements ranging from -1 to 1 60 | 61 | Typically ``cos(theta)``, where ``theta`` is the colatitude in radians 62 | ASTYPE: np.dtype, default np.float64 63 | output variable data type 64 | 65 | Returns 66 | ------- 67 | pl: np.ndarray 68 | fully-normalized Legendre polynomials 69 | dpl: np.ndarray 70 | first derivative of Legendre polynomials 71 | """ 72 | # verify dimensions 73 | x = np.atleast_1d(x).flatten().astype(ASTYPE) 74 | # size of the x array 75 | nx = len(x) 76 | # verify data type of spherical harmonic truncation 77 | lmax = np.int64(lmax) 78 | # output matrix of normalized legendre polynomials 79 | pl = np.zeros((lmax+1,nx),dtype=ASTYPE) 80 | # output matrix of First derivative of Legendre polynomials 81 | dpl = np.zeros((lmax+1,nx),dtype=ASTYPE) 82 | # dummy matrix for the recurrence relation 83 | ptemp = np.zeros((lmax+1,nx),dtype=ASTYPE) 84 | 85 | # u is sine of colatitude (cosine of latitude) so that 0 <= s <= 1 86 | # for x=cos(th): u=sin(th) 87 | u = np.sqrt(1.0 - x**2) 88 | # update where u==0 to eps of data type to prevent invalid divisions 89 | u0, = np.nonzero(u == 0) 90 | u[u0] = np.finfo(u.dtype).eps 91 | 92 | # Initialize the recurrence relation 93 | ptemp[0,:] = 1.0 94 | ptemp[1,:] = x 95 | # Normalization is geodesy convention 96 | pl[0,:] = ptemp[0,:] 97 | pl[1,:] = np.sqrt(3.0)*ptemp[1,:] 98 | for l in range(2,lmax+1): 99 | ptemp[l,:] = (((2.0*l)-1.0)/l)*x*ptemp[l-1,:] - ((l-1.0)/l)*ptemp[l-2,:] 100 | # Normalization is geodesy convention 101 | pl[l,:] = np.sqrt((2.0*l)+1.0)*ptemp[l,:] 102 | # Overwrite polar case (x == +/-1) 103 | pl[l,u0] = np.sqrt((2.0*l)+1.0)*x[u0]**l 104 | 105 | # First derivative of Legendre polynomials 106 | for l in range(1,lmax+1): 107 | fl = np.sqrt(((l**2.0) * (2.0*l + 1.0)) / (2.0*l - 1.0)) 108 | dpl[l,:] = (1.0/u)*(l*x*pl[l,:] - fl*pl[l-1,:]) 109 | 110 | # return the legendre polynomials and their first derivative 111 | return (pl, dpl) 112 | -------------------------------------------------------------------------------- /gravity_toolkit/time_series/__init__.py: -------------------------------------------------------------------------------- 1 | from .amplitude import * 2 | from .fit import * 3 | from .lomb_scargle import * 4 | from .piecewise import * 5 | from .regress import * 6 | from .savitzky_golay import * 7 | from .smooth import * 8 | -------------------------------------------------------------------------------- /gravity_toolkit/time_series/amplitude.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | u""" 3 | amplitude.py 4 | Written by Tyler Sutterley (01/2023) 5 | 6 | Calculate the amplitude and phase of a harmonic function from calculated 7 | sine and cosine of a series of measurements 8 | 9 | CALLING SEQUENCE: 10 | ampl,ph = gravity_toolkit.time_series.amplitude(bsin, bcos) 11 | 12 | INPUTS: 13 | bsin: amplitude of the calculated sine values 14 | bcos: amplitude of the calculated cosine values 15 | 16 | OUTPUTS: 17 | ampl: amplitude from the harmonic functions 18 | ph: phase from the harmonic functions in degrees 19 | 20 | PYTHON DEPENDENCIES: 21 | numpy: Scientific Computing Tools For Python (https://numpy.org) 22 | 23 | UPDATE HISTORY: 24 | Updated 01/2023: refactored time series analysis functions 25 | Updated 04/2022: updated docstrings to numpy documentation format 26 | Updated 07/2020: added function docstrings 27 | Updated 10/2019: output both amplitude and phase 28 | Updated 05/2013: converted to python 29 | Written 07/2012: 30 | """ 31 | import numpy as np 32 | 33 | def amplitude(bsin, bcos): 34 | """ 35 | Calculate the amplitude and phase of a harmonic function 36 | 37 | Parameters 38 | ---------- 39 | bsin: float 40 | amplitude of the calculated sine values 41 | bcos: float 42 | amplitude of the calculated cosine values 43 | 44 | Returns 45 | ------- 46 | ampl: float 47 | amplitude from the harmonic functions 48 | ph: float 49 | phase from the harmonic functions in degrees 50 | """ 51 | ampl = np.sqrt(bsin**2.0 + bcos**2.0) 52 | ph = 180.0*np.arctan2(bcos, bsin)/np.pi 53 | return (ampl,ph) 54 | -------------------------------------------------------------------------------- /gravity_toolkit/time_series/fit.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | u""" 3 | fit.py 4 | Written by Tyler Sutterley (06/2023) 5 | Utilities for fitting time-series data with regression models 6 | 7 | PYTHON DEPENDENCIES: 8 | numpy: Scientific Computing Tools For Python (https://numpy.org) 9 | 10 | UPDATE HISTORY: 11 | Updated 06/2023: made the tidal aliasing period an option 12 | Written 05/2023 13 | """ 14 | from __future__ import annotations 15 | import numpy as np 16 | 17 | # PURPOSE: build a list of tidal aliasing terms for regression fit 18 | def aliasing_terms(t_in: np.ndarray, period=161.0): 19 | """ 20 | Create a list of custom design-matrix terms to account for 21 | tidal aliasing during the GRACE and GRACE-FO periods 22 | 23 | Parameters 24 | ---------- 25 | t_in: float 26 | input time array 27 | period: float 28 | tidal aliasing period for a constituent 29 | 30 | Returns 31 | ------- 32 | TERMS: list 33 | tidal aliasing terms for GRACE and GRACE-FO missions 34 | """ 35 | # create output list of fit terms 36 | TERMS = [] 37 | # number of time points 38 | nmax = len(t_in) 39 | # create custom terms for tidal aliasing during GRACE period 40 | ii, = np.nonzero(t_in[0:nmax] < 2018.0) 41 | SIN = np.zeros((nmax)) 42 | COS = np.zeros((nmax)) 43 | SIN[ii] = np.sin(np.pi*t_in[ii]*730.50/period) 44 | COS[ii] = np.cos(np.pi*t_in[ii]*730.50/period) 45 | TERMS.append(SIN) 46 | TERMS.append(COS) 47 | # create custom terms for tidal aliasing during GRACE-FO period 48 | ii, = np.nonzero(t_in[0:nmax] >= 2018.0) 49 | SIN = np.zeros((nmax)) 50 | COS = np.zeros((nmax)) 51 | SIN[ii] = np.sin(np.pi*t_in[ii]*730.50/period) 52 | COS[ii] = np.cos(np.pi*t_in[ii]*730.50/period) 53 | TERMS.append(SIN) 54 | TERMS.append(COS) 55 | # return the fit terms 56 | return TERMS 57 | -------------------------------------------------------------------------------- /gravity_toolkit/version.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | u""" 3 | version.py (11/2023) 4 | Gets version number of a package 5 | """ 6 | import importlib.metadata 7 | 8 | # package metadata 9 | metadata = importlib.metadata.metadata("gravity_toolkit") 10 | # get version 11 | version = metadata["version"] 12 | # append "v" before the version 13 | full_version = f"v{version}" 14 | # get project name 15 | project_name = metadata["Name"] 16 | -------------------------------------------------------------------------------- /readthedocs.yml: -------------------------------------------------------------------------------- 1 | # readthedocs.yml 2 | # Read the Docs configuration file 3 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 4 | 5 | # Required 6 | version: 2 7 | 8 | # Configuration for the documentation build process 9 | build: 10 | os: "ubuntu-22.04" 11 | tools: 12 | python: "mambaforge-22.9" 13 | 14 | # Build documentation in the docs/ directory with Sphinx 15 | sphinx: 16 | configuration: doc/source/conf.py 17 | 18 | # Optionally build your docs in additional formats such as PDF and ePub 19 | formats: [] 20 | 21 | # Optionally set the version of conda and environment required to build your docs 22 | conda: 23 | environment: doc/environment.yml 24 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | boto3 2 | future 3 | lxml 4 | matplotlib 5 | numpy 6 | python-dateutil 7 | pyyaml 8 | scipy 9 | -------------------------------------------------------------------------------- /scripts/calc_harmonic_resolution.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | u""" 3 | calc_harmonic_resolution.py 4 | Written by Tyler Sutterley (04/2022) 5 | 6 | Calculates the spatial resolution that can be resolved 7 | by the spherical harmonics of a certain degree 8 | Default method uses the smallest half-wavelength that can be resolved 9 | (is equal to approximately 20000/lmax km) 10 | Secondary method calculates the smallest possible bump that can be resolved 11 | by dividing the area of a sphere by (lmax+1)^2 12 | 13 | CALLING SEQUENCE: 14 | python calc_harmonic_resolution.py --lmax 60 --cap 15 | 16 | COMMAND LINE OPTIONS: 17 | -l X, --lmax X: maximum degree of spherical harmonics 18 | -R X, --radius X: average radius of the Earth in kilometers 19 | -C, --cap: calculate the smallest possible bump that can be resolved 20 | 21 | PYTHON DEPENDENCIES: 22 | numpy: Scientific Computing Tools For Python (https://numpy.org) 23 | 24 | REFERENCES: 25 | Hofmann-Wellenhof and Moritz, "Physical Geodesy" (2005) 26 | http://www.springerlink.com/content/978-3-211-33544-4 27 | Barthelmes, "Definition of Functionals of the Geopotential and Their 28 | Calculation from Spherical Harmonic Models", STR09/02 (2009) 29 | http://icgem.gfz-potsdam.de/str-0902-revised.pdf 30 | 31 | UPDATE HISTORY: 32 | Updated 04/2022: use argparse descriptions within documentation 33 | Updated 09/2020: using argparse to set parameters 34 | Updated 10/2019: changing Y/N flags to True/False 35 | Updated 02/2014: minor update to if statement 36 | Updated 08/2013: changed SPH_CAP option to (Y/N) 37 | Written 01/2013 38 | """ 39 | import argparse 40 | import numpy as np 41 | 42 | # PURPOSE: Calculates minimum spatial resolution that can be resolved 43 | # from spherical harmonics of a maximum degree 44 | def calc_harmonic_resolution(LMAX, RADIUS=6371.0008, SPH_CAP=False): 45 | """ 46 | Calculates minimum spatial resolution that can be resolved from 47 | spherical harmonics of a maximum degree 48 | 49 | Arguments 50 | --------- 51 | LMAX: maximum spherical harmonic degree 52 | 53 | Keyword arguments 54 | ----------------- 55 | RADIUS: average radius of the Earth in kilometers 56 | SPH_CAP: calculate the smallest possible bump that can be resolved 57 | """ 58 | if SPH_CAP: 59 | # Smallest diameter of a spherical cap that can be resolved by the 60 | # harmonics. Size of the smallest bump, half-wavelength, which can 61 | # be produced by the clm/slm 62 | psi_min = 4.0*RADIUS*np.arcsin(1.0/(LMAX+1.0)) 63 | else: 64 | # Shortest half-wavelength that can be resolved by the clm/slm 65 | # This estimation is based on the number of possible zeros along 66 | # the equator 67 | psi_min = np.pi*RADIUS/LMAX 68 | return psi_min 69 | 70 | # PURPOSE: create argument parser 71 | def arguments(): 72 | parser = argparse.ArgumentParser() 73 | parser.add_argument('--lmax','-l', metavar='LMAX', 74 | type=int, nargs='+', 75 | help='maximum degree of spherical harmonics') 76 | parser.add_argument('--radius','-R', 77 | type=float, default=6371.0008, 78 | help='Average radius of the Earth in kilometers') 79 | parser.add_argument('--cap','-C', 80 | default=False, action='store_true', 81 | help='Calculate smallest possible bump that can be resolved') 82 | # return the parser 83 | return parser 84 | 85 | # This is the main part of the program that calls the individual functions 86 | def main(): 87 | # Read the system arguments listed after the program 88 | parser = arguments() 89 | args,_ = parser.parse_known_args() 90 | # for each entered spherical harmonic degree 91 | for LMAX in args.lmax: 92 | psi_min = calc_harmonic_resolution(LMAX, 93 | RADIUS=args.radius, SPH_CAP=args.cap) 94 | print('{0:5d}: {1:0.4f} km'.format(LMAX,psi_min)) 95 | 96 | # run main program 97 | if __name__ == '__main__': 98 | main() 99 | -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [tool:pytest] 2 | minversion = 2.0 3 | norecursedirs = .git 4 | python_files = test*.py 5 | testpaths = 6 | test 7 | 8 | [coverage:run] 9 | branch = true 10 | source = 11 | gravity_toolkit 12 | test 13 | omit = 14 | setup.py 15 | conf.py 16 | scripts/* 17 | 18 | [coverage:report] 19 | show_missing = true 20 | precision = 2 21 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | import os 2 | from setuptools import setup, find_packages 3 | 4 | # package description and keywords 5 | description = ('Python tools for obtaining and working with spherical harmonic' 6 | 'coefficients from the NASA/DLR GRACE and NASA/GFZ GRACE Follow-on missions') 7 | keywords = 'GRACE, GRACE-FO, Gravity, satellite geodesy, spherical harmonics' 8 | # get long_description from README.rst 9 | with open("README.rst", mode="r", encoding='utf8') as fh: 10 | long_description = fh.read() 11 | long_description_content_type = "text/x-rst" 12 | 13 | # get install requirements 14 | with open('requirements.txt', encoding='utf8') as fh: 15 | install_requires = [line.split().pop(0) for line in fh.read().splitlines()] 16 | 17 | # get version 18 | with open('version.txt', encoding='utf8') as fh: 19 | version = fh.read() 20 | 21 | # list of all scripts to be included with package 22 | scripts=[os.path.join('scripts',f) for f in os.listdir('scripts') if f.endswith('.py')] 23 | scripts.append(os.path.join('gravity_toolkit','grace_date.py')) 24 | scripts.append(os.path.join('gravity_toolkit','grace_months_index.py')) 25 | 26 | setup( 27 | name='gravity-toolkit', 28 | version=version, 29 | description=description, 30 | long_description=long_description, 31 | long_description_content_type=long_description_content_type, 32 | url='https://github.com/tsutterley/gravity-toolkit', 33 | author='Tyler Sutterley', 34 | author_email='tsutterl@uw.edu', 35 | license='MIT', 36 | classifiers=[ 37 | 'Development Status :: 3 - Alpha', 38 | 'Intended Audience :: Science/Research', 39 | 'Topic :: Scientific/Engineering :: Physics', 40 | 'License :: OSI Approved :: MIT License', 41 | 'Programming Language :: Python :: 3', 42 | 'Programming Language :: Python :: 3.6', 43 | 'Programming Language :: Python :: 3.7', 44 | 'Programming Language :: Python :: 3.8', 45 | 'Programming Language :: Python :: 3.9', 46 | 'Programming Language :: Python :: 3.10', 47 | ], 48 | keywords=keywords, 49 | packages=find_packages(), 50 | install_requires=install_requires, 51 | scripts=scripts, 52 | include_package_data=True, 53 | ) 54 | -------------------------------------------------------------------------------- /test/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tsutterley/gravity-toolkit/7cb878631c154cfc4e085482fbc8a269d6c90350/test/__init__.py -------------------------------------------------------------------------------- /test/conftest.py: -------------------------------------------------------------------------------- 1 | import pytest 2 | 3 | def pytest_addoption(parser): 4 | parser.addoption("--username", action="store", help="NASA Earthdata username") 5 | parser.addoption("--password", action="store", help="NASA Earthdata password") 6 | parser.addoption("--webdav", action="store", help="PO.DAAC Drive WebDAV password") 7 | 8 | @pytest.fixture 9 | def username(request): 10 | """ Returns NASA Earthdata username """ 11 | return request.config.getoption("--username") 12 | 13 | @pytest.fixture 14 | def password(request): 15 | """ Returns NASA Earthdata password """ 16 | return request.config.getoption("--password") 17 | 18 | @pytest.fixture 19 | def webdav(request): 20 | """ Returns PO.DAAC Drive WebDAV password """ 21 | return request.config.getoption("--webdav") 22 | -------------------------------------------------------------------------------- /test/out.combine.green_ice.0.5.2008.60.gz: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tsutterley/gravity-toolkit/7cb878631c154cfc4e085482fbc8a269d6c90350/test/out.combine.green_ice.0.5.2008.60.gz -------------------------------------------------------------------------------- /test/out.geoid.green_ice.0.5.2008.60.gz: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tsutterley/gravity-toolkit/7cb878631c154cfc4e085482fbc8a269d6c90350/test/out.geoid.green_ice.0.5.2008.60.gz -------------------------------------------------------------------------------- /test/out.green_ice.grid.0.5.2008.cmh20.gz: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tsutterley/gravity-toolkit/7cb878631c154cfc4e085482fbc8a269d6c90350/test/out.green_ice.grid.0.5.2008.cmh20.gz -------------------------------------------------------------------------------- /test/requirements.txt: -------------------------------------------------------------------------------- 1 | pytest>=4.6 2 | pytest-cov 3 | -------------------------------------------------------------------------------- /test/test_gia.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | u""" 3 | test_gia.py (12/2022) 4 | Tests the that GIA model readers are equivalent 5 | """ 6 | import gzip 7 | import time 8 | import pytest 9 | import shutil 10 | import pathlib 11 | import numpy as np 12 | import gravity_toolkit as gravtk 13 | 14 | # PURPOSE: Download ICE-6G GIA model 15 | @pytest.fixture(scope="module", autouse=True) 16 | def download_GIA_model(): 17 | # output GIA file 18 | GIA_FILE = pathlib.Path('Stokes_trend_High_Res.txt') 19 | # download GIA model 20 | HOST = ['https://www.atmosp.physics.utoronto.ca','~peltier','datasets', 21 | 'Ice6G_C_VM5a','ICE-6G_High_Res_Stokes_trend.txt.gz'] 22 | fid = gravtk.utilities.from_http(HOST, verbose=True) 23 | # decompress GIA model from virtual BytesIO object 24 | with gzip.open(fid, 'rb') as f_in, open(GIA_FILE, 'wb') as f_out: 25 | shutil.copyfileobj(f_in, f_out) 26 | # run tests 27 | yield 28 | # clean up 29 | GIA_FILE.unlink() 30 | 31 | # PURPOSE: read ICE-6G GIA test outputs 32 | def test_GIA_model_read(): 33 | # output GIA file and type 34 | GIA_FILE = 'Stokes_trend_High_Res.txt' 35 | GIA = 'ICE6G-D' 36 | # read GIA model 37 | Ylms = gravtk.read_GIA_model(GIA_FILE, GIA=GIA) 38 | # assert input GIA values 39 | assert Ylms['clm'][2,0] == 1.43961238E-11 40 | assert Ylms['clm'][3,0] == 1.52009079E-12 41 | assert Ylms['slm'][3,1] == -8.05198489E-12 42 | # assert parameters 43 | assert Ylms['title'] == 'ICE6G-D_High_Res' 44 | 45 | # PURPOSE: read ICE-6G GIA model and test harmonic outputs 46 | def test_GIA_model_harmonics(): 47 | # output GIA file and type 48 | GIA_FILE = 'Stokes_trend_High_Res.txt' 49 | GIA = 'ICE6G-D' 50 | # degree of truncation 51 | LMAX,MMAX = (60, 30) 52 | # read GIA model 53 | Ylms = gravtk.gia(lmax=LMAX).from_GIA(GIA_FILE, GIA=GIA, mmax=MMAX) 54 | # assert input GIA values 55 | assert Ylms.clm[2,0] == 1.43961238E-11 56 | assert Ylms.clm[3,0] == 1.52009079E-12 57 | assert Ylms.slm[3,1] == -8.05198489E-12 58 | # assert parameters 59 | assert Ylms.title == 'ICE6G-D_High_Res' 60 | # assert truncation 61 | assert Ylms.lmax == LMAX 62 | assert Ylms.l[-1] == LMAX 63 | assert Ylms.mmax == MMAX 64 | assert Ylms.m[-1] == MMAX 65 | 66 | # PURPOSE: read ICE-6G GIA model and compare drift estimates 67 | def test_GIA_model_drift_estimate(): 68 | # output GIA file and type 69 | GIA_FILE = 'Stokes_trend_High_Res.txt' 70 | GIA = 'ICE6G-D' 71 | # degree and order of truncation 72 | LMAX,MMAX = (60, 30) 73 | # synthetic time estimate 74 | now = time.gmtime() 75 | tdec = np.arange(2002, now.tm_year+1, 1.0/12.0) 76 | epoch = 2003.3 77 | # read GIA model 78 | GIA_Ylms_rate = gravtk.read_GIA_model(GIA_FILE, GIA=GIA, LMAX=LMAX, MMAX=MMAX) 79 | # calculate the monthly mass change from GIA 80 | GIA_Ylms = gravtk.harmonics(lmax=LMAX, mmax=MMAX) 81 | GIA_Ylms.time = np.copy(tdec) 82 | GIA_Ylms.month = gravtk.time.calendar_to_grace(tdec) 83 | GIA_Ylms.month = gravtk.time.adjust_months(GIA_Ylms.month) 84 | # allocate for output harmonics 85 | GIA_Ylms.clm = np.zeros((GIA_Ylms.lmax+1, GIA_Ylms.mmax+1, len(tdec))) 86 | GIA_Ylms.slm = np.zeros((GIA_Ylms.lmax+1, GIA_Ylms.mmax+1, len(tdec))) 87 | # assert input GIA values 88 | # monthly GIA calculated by gia_rate*time elapsed 89 | # finding change in GIA each month 90 | for i,t in enumerate(tdec): 91 | GIA_Ylms.clm[:,:,i] = GIA_Ylms_rate['clm']*(t - epoch) 92 | GIA_Ylms.slm[:,:,i] = GIA_Ylms_rate['slm']*(t - epoch) 93 | # read GIA model and calculate drift from harmonics class 94 | Ylms = gravtk.gia(lmax=LMAX).from_GIA( 95 | GIA_FILE, GIA=GIA, mmax=MMAX).drift(tdec, epoch=epoch) 96 | # assert that spherical harmonics are equal 97 | assert np.all(GIA_Ylms.clm == Ylms.clm) 98 | assert np.all(GIA_Ylms.slm == Ylms.slm) 99 | # assert time variables are equal 100 | assert np.all(GIA_Ylms.time == Ylms.time) 101 | assert np.all(GIA_Ylms.month == Ylms.month) 102 | -------------------------------------------------------------------------------- /test/test_legendre.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | u""" 3 | test_legendre.py (11/2021) 4 | """ 5 | import numpy as np 6 | import gravity_toolkit as gravtk 7 | 8 | # PURPOSE: test unnormalized Legendre polynomials 9 | def test_unnormalized(l=3, x=[-1.0, -0.9, -0.8]): 10 | obs = gravtk.legendre(l, x) 11 | expected = np.array([ 12 | [-1.00000, -0.47250, -0.08000], 13 | [0.00000, -1.99420, -1.98000], 14 | [0.00000, -2.56500, -4.32000], 15 | [0.00000, -1.24229, -3.24000] 16 | ]) 17 | assert np.isclose(obs, expected, atol=1e-05).all() 18 | 19 | # PURPOSE: test fully-normalized Legendre polynomials 20 | def test_normalized(l=3, x=[-1.0, -0.9, -0.8]): 21 | obs = gravtk.legendre(l, x, NORMALIZE=True) 22 | expected = np.array([ 23 | [-2.64575, -1.25012, -0.21166], 24 | [-0.00000, 2.15398, 2.13864], 25 | [0.00000, -0.87611, -1.47556], 26 | [-0.00000, 0.17323, 0.45180] 27 | ]) 28 | assert np.isclose(obs, expected, atol=1e-05).all() 29 | 30 | # PURPOSE: test fully-normalized zonal Legendre polynomials 31 | def test_zonal(l=3, x=[-1.0, -0.9, -0.8]): 32 | obs,_ = gravtk.legendre_polynomials(l, x) 33 | expected = np.array([ 34 | [1.00000, 1.00000, 1.00000], 35 | [-1.73205, -1.55885, -1.38564], 36 | [2.23607, 1.59879, 1.02859], 37 | [-2.64575, -1.25012, -0.21166], 38 | ]) 39 | assert np.isclose(obs, expected, atol=1e-05).all() 40 | 41 | # PURPOSE: compare fully-normalized Legendre polynomials 42 | def test_plms(l=240, x=0.1): 43 | obs = gravtk.legendre(l, x, NORMALIZE=True) 44 | # calculate associated Legendre polynomials 45 | holmes,_ = gravtk.plm_holmes(l, x) 46 | colombo,_ = gravtk.plm_colombo(l, x) 47 | mohlenkamp,_ = gravtk.plm_mohlenkamp(l, x) 48 | # compare Legendre polynomials 49 | assert np.isclose(obs, holmes[l,:]).all() 50 | assert np.isclose(holmes, colombo).all() 51 | assert np.isclose(holmes, mohlenkamp).all() 52 | -------------------------------------------------------------------------------- /test/test_love_numbers.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | u""" 3 | test_love_numbers.py (01/2023) 4 | UPDATE HISTORY: 5 | Updated 01/2023: single implicit import of gravity toolkit 6 | Updated 12/2020: add linear interpolation to degree 1000 7 | add tests for Gegout and Wang load Love number sets 8 | Written 08/2020 9 | """ 10 | import os 11 | import pytest 12 | import gravity_toolkit as gravtk 13 | 14 | # PURPOSE: Define Load Love Numbers for lower degree harmonics 15 | def get_love_numbers(): 16 | """ 17 | Gets a list of Load Love Numbers for degrees 0 to 3 18 | """ 19 | hl = [-0.13273, -0.26052933922888, -0.99015777857079, -1.0499804506108] 20 | kl = [0.0, 0.02743231435436, -0.30252982142510, -0.19413374466744] 21 | ll = [0.0, 0.13026466961444, 0.023882296795977, 0.069842389427609] 22 | return dict(hl=hl, kl=kl, ll=ll) 23 | 24 | # PURPOSE: Check that Load Love Numbers match expected for reference frame 25 | def test_love_numbers(): 26 | # valid low degree Love numbers for reference frame CF 27 | VALID = get_love_numbers() 28 | # path to load Love numbers file 29 | love_numbers_file = gravtk.utilities.get_data_path( 30 | ['data','love_numbers']) 31 | # read load Love numbers and convert to reference frame CF 32 | TEST = gravtk.read_love_numbers(love_numbers_file, 33 | LMAX=1000, HEADER=2, FORMAT='dict', REFERENCE='CF') 34 | assert all((v==t).all() for key in ['hl','kl','ll'] 35 | for v,t in zip(VALID[key],TEST[key])) 36 | assert (TEST['l'].max() == 1000) 37 | 38 | # PURPOSE: Check that Gegout (2005) Load Love Numbers can be read 39 | def test_Gegout_love_numbers(): 40 | # path to load Love numbers file 41 | love_numbers_file = gravtk.utilities.get_data_path( 42 | ['data','Load_Love2_CE.dat']) 43 | COLUMNS = ['l','hl','ll','kl'] 44 | # read load Love numbers and convert to reference frame CM 45 | TEST = gravtk.read_love_numbers(love_numbers_file, 46 | HEADER=3, COLUMNS=COLUMNS, FORMAT='class', REFERENCE='CM') 47 | assert (TEST.lmax == 1024) 48 | 49 | # PURPOSE: Check that Wang et al. (2012) Load Love Numbers can be read 50 | def test_Wang_love_numbers(): 51 | # path to load Love numbers file (truncated from degree 46341) 52 | love_numbers_file = gravtk.utilities.get_data_path( 53 | ['data','PREM-LLNs-truncated.dat']) 54 | COLUMNS = ['l','hl','ll','kl','nl','nk'] 55 | # read load Love numbers and convert to reference frame CE 56 | TEST = gravtk.read_love_numbers(love_numbers_file, 57 | HEADER=1, COLUMNS=COLUMNS, FORMAT='class', REFERENCE='CE') 58 | assert (TEST.lmax == 5000) 59 | -------------------------------------------------------------------------------- /test/test_point_masses.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | u""" 3 | test_point_masses.py (01/2023) 4 | UPDATE HISTORY: 5 | Updated 01/2023: single implicit import of gravity toolkit 6 | Written 02/2021 7 | """ 8 | import pytest 9 | import numpy as np 10 | import gravity_toolkit as gravtk 11 | 12 | # parameterize the number of point masses 13 | @pytest.mark.parametrize("NPTS", np.random.randint(2,2000,size=1)) 14 | def test_point_masses(NPTS): 15 | # create spatial grid 16 | dlon,dlat = (1.0,1.0) 17 | lat = np.arange(90.0 - dlat/2.0, -90.0 - dlat/2.0, -dlat) 18 | lon = np.arange(-180.0 + dlon/2.0, 180.0 + dlon/2.0, dlon) 19 | gridlon,gridlat = np.meshgrid(lon,lat) 20 | nlat, nlon = np.shape(gridlon) 21 | 22 | # parameterize point masses 23 | LAT = lat[0]-dlat*np.random.randint(0,nlat,size=NPTS) 24 | LON = lon[0]+dlon*np.random.randint(0,nlon,size=NPTS) 25 | MASS = 100.0 - 200.0*np.random.randn(NPTS) 26 | 27 | # create test gridded field 28 | data = np.zeros((nlat, nlon)) 29 | for i in range(NPTS): 30 | indy,indx = np.nonzero((gridlat == LAT[i]) & (gridlon == LON[i])) 31 | data[indy,indx] += MASS[i] 32 | 33 | # path to load Love numbers file 34 | love_numbers_file = gravtk.utilities.get_data_path( 35 | ['data','love_numbers']) 36 | # read load Love numbers 37 | LOVE = gravtk.read_love_numbers(love_numbers_file) 38 | # calculate harmonics and degree amplitudes for each case 39 | grid_Ylms = gravtk.gen_stokes(data, lon, lat, 40 | LMAX=60, UNITS=2, LOVE=LOVE) 41 | point_Ylms = gravtk.gen_point_load(MASS, LON, LAT, 42 | LMAX=60, UNITS=2, LOVE=LOVE) 43 | 44 | # check that harmonic data is equal to machine precision 45 | difference_Ylms = grid_Ylms.copy() 46 | difference_Ylms.subtract(point_Ylms) 47 | harmonic_eps = np.finfo(np.float32).eps 48 | assert np.all(np.abs(difference_Ylms.clm) < harmonic_eps) 49 | # verify that the degree amplitudes are within tolerance 50 | difference_amplitude = grid_Ylms.amplitude - point_Ylms.amplitude 51 | assert np.all(np.abs(difference_amplitude) < harmonic_eps) 52 | -------------------------------------------------------------------------------- /test/test_units.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | u""" 3 | test_units.py (03/2023) 4 | Verify spherical harmonic and spatial unit factors 5 | 6 | UPDATE HISTORY: 7 | Updated 03/2023: include explicit comparison with some units 8 | include comparisons without including elastic deformation 9 | Written 01/2023 10 | """ 11 | import pytest 12 | import numpy as np 13 | import gravity_toolkit as gravtk 14 | 15 | # PURPOSE: test spherical harmonic units 16 | @pytest.mark.parametrize("LMAX", np.random.randint(60,696,size=1)) 17 | def test_harmonic_units(LMAX): 18 | # extract arrays of kl, hl, and ll Love Numbers 19 | LOVE = gravtk.load_love_numbers(LMAX, 20 | LOVE_NUMBERS=0, REFERENCE='CF', 21 | FORMAT='class') 22 | factors = gravtk.units(lmax=LMAX).harmonic(*LOVE) 23 | # cmwe, centimeters water equivalent 24 | cmwe = factors.rho_e*factors.rad_e*(2.0*factors.l+1.0)/(1.0+LOVE.kl)/3.0 25 | assert np.all(factors.get('cmwe') == factors.cmwe) 26 | assert np.all(factors.get(gravtk.units.bycode(1)) == factors.cmwe) 27 | assert np.all(cmwe == factors.cmwe) 28 | # mmGH, mm geoid height 29 | mmGH = np.ones((LMAX + 1))*(10.0*factors.rad_e) 30 | assert np.all(factors.get('mmGH') == factors.mmGH) 31 | assert np.all(factors.get(gravtk.units.bycode(2)) == factors.mmGH) 32 | assert np.all(mmGH == factors.mmGH) 33 | # mmCU, mm elastic crustal deformation 34 | assert np.all(factors.get('mmCU') == factors.mmCU) 35 | assert np.all(factors.get(gravtk.units.bycode(3)) == factors.mmCU) 36 | # microGal, microGal gravity perturbations 37 | assert np.all(factors.get('microGal') == factors.microGal) 38 | assert np.all(factors.get(gravtk.units.bycode(4)) == factors.microGal) 39 | # mbar, equivalent surface pressure 40 | assert np.all(factors.get('mbar') == factors.mbar) 41 | assert np.all(factors.get(gravtk.units.bycode(5)) == factors.mbar) 42 | # cmVCU, cm viscoelastic crustal uplift (GIA ONLY) 43 | assert np.all(factors.get('cmVCU') == factors.cmVCU) 44 | assert np.all(factors.get(gravtk.units.bycode(6)) == factors.cmVCU) 45 | # cmwe, centimeters water equivalent without elastic deformation 46 | factors = gravtk.units(lmax=LMAX).harmonic(*LOVE, include_elastic=False) 47 | cmwe = factors.rho_e*factors.rad_e*(2.0*factors.l+1.0)/3.0 48 | assert np.all(factors.get('cmwe') == factors.cmwe) 49 | 50 | # PURPOSE: test harmonic units with different love number formats 51 | @pytest.mark.parametrize("LMAX", np.random.randint(60,696,size=1)) 52 | def test_harmonic_love_numbers(LMAX): 53 | # extract arrays of kl, hl, and ll Love Numbers 54 | hl,kl,ll = gravtk.load_love_numbers(LMAX, 55 | LOVE_NUMBERS=0, REFERENCE='CF', 56 | FORMAT='tuple') 57 | LOVE = gravtk.load_love_numbers(LMAX, 58 | LOVE_NUMBERS=0, REFERENCE='CF', 59 | FORMAT='class') 60 | factors_tuple = gravtk.units(lmax=LMAX).harmonic(hl,kl,ll) 61 | factors_class = gravtk.units(lmax=LMAX).harmonic(*LOVE) 62 | # cmwe, centimeters water equivalent 63 | assert np.all(factors_tuple.get('cmwe') == factors_class.get('cmwe')) 64 | # mmCU, mm elastic crustal deformation 65 | assert np.all(factors_tuple.get('mmCU') == factors_class.get('mmCU')) 66 | # mbar, equivalent surface pressure 67 | assert np.all(factors_tuple.get('mbar') == factors_class.get('mbar')) 68 | 69 | # PURPOSE: test spatial units 70 | @pytest.mark.parametrize("LMAX", np.random.randint(60,696,size=1)) 71 | def test_spatial_units(LMAX): 72 | # extract arrays of kl, hl, and ll Love Numbers 73 | LOVE = gravtk.load_love_numbers(LMAX, 74 | LOVE_NUMBERS=0, REFERENCE='CF', 75 | FORMAT='class') 76 | factors = gravtk.units(lmax=LMAX).spatial(*LOVE) 77 | # cmwe, centimeters water equivalent 78 | cmwe = 3.0*(1.0+LOVE.kl)/(1.0+2.0*factors.l)/(4.0*np.pi*factors.rad_e*factors.rho_e) 79 | assert np.all(factors.get('cmwe') == factors.cmwe) 80 | assert np.all(cmwe == factors.cmwe) 81 | # mmwe, millimeters water equivalent 82 | mmwe = 3.0*(1.0+LOVE.kl)/(1.0+2.0*factors.l)/(40.0*np.pi*factors.rad_e*factors.rho_e) 83 | assert np.all(factors.get('mmwe') == factors.mmwe) 84 | assert np.all(mmwe == factors.mmwe) 85 | # cmwe, centimeters water equivalent without elastic deformation 86 | factors = gravtk.units(lmax=LMAX).spatial(*LOVE, include_elastic=False) 87 | cmwe = 3.0/(1.0+2.0*factors.l)/(4.0*np.pi*factors.rad_e*factors.rho_e) 88 | assert np.all(factors.get('cmwe') == factors.cmwe) 89 | 90 | # PURPOSE: test unit attributes 91 | def test_unit_attributes(): 92 | units_name, units_longname = gravtk.units.get_attributes('cmwe') 93 | assert (units_name == 'cm') 94 | assert (units_longname == 'Equivalent_Water_Thickness') 95 | units_name, units_longname = gravtk.units.get_attributes('microGal') 96 | assert (units_name == u'\u03BCGal') 97 | assert (units_longname == 'Gravitational_Undulation') 98 | units_name, units_longname = gravtk.units.get_attributes('mVCU') 99 | assert (units_name == 'meters') 100 | assert (units_longname == 'Viscoelastic_Crustal_Uplift') 101 | -------------------------------------------------------------------------------- /version.txt: -------------------------------------------------------------------------------- 1 | 1.2.3 2 | --------------------------------------------------------------------------------