---

📖 Introduction

ECAT is a unified framework for adaptive fault modeling and earthquake cycle analysis. It integrates fault constructing, forward modeling, data processing, and advanced inversion strategies into a comprehensive toolkit.

Key Goals:

• Provide robust tools for the entire Forward and Inverse earthquake cycle.
• Support complex fault geometries with adaptive meshing.
• Enable flexible hyperparameter estimation strategies (Single, Individual, Grouped).
• Continuous Updates: Stable features are integrated regularly, with ongoing bug fixes and new module additions.

---

💻 Installation

See Install.md for detailed instructions.

Quick Start

# Clone the repository
git clone https://github.com/kefuhe/ECAT.git
cd ECAT

# Python 3.10 is recommended; 3.11 and 3.12 remain supported targets.
conda create -n ecat -c conda-forge python=3.10 --file requirements/ecat-requirements.txt
conda activate ecat

# Install an okada4py wheel matching the active CPython version first.
# If no matching release wheel is available, Install.md shows the source-build route.
# Then run the installation script.
./install.sh  # Linux / WSL

Windows PowerShell runs the platform script as:

.\install.bat

For mainland-China direct connections without a working VPN, use the command-scoped USTC conda-forge mirror instead of the default conda create line:

conda create -n ecat --override-channels --strict-channel-priority -c https://mirrors.ustc.edu.cn/anaconda/cloud/conda-forge python=3.10 --file requirements/ecat-requirements.txt

This mirror option is for slow Conda/PyPI downloads, not for VPN/proxy failures or GitHub downloads. Install.md gives the corresponding pip, Linux/WSL, and PowerShell commands.

The command above lets Conda choose the platform runtime. If you want MKL with Open MPI, MS-MPI, or Intel MPI from the outset, choose one of the verified pre-install profiles in Install.md before creating the environment; do not replace BLAS/MPI binaries after installing ECAT.

csi and its runtime dependencies are required. The repository dependency list contains the direct runtime requirements of CSI and eqtools together with their compatibility ranges. See Install.md for the wheel and optional-feature instructions. See installation and runtime troubleshooting for VPN/proxy recovery, temporary BLAS thread tests, MPI diagnostics, and symptom-specific recovery steps. The compute runtime stack explains how oneAPI, oneMKL, OpenBLAS, mpi4py, Open MPI, MPICH, Intel MPI, and MS-MPI fit together. The parallel execution basics introduces processes, MPI ranks, threads, CPU affinity, and portable first-run commands.

Updating an existing checkout

After pulling a newer ECAT revision, update eqtools from its own project directory instead of recreating the complete environment:

git pull
conda activate ecat
cd eqtools
python -m pip install .

Maintainers who need source edits to take effect without reinstalling can use python -m pip install -e . instead. Reinstall csi_cutde_mpiparallel separately only when CSI changed. The full update and optional-extra commands are documented in Install.md.

---

🏃 Running ECAT & Case Studies

ECAT relies on a rich library of cases for testing and research. To run ECAT effectively, you should first obtain the case library.

3.1 Get the Case Library (Basic Running)

The full case library is hosted in a separate repository (ECAT-Cases). You have two options to download it:

Option 1: Auto-download via Install Script Uncomment the following line in install.sh / install.bat before running installation:

git submodule update --init --recursive

Option 2: Manual Download

# Using the helper script
./download_cases.sh

# Or direct clone into the directory
git clone [https://github.com/kefuhe/ECAT-cases.git](https://github.com/kefuhe/ECAT-cases.git)

3.2 Method & Example Modules

Basic examples to understand specific modules of ECAT.

🏷️ Category	⚡ Earthquake Example	📝 Description (Date, Magnitude, Type)	📁 Directory (in ECAT-Cases)
Data preparation & Downsampling	InSAR / offset downsampling	GAMMA, GeoTIFF, GMTSAR direct-projection, and adapter examples; converts dense SAR/offset rasters to CSI-style .txt/.rsp/.cov inputs	Cases · Guide
Nonlinear Inversion	Hotan Earthquake	2020-06-25, Mw6.3, Normal	Details
	Iran Earthquake	2017-04-05, Mw6.1, Reverse	Details
	Taiwan Earthquake	2024-04-05, Mw7.4, Reverse	Details
	Wushi Earthquake	2024-01-22, Mw7.0, Strike-slip	Details
	Western Xizang	2020-07-22, Mw6.3, Normal	Details
BLSE Linear Inversion	Dingri Earthquake 2020	2020-03-20, Mw5.7, Normal	Details

For detailed data-format notes, use the ECAT-Cases README and the ECAT docs: InSAR downsampling, adapter workflow, and SAR reader reference.

3.3 Real Earthquake Case Studies (Visual Gallery)

Advanced applications demonstrating adaptive fault geometry and complex slip distribution.

A. Adaptive Fault Geometry with Relocated Aftershocks

Case 1: 2021 Maduo Earthquake (Mw 7.4)

Case 2: 2023 Kahramanmaraş Türkiye Doublet

Complex multi-segment modeling with variance dip angles.

Case 3: 2022 Luding Earthquake

Pre-Clustering Selection Followed by Fitting.

B. Isocurve Fitting (Depth-focused Aftershocks)

Note: Robust curve fitting serves as a reference. Final curves often incorporate user interaction.

C. Comprehensive Research Cases List

🌏 Case Name	📝 Description	🔗 Link
Dingri 2015	2015-04-25, Mw5.7, Normal	Details
Dingri 2020	2020-03-20, Mw5.6, Normal	Details
Dingri 2025	2025-01-07, Mw7.0, Normal	Details
Sagaing 2025	2025-03-28, Mw7.8, Strike-slip	Details

---

🚀 Core Features & Workflow

1. Inversion Workflow & Strategies

ECAT supports a flexible inversion pipeline, ranging from standard step-wise inversion to advanced joint Bayesian optimization.

• Data Processing:
  • InSAR/Offset: Supports Resolution-based (fault-dependent) and Quadtree-based (fault-independent) downsampling.
  • GNSS: Direct integration without downsampling.
• Inversion Strategies:
  • Standard Two-Step: Nonlinear geometry search followed by Linear slip inversion (BLSE/VCE).
  • SMC-FJ (Joint Strategy): Simultaneous estimation of Geometry + Slip + Hyperparameters using Bayesian optimization.
• Hyperparameter Modes (Unique Feature): For both Linear (BLSE; VCE) and Bayesian parts, data weights and smoothing factors can be estimated in three modes:
  • Single: Global factor for all datasets/faults (Default for smoothing).
  • Individual (Default): Independent factor for each dataset/fault-segment (Default for weighting).
  • Grouped: Cluster-based factors for user-defined groups.

2. Adaptive Fault Construction & Meshing

ECAT offers versatile methods to build complex fault geometries from various data sources.

• Construction Modes:
  1. Planar: Simple geometry from GCMT or nonlinear inversion results.
  2. Listric: Depth-dependent dip (exponential decay/SDM-style).
  3. Trace + Profile: Lofted surfaces defined by surface traces and variable dip profiles.
  4. Contour: 3D surfaces from Slab2.0 depth contours or iso-depth curves.
• Meshing:
  • Triangular Elements (T3): Recommended for complex, gap-free surfaces.
  • Rectangular Elements (Q4): Supported for simple planar geometries.

3. Forward Modeling Engines

ECAT utilizes layered Green's function calculations powered by edcmp and pscmp, supporting both rectangular and triangular elements.

For details, see README in the csi subdirectory.

---

🚧 Modules in Development

Postseismic (Beta)

• Engine: pscmp_visco_postseismic.py
• Features: Combined model of viscoelastic relaxation and stress-driven afterslip.
  • cv_cum: Viscoelastic relaxation due to coseismic slip.
  • as_cum: Afterslip calculation.
  • calAS_AV: Viscoelastic relaxation due to afterslip.

Interseismic (Alpha)

• Engine: pscmp_visco_interseismic.py
• Function: calviscoGfromPscmp for earthquake cycle velocity calculations.

---

📝 Citation

If you use ECAT in your research, please cite:

He K., C. Xu, Y. Wen, Y. Zhao, G. Xu, L. Sun, and J. Wang (2025). A Unified Framework for Adaptive Fault Modeling: Methods and Applications. SCIENCE CHINA Earth Sciences . DOI: 10.1007/s11430-025-1773-0.

---