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
• Implicity smoothing and small memory footprint via distance-weighted eigenmodes
• Slip rate and coupling bounded solves via [sequential quadratic programming] (https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2025EA004229)
• MCMC uncertainty estimates
• Blazingly fast elastic calculations via Ben Thompson's cutde
• Easy IO with standard file types (.csv, .json, .hdf5, .pkl)

Getting started

To set up a development conda environment, install pixi and run the following command in the celeri folder.

pixi shell

Alternatively, run the following commands in the celeri folder.

conda config --prepend channels conda-forge
conda env create
conda activate celeri
pip install --no-use-pep517 -e .

From here, you can launch model runs with celeri_solve.

To run notebooks from VSCode:

1. cd to the celeri folder.
2. Use code . to start VSCode from the command line.
3. Navigate to the notebook you'd like to run.
4. Click on the Python environment selector near the upper right-hand corner of the VSCode window.
5. Select the "default" shell.
6. Run the notebook.

Command line work flow

celeri_solve.py

• Estimate model parameters.
• A *_config.json file is a required argument.
• Call as:

python celeri_solve.py <my_config.json>

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

celeri_forward.py

• Predict surface velocities from model parameters constrained by previous celeri_solve.py run.
• celeri_forward.py is batched , so that it never creates large matrices.
• Call as:

python celeri_forward.py <path to output folder> <station file for forward model predictions>

• If you want to run celeri_forward.py, you probably want some gridded locations for model evaluation. That's what create_grid_station.py is for: Call as:

python create_grid_station.py <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.py.

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

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:

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