Setup and Installation

Installation

geoid-toolkit is available for download from the GitHub repository, the Python Package Index (pypi), and from conda-forge.

The simplest installation for most users will likely be using conda or mamba:

conda install -c conda-forge geoid-toolkit

conda installed versions of geoid-toolkit can be upgraded to the latest stable release:

conda update geoid-toolkit

Development Install

To use the development repository, please fork geoid-toolkit into your own account and then clone onto your system:

git clone https://github.com/tsutterley/geoid-toolkit.git

geoid-toolkit can then be installed within the package directory using pip:

python3 -m pip install --user .

To include all optional dependencies:

python3 -m pip install --user .[all]

The development version of geoid-toolkit can also be installed directly from GitHub using pip:

python3 -m pip install --user git+https://github.com/tsutterley/geoid-toolkit.git

Package Management with pixi

Alternatively pixi can be used to create a streamlined environment after cloning the repository:

pixi install

pixi maintains isolated environments for each project, allowing for different versions of geoid-toolkit and its dependencies to be used without conflict. The pixi.lock file within the repository defines the required packages and versions for the environment.

pixi can also create shells for running programs within the environment:

pixi shell

To see the available tasks within the geoid-toolkit workspace:

pixi task list

Tasks that can run on this machine:
-----------------------------------
clean-docs (by design), coverage (by design), docs (by design), export-env (by design), lint (by design), start (by design), test (by design)
Task        Description
clean-docs  Remove build artifacts and rebuild the documentation with sphinx
coverage    Run the pytest suite and create coverage reports
docs        Create documentation with sphinx
export-env  Export workspace to a conda environment file
lint        Run flake8 to check for compilation errors
start       Start JupyterLab in the notebooks directory
test        Run the pytest suite

Note

pixi is under active development and may change in future releases

Verifying Installation

import geoid_toolkit as geoidtk

print(f'geoid-toolkit version: {geoidtk.__version__}')

geoid-toolkit version: 1.1.3

Configuration

The geoid-toolkit cache directory is the default location for downloaded GRACE/GRACE-FO and auxiliary data. The default cache directory is platform-specific and set by the platformdirs package. This parametrized path can be persistently overridden on a machine by setting the GEOIDTK_CACHE_DIR environment variable.

The location of the cache directory used by geoid-toolkit can be checked by:

geoidtk.utilities.get_cache_path()

PosixPath('/home/docs/.cache/geoidtk')