MsPASS: Massive Parallel Analysis System for Seismologists

MsPASS is an open-source framework for scalable seismic data processing and data management. It combines:

• A parallel processing framework based on a scheduler/worker model (Dask and Spark integration)
• A MongoDB-centered data management model for waveform and metadata workflows
• A container-first runtime model for reproducible desktop, cluster, and cloud execution

For full user and API documentation, visit mspass.org.

Table of Contents

• How to Get MsPASS
• Quick Start (Recommended: Docker)
• Conda Installation (Alternative)
• PyPI Package Status
• Documentation
• Development and Source Builds
• Project Links
• Contributing
• License

How to Get MsPASS

MsPASS is distributed through multiple channels with different intended use cases:

1. Docker (recommended for most users)

   • Primary, fully provisioned runtime path
   • Published to Docker Hub: mspass/mspass
   • Also published to GitHub Container Registry: ghcr.io/mspass-team/mspass

2. Conda (alternative local package install)

   • Published as mspasspy on Anaconda Cloud: anaconda.org/mspass/mspasspy
   • Appropriate when you need a local Conda-managed environment

3. PyPI (Linux x86_64 wheels and source distribution)

   • Native wheels are published for Linux x86_64 on CPython 3.10, 3.11, 3.12, and 3.13
   • The source distribution remains available for source-based consumers
   • PyPI wheels for macOS, Windows, and Linux arm64 are not supported

Quick Start (Recommended: Docker)

Install Docker Desktop (or Docker Engine on Linux), then pull the image:

docker pull mspass/mspass

Launch MsPASS in a project directory (Jupyter exposed on port 8888):

docker run -p 8888:8888 --mount src=`pwd`,target=/home,type=bind mspass/mspass

Then open the Jupyter URL printed in the container logs (typically http://127.0.0.1:8888/...).

For repeated runs and multi-service operation, use Docker Compose. A baseline compose configuration is available in data/yaml/compose.yaml.

Conda Installation (Alternative)

If you prefer Conda over containers:

conda create --name mspass_env
conda activate mspass_env
conda config --add channels mspass
conda config --add channels conda-forge
conda install -y mspasspy

Conda package: anaconda.org/mspass/mspasspy

Note: many workflows still rely on MongoDB and are easiest to operate via the MsPASS Docker image, even when Python libraries are installed via Conda.

PyPI Package Status

MsPASS publishes a source distribution and native Linux x86_64 wheels for CPython 3.10 through 3.13 to PyPI on tagged releases.

• macOS, Windows, and Linux arm64 wheels are not published or supported.
• Other platforms can use the source distribution with a compatible native toolchain.
• It is not the recommended end-user runtime path.
• For the most complete and reproducible environment, use Docker.

Documentation

• Documentation home: www.mspass.org
• Running MsPASS on a desktop: mspass_desktop
• Command-line Docker workflow: command_line_desktop
• Deploy with Conda: deploy_mspass_with_conda
• Python API reference: python_api
• C++ API reference: cxx_api

Development and Source Builds

For contributors and source builds:

• Build/setup guide: Compiling MsPASS from source code
• Contributor onboarding: Get started instructions for contributors

Project Links

For users interested in releases and package channels:

• Docker image: Docker Hub
• Conda package: Anaconda Cloud
• Python package: PyPI
• Container mirror: GitHub Container Registry
• Source repository: GitHub

Maintainer and contributor automation (CI, packaging, release jobs) is implemented with GitHub Actions workflows in this repository.

Contributing

Contributions are welcome. Please use issues and pull requests for bug reports, feature requests, and code changes.

Before opening a pull request:

1. Follow the contributor setup instructions in the project wiki.
2. Run relevant tests locally when possible.
3. Keep documentation in sync with user-facing behavior changes.

CI automatically formats Python, tests, and documentation notebooks with Black 25.1.0. For a PR from a branch in this repository, it creates or updates one formatting-only PR into that source branch, using black-formatting/pr-<original PR number>. Merge that fix to apply the changes; the original PR's CI then reruns. Formatting PRs do not create further formatting PRs, and obsolete fixes and their branches are cleaned up when the source PR is formatted or closed. A stale run cannot publish after its source PR has moved.

The required black-format check stays red until the generated changes are applied to the actual source commit. Every run that finds changes also uploads a black-format.patch artifact; download it and run git apply black-format.patch on the source branch if preferred. Fork PRs use this patch because the repository token cannot write to contributors' forks. GitHub may require a maintainer to select Approve workflows to run on a bot-created formatting PR; no extra personal access token is required.

Run the matching read-only check locally from the repository root with:

python -m pip install 'black[jupyter]==25.1.0'
shopt -s globstar nullglob
notebooks=(docs/**/*.ipynb)
black --workers 1 --check --diff python/mspasspy python/tests "${notebooks[@]}"

To apply the corresponding formatting locally, run the final command without --check --diff:

shopt -s globstar nullglob
notebooks=(docs/**/*.ipynb)
black --workers 1 python/mspasspy python/tests "${notebooks[@]}"

License

This project is licensed under the BSD 3-Clause License. See LICENSE for details.