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 (source distribution only)

   • The PyPI release is a source distribution (sdist), not a prebuilt binary runtime
   • Best suited for packaging workflows and source-based consumers

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 to PyPI on tagged releases.

• This channel is intended for source consumption.
• 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
• Source 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.

License

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