Metadata-Version: 2.4
Name: celeri
Version: 0.0.5
Summary: Next generation earthquake cycle kinematics
Project-URL: Homepage, https://github.com/brendanjmeade/celeri
Author-email: Brendan Meade <brendanjmeade@gmail.com>
License: MIT License
        
        Copyright (c) 2005 brendanjmeade
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.13
Requires-Dist: cartopy
Requires-Dist: colorcet
Requires-Dist: cutde>=25.7.24
Requires-Dist: cvxopt
Requires-Dist: cvxpy
Requires-Dist: gmsh
Requires-Dist: h5py
Requires-Dist: ipykernel
Requires-Dist: ipython
Requires-Dist: loguru
Requires-Dist: matplotlib
Requires-Dist: meshio
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: nutpie
Requires-Dist: pandas
Requires-Dist: papermill
Requires-Dist: pyarrow
Requires-Dist: pydantic
Requires-Dist: pymc
Requires-Dist: pyproj
Requires-Dist: pytest
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: shapely
Requires-Dist: spherical-geometry
Requires-Dist: tqdm
Requires-Dist: xarray
Requires-Dist: zarr
Description-Content-Type: text/markdown

# Quasi-static imaging of earthquake cycle kinematics

[![GitHub stars](https://img.shields.io/github/stars/brendanjmeade/celeri?style=social)](https://github.com/brendanjmeade/celeri)
[![Tests](https://github.com/brendanjmeade/celeri/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/brendanjmeade/celeri/actions/workflows/test.yml)
[![Release pipeline](https://github.com/brendanjmeade/celeri/actions/workflows/release.yaml/badge.svg?branch=main)](https://github.com/brendanjmeade/celeri/actions/workflows/release.yaml)
[![conda-forge](https://img.shields.io/conda/vn/conda-forge/celeri.svg)](https://prefix.dev/channels/conda-forge/packages/celeri)
[![PyPI version](https://img.shields.io/pypi/v/celeri.svg)](https://pypi.org/project/celeri/)
[![pixi](https://img.shields.io/badge/pixi-project-4E54E9?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTYiIGhlaWdodD0iOTYiIHZpZXdCb3g9IjAgMCA5NiA5NiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cmVjdCB3aWR0aD0iOTYiIGhlaWdodD0iOTYiIHJ4PSIxNiIgZmlsbD0iI0ZGRiIvPjxwYXRoIGQ9Ik00OS45OTkgMTkuMzMzTDUwIDc2LjY2N0M2NS4yNCA3Mi43MzIgNzYuNjY3IDU5LjQ3MSA3Ni42NjcgNDMuMzMzQzc2LjY2NyAyNy4xOTUgNjUuMjQgMTMuOTM0IDUwIDEwTDUwIDYuNjY3MjNFQzMwLjIxNCAxMS4xMjIgMTYuNjY3IDI3LjE5NCAxNi42NjcgNDMuMzMzQzE2LjY2NyA1OS40NzEgMzAuMjE0IDcyLjczMiA1MCA3Ni42NjdMNDkuOTk5IDE5LjMzM1oiIGZpbGw9IiM0RTU0RTkiLz48L3N2Zz4=)](https://pixi.sh)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/brendanjmeade/celeri/tree/main/LICENSE)

`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`](https://brendanjmeade.github.io/celeri_ui/)
- Graphical comparisons of model results with [`result_manager`](https://github.com/brendanjmeade/result_manager)
- 3D visualization of model results with [`parsli`](https://github.com/brendanjmeade/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](https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2025EA004229)
- Markov chain Monte Carlo (MCMC) uncertainty estimates
- Blazingly fast elastic calculations via [Ben Thompson's](https://github.com/tbenthompson) [cutde](https://github.com/tbenthompson/cutde)
- Easy I/O with standard file types (`.csv`, `.json`, `.hdf5`, `.pkl`)

See the [wiki](https://github.com/brendanjmeade/celeri/wiki) for more detailed information.

## Getting started

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

A [project folder structure](https://github.com/brendanjmeade/celeri/tree/main/#folder-structure-and-file-locations-for-applications) containing a `data/` directory, such as the one provided with this repository, is required to use `celeri`.

After [installation](https://github.com/brendanjmeade/celeri/tree/main/#installation), you can use `celeri-solve` or [other commands](https://github.com/brendanjmeade/celeri/tree/main/#command-line-workflow) from the command line:

```bash
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](https://github.com/brendanjmeade/celeri/tree/main/#installation).
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](https://pixi.sh/).

```bash
# 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:

```bash
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](https://github.com/brendanjmeade/celeri/tree/main/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:

```bash
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.

### `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:

```bash
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`:

```bash
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:

```text
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

```mermaid
%%{init: {
  'theme': 'forest',
  'themeVariables': { 'primaryColor': '#90EE90', 'lineColor': '#333' },
  'flowchart': { 'padding': 5, 'nodeSpacing': 15, 'rankSpacing': 55 }
}}%%

flowchart TB
    command["config.json"]
    celeri_ui["celeri_ui"]:::tool

    station["station.csv"]
    los["los.csv"]
    mogi["mogi.csv"]
    block["block.csv"]
    segmesh["segmesh.py"]:::tool
    segment["segment.csv"]
    mesh_json["mesh_params.json"]
    mesh_1["mesh_1.msh"]
    mesh_2["mesh_2.msh"]
    mesh_3["mesh_3.msh"]

    mesh_n["mesh_n.msh"]

    %% Solid lines from command.json
    command --> station
    command --> los
    command --> mogi
    command --> block
    command --> segment
    command --> mesh_json

    %% Solid lines from celeri_ui
    celeri_ui -.-> block
    celeri_ui -.-> segment

    %% Solid line segment to mesh.json
    segment --> mesh_json

    %% Solid lines from mesh.json to mesh files
    mesh_json --> mesh_1
    mesh_json -.-> mesh_2
    mesh_json -.-> mesh_3
    mesh_json -.-> mesh_n

    mesh_1 ~~~ mesh_2
    mesh_2 ~~~ mesh_3
    mesh_3 ~~~ mesh_n

    %% DASHED: segmesh to mesh files
    segmesh -.-> mesh_json
    segmesh -.-> mesh_1
    segmesh -.-> mesh_n
    segmesh -.-> mesh_2
    segmesh -.-> mesh_3
    segmesh -.-> segment

    celeri_solve["celeri-solve.py"]:::tool

    %% command.json to celeri-solve.py
    command --> celeri_solve

    station_out["model_station.csv"]
    segment_out["model_segment.csv"]
    output_zarr["*.zarr"]
    model_hdf["model.hdf"]
    meshes_csv["model_meshes.csv"]

    celeri_solve --> station_out
    celeri_solve --> segment_out
    celeri_solve --> meshes_csv
    celeri_solve --> model_hdf
    celeri_solve --> output_zarr

    fennil["fennil"]:::tool
    parsli["parsli"]:::tool
    vis_ipynb["vis.ipynb"]:::tool

    station_out --> fennil
    segment_out --> fennil
    meshes_csv --> fennil
    model_hdf --> parsli
    output_zarr --> vis_ipynb

    %% Vertical ordering trick
    mesh_n ~~~ celeri_solve
    celeri_solve ~~~ station_out

    classDef tool fill:#e8d0e8,stroke:#333,stroke-width:1px
    classDef dashedtool fill:#e8d0e8,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef dashed fill:#90EE90,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef gradient fill:#90EE90,stroke:#333,stroke-width:1px
```

### 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](https://github.com/brendanjmeade/celeri/tree/main/#installation), 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](https://github.com/brendanjmeade/celeri/tree/main/alternative-installation.md#installing-for-development).

To reconfigure your local Git clone for contributions, you'll need to [fork the repository](https://github.com/brendanjmeade/celeri/fork) and reconfigure your remotes:

```bash
# 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](https://github.com/brendanjmeade/celeri/tree/main/maintenance-notes.md) for current best practices for maintaining this repository, in particular:

- [Cutting a new release](https://github.com/brendanjmeade/celeri/tree/main/maintenance-notes.md#cutting-a-new-release)
- [Updating dependencies](https://github.com/brendanjmeade/celeri/tree/main/maintenance-notes.md#updating-existing-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](https://github.com/jploveless/Blocks)
- Rob McCaffrey's Fortran-based [TDEFNODE](https://robmccaffrey.github.io/TDEFNODE/TDEFNODE.html)
- Richard Styron's Julia-based [Oiler](https://github.com/cossatot/Oiler)
