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.
A step by step tutorial on how to install and run BP5-QD_low_resolution case and circular_asperity_low_resolution case. The former uses parameters to set the initial model, while the latter uses external files to import the initial model.
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 TDstressFS_C.cpp in folder src is a C++ source file that computes Green's functions, translated from the Python script TDstressFS.py to leverage C++'s performance for efficient numerical calculations. It is compiled into a dynamic library, TDstressFS_C.so, using a provided Makefile, which must be executed with the make command before running the code to ensure compatibility across different computing environments. The generated library is called by the Python script Hmatrix.py via dynamic loading (e.g., using ctypes). To use it, navigate to the code directory src, run make to build TDstressFS_C.so.
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 examples/BP5-QD/bp5t.msh -p examples/BP5-QD/parameter.txt
To run the HF-model:
mpirun -n 10 python -m pyquake3d.main_mpi -g examples/HF-model/HFmodel.msh -p examples/HF-model/parameter.txt
To run the EAFZ-model:
mpirun -n 10 python -m pyquake3d.main_mpi -g examples/EAFZ-model/turkey.msh -p examples/EAFZ-model/parameter.txt
To run the Lab-model:
mpirun -n 10 python -m pyquake3d.main_mpi -g examples/Lab-model/lab.msh -p examples/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.
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.
Explore selected simulations performed with PyQuake3D:
- Seismic cycles on a planar fault with frictional heterogeneity
- Seismic cycles on the East Anatolian Fault Zone
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.