PyQuake3D is a high-performance Python-based Boundary Element Method (BEM) code for simulating sequences of seismic and aseismic slip (SEAS) on a complex 3D fault geometry governed by rate- and state-dependent friction. It combines physics-based modeling with modern parallel computing tools (MPI, GPU acceleration via CuPy) to solve a variety of earthquake cycle and rupture problems. This document provides an overview of how to use the script, as well as a detailed description of the input parameters.
PyQuake3D was originally developed by Dr. Rongjiang Tang and Dr. Luca Dal Zilio.
We welcome contributions to the project—please follow the contribution guidelines and help us maintain a clean, consistent codebase.
For questions, suggestions, or collaboration opportunities, feel free to reach out:
Please refer to the Code Manual for more details.
- 3D non-planar quasi-dynamic earthquake cycle simulations
- Support for rate-and-state aging friction laws
- Support for Hierarchical matrix storage and calculation
- Support for MPI-based GPU acceleration
- Support MPI-based CPU acceleration
- Suitable for large model earthquake cycle simulation
- Support for pore fluid pressure varing with slip due to inelastic processes including dilatancy, pore compaction.
- Supports fluid thermal pressurization caused by friction heating.
- Singularity-free regularized Green's function (only full space).
PyQuake3D supports Python 3.8 and above, so there is no need to specify any version when installing the dependent libraries.
Use pip for the quick installation:
python -m pip install -e .Install cupy if you want to use GPU acceleration, we recommened to use conda (e.g. CUDA 11.8):conda install -c conda-forge cupy cudatoolkit=11.8
The operation of PyQuake3D relies on Green's functions; the C++ library for Green's functions must be installed.
-
Install an MPI implementation and g++ compiler (including gcc and other related tools). Common options are:
sudo apt updatesudo apt install g++sudo apt install openmpi-bin libopenmpi-dev
-
Navigate to the
greenfuncdirectory, runpython -m pip install -e.to buildgreenfuncions_lib.- If you use macos system, run
bash install.shto buildgreenfuncions_lib.
- If you use macos system, run
-
For details on how to call and use the Green's function, you can refer to and run the Python examples provided in the
greenfunc/examplesfolder.
PyQuake3D provides two versions of the code, GPU and CPU, which can be run using different main functions：main_gpu_mpi or main_mpi.
To run the PyQuake3D MPI script, use the following command:
mpirun -n <N> python -m pyquake3d.main_mpi -g <input_geometry_file> -p <input_parameter_file>Where 10 is the number of virtual cpus. Note that using the mpiexec instead in Windows environment.
For example:
To execute benchmarks like BP5-QD, use:
```bash
In the PyQuake3D root directory, To run the BP5-QD benchmark:
mpirun -n 10 python -m pyquake3d.main_mpi -g para/BP5-QD/bp5t.msh -p examples/BP5-QD/parameter.txt
To run the HF-model:
mpirun -n 10 python -m pyquake3d.main_mpi -g para/HF-model/HFmodel.msh -p para/HF-model/parameter.txt
To run the EAFZ-model:
mpirun -n 10 python -m pyquake3d.main_mpi -g para/EAFZ-model/turkey.msh -p para/EAFZ-model/parameter.txt
To run the Lab-model:
mpirun -n 10 python -m pyquake3d.main_mpi -g para/Lab-model/lab.msh -p para/Lab-model/parameter.txt
python -g --inputgeo <input_geometry_file> -p --inputpara <input_parameter_file>
mpirun -n <N> python -m pyquake3d.main_gpu_mpi -g <input_geometry_file> -p <input_parameter_file>Ensure you modify the input parameter (parameter.txt) as follows:
- GPU: True
- GPU_cores: 1
The simulation parameters are implemented by modifying the parameter.txt file, rather than by changing the source code. The heterogeneous stress and friction parameters are imported from external files. Please refer to Code Manual for description of parameter details.
Explore selected simulations performed with PyQuake3D:
- Seismic cycles on a planar fault with frictional heterogeneity
- Seismic cycles on the East Anatolian Fault Zone
This project is licensed under the MIT License. See the LICENSE file for more details.
We acknowledge the support and feedback provided by the broader scientific community and all contributors to this work.
Development of the Python-based BEM algorithm was informed by the HBI code introduced in:
Ozawa, S., Ida, A., Hoshino, T., & Ando, R. (2023). Large-scale earthquake sequence simulations on 3-D non-planar faults using the boundary element method accelerated by lattice H-matrices. Geophysical Journal International, 232(3), 1471–1481.
https://doi.org/10.1093/gji/ggad042
The implementation of the stress Green’s functions builds on MATLAB routines from:
Nikkhoo, M., & Walter, T. R. (2015). Triangular dislocation: an analytical, artefact-free solution. Geophysical Journal International, 201(2), 1119–1141.
https://doi.org/10.1093/gji/ggv035
We sincerely thank Ryosuke Ando and So Ozawa for their valuable guidance in the development of the code. We also thank Steffen Börm for his assistance with H-matrix implementation and T. Ben Thompson for his assistance with the H-matrix compression via Adaptive Cross Approximation (ACA).
We gratefully acknowledge the institutional and technical support provided by NTU and EOS, and the contributions of researchers and collaborators who help improve the codebase.
If you find this work useful, please cite:
@article{tang2025pyquake3d,
title={PyQuake3D: A Python tool for 3-D earthquake sequence simulations of seismic and aseismic slip},
author={Tang, Rongjiang and Gan, Lu and Li, Fusheng and Dal Zilio, Luca},
journal={Journal of Geophysical Research: Machine Learning and Computation},
volume={2},
number={4},
pages={e2025JH000871},
year={2025},
publisher={Wiley Online Library}
}
Tang, R., Gan, L., Li, F., & Dal Zilio, L. (2025). PyQuake3D: A Python tool for 3‐D earthquake sequence simulations of seismic and aseismic slip. Journal of Geophysical Research: Machine Learning and Computation, 2(4), e2025JH000871.