Quasi-static imaging of earthquake cycle kinematics

celeri is a Python-based package designed to image earthquake cycle activity, including spatial slip deficit/fault coupling across geometrically complex fault systems at large scales. It features:

• GUI-based model building with celeri_ui
• Graphical comparisons of model results with result_manager
• 3D visualization of model results with parsli
• Fast and automated block closure on the sphere
• Large aperture models with locally optimized sphere flattening
• Implicit smoothing and a small memory footprint via distance-weighted eigenmodes
• Slip rate and coupling bounded solves via sequential quadratic programming
• Markov chain Monte Carlo (MCMC) uncertainty estimates
• Blazingly fast elastic calculations via Ben Thompson's cutde
• Easy I/O with standard file types (.csv, .json, .hdf5, .pkl)

Getting started

celeri can be run from the command line or from a Jupyter notebook.

A project folder structure containing a data/ directory, such as the one provided with this repository, is required to use celeri.

After installation, you can use celeri-solve or other commands from the command line:

cd data/config
celeri-solve some_config.json

You can also run celeri from a Jupyter notebook, such as those provided in the notebooks/ directory.

To run notebooks from Visual Studio Code:

1. Ensure that celeri is installed.
2. Start VS Code, and ensure that the Jupyter extension is installed.
3. Open the project folder (e.g. a clone of this repository).
4. Open the notebook you'd like to run.
5. Click on the Python environment selector near the upper right-hand corner of the VS Code window.
6. If using pixi, select the "default" kernel. Otherwise, select the environment in which you installed celeri.
7. Run the notebook.

If VS Code does not show an option for the "default" kernel, ensure that your Jupyter extension is up to date. You may need to restart VS Code after running pixi shell for the first time.

Installation

The simplest way to install celeri is to use pixi.

# Create a clone of this repository into the celeri/ directory
git clone https://github.com/brendanjmeade/celeri.git
cd celeri
pixi shell  # Installs and activates the pre-configured celeri "default" environment

Note that pixi is project-centric, so pixi commands only apply if you're within the project directory.

Pixi's support for global project installs is currently very preliminary. In the meantime, running the following command will create shims for all your favorite celeri commands like celeri-solve so you can run them from anywhere:

pixi run pixi-global-install-shim-hack

You can remove these shims by adding the --remove flag to this command.

For details about how to use pixi in other configurations, or how to install celeri with other tools such as conda, pip, or uv, see alternative-installation.md.

Command line workflow

celeri-solve

• Estimate model parameters.
• A *_config.json file is a required argument.
• With the Python environment activated, run:

celeri-solve <my_config.json>

• This will create a folder in the runs/ directory that contains all output files. New folders are created automatically for each run and are sequentially numbered.

• All relative paths in *_config.json are resolved relative to the directory containing the config file. Absolute paths are used as-is.

• NOTE: In the current release, several warnings/errors will be thrown, but they do not impact the calculations. These result from: numpy/numpy#28687. These are patched in numpy 2.3 and will go away once Numba releases with numba/numba#10110 merged.

celeri-forward

• Predict surface velocities from model parameters constrained by previous celeri-solve run.
• celeri-forward is batched so that it never creates large matrices.
• With the Python environment activated, run:

celeri-forward <path to output folder> <station file for forward model predictions>

• If you plan to run celeri-forward, you may want gridded locations for model evaluation. Use create-grid-station:

create-grid-station <lon_min> <lat_min> <lon_max> <lat_max> --n_points=<number of grid points>

• where:
  • lon_min: Minimum longitude
  • lat_min: Minimum latitude
  • lon_max: Maximum longitude
  • lat_max: Maximum latitude
  • --n_points=<number of grid points>: Optional. The default value is 100.
• This produces a station file (named <UUID>_station.csv) that can be passed to celeri-forward.

Folder structure and file locations for applications

A large number of input files can be involved in a model run. We assume that a project is arranged using the following folder structure:

project_name/
├── README.md
├── notebooks/
│   ├── block_model.ipynb
│   ├── visualize_results.ipynb
│   └── resolution_tests.ipynb
├── data/
|   ├── config/
│   |   └── *config.json
│   ├── segment/
│   │   └── *segment.csv
│   ├── block/
│   │   └── *block.csv
│   ├── station/
│   │   └── *station.csv
│   ├── mesh/
│   |   ├── *mesh.json
│   |   └── *.msh
|   └── operators/
│       └── *.hdf5
└── runs/
    └── 0000000001/
       ├── 0000000001.log
       ├── output.pkl
       ├── elastic_operators.hdf5
       ├── model_segment.csv
       ├── model_block.csv
       └── model_station.csv

The flow of information through celeri

Contributing to celeri

In order to contribute a GitHub pull request, you'll need to:

1. Set up your Python environment for development
2. Set up your local Git clone for contributions

If you've installed using pixi as described above, your environment is already development-ready. Otherwise, you'll need to ensure celeri has been pip-installed in editable mode as per the alternative installation instructions.

To reconfigure your local Git clone for contributions, you'll need to fork the repository and reconfigure your remotes:

# After forking the repository to your GitHub account:
git remote rename origin upstream
git remote add origin https://github.com/YOUR_USERNAME/celeri.git

Replace YOUR_USERNAME with your GitHub username.

Maintenance notes

See maintenance-notes.md for current best practices for maintaining this repository, in particular:

• Cutting a new release
• Updating dependencies

Other earthquake cycle kinematics software

We think celeri is pretty great, but there are other great kinematic modeling tools:

• Jack Loveless' and Brendan Meade's MATLAB-based Blocks
• Rob McCaffrey's Fortran-based TDEFNODE
• Richard Styron's Julia-based Oiler