APSG is the package for structural geologists. It defines several new Python classes to easily manage, analyze and visualize orientation structural geology data.

Check CHANGELOG.md for recent updates.

Quick example

from apsg import *

f = folset.random_fisher(position=fol(130, 60))
s = StereoNet()
s.great_circle(f)
s.point(f)
s.contour(f)
s.show()

StereoNet supports both equal-area (Schmidt, default) and equal-angle (Wulff) projections, lower and upper hemisphere, and rotating the whole net independently of the plotted data. See the stereonet tutorial in the documentation for examples.

Requirements

APSG requires Python 3.12 or later. It depends on NumPy, SciPy, Matplotlib, SQLAlchemy, pandas, pygeomag. The installers below take care of these.

Installation

Install APSG into a separate environment. Pick one of the options below. uv is the default and the fastest; pip and conda/mamba are alternatives.

With uv (recommended)

Install uv, then create a virtual environment and install APSG into it:

uv venv
uv pip install apsg

Activate the environment on Linux and macOS:

source .venv/bin/activate

On Windows (Command Prompt or PowerShell):

.venv\Scripts\activate

To include JupyterLab and openpyxl (needed to read Excel files), use the lab extra:

uv pip install "apsg[lab]"

In an existing project with a pyproject.toml, add APSG as a dependency instead:

uv add apsg

To use APSG from the command line, install it as a tool. This puts an isolated copy of APSG on your PATH, without activating an environment:

uv tool install apsg

Then start the interactive APSG shell, which runs from apsg import * for you:

iapsg

To try the shell without installing, run uvx --from apsg iapsg. Add the lab extra with uv tool install "apsg[lab]" to include JupyterLab.

Development install

To work on APSG itself, clone the repository and install it in editable mode with all extras and development tools:

git clone https://github.com/ondrolexa/apsg.git
cd apsg
uv sync --all-extras --dev

Run the test suite with uv run pytest.

With pip

Create and activate a virtual environment. On Linux and macOS:

python -m venv .venv
source .venv/bin/activate

On Windows (Command Prompt or PowerShell):

python -m venv .venv
.venv\Scripts\activate

Note: On Windows, PowerShell may refuse to run the activation script. To allow it for the current user, run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Install the latest stable release from PyPI:

pip install apsg

To include JupyterLab and openpyxl (needed to read Excel files), use the lab extra:

pip install "apsg[lab]"

To upgrade an existing installation without touching its dependencies:

pip install --upgrade --no-deps apsg

To install the master branch from GitHub:

pip install git+https://github.com/ondrolexa/apsg.git

With conda or mamba

If you already use conda or mamba, add the conda-forge channel and create an environment with APSG:

conda config --add channels conda-forge
conda create -n apsg python apsg jupyterlab

or with mamba:

mamba create -n apsg python apsg jupyterlab

To install APSG into an existing environment, run conda install apsg (or mamba install apsg).

Current release

Name	Downloads	Version	Platforms

Documentation

Explore all features of APSG in the documentation.

Contributing

Most discussion happens on GitHub. Feel free to open an issue or comment on any open issue or pull request. See CONTRIBUTING.md for more details.

Donate

APSG is an open-source project, available for free. It took a lot of time and resources to build this software. If you find it useful and want to support its future development, please consider donating.

License

APSG is free software: you can redistribute it and/or modify it under the terms of the MIT License. A copy of this license is provided in the LICENSE file.