dyncfs

Documentation · Quickstart · 中文入门 · Examples

This Python package serves as the frontend for computing static and dynamic Coulomb Failure Stress changes in layered media. The current backend dispatch uses EDGRN2/EDCMP2 for static stress, QSEIS2025 for layered dynamic stress, and QSSP2020 for spherical dynamic stress, based on programs developed by Rongjiang Wang and modified by Jiangcheng Zhou. The generation and retrieval of Green's function libraries are handled by the pygrnwang package, while travel-time calculations and geographic coordinate transformations are implemented using obspy.

The Wenchuan and Ludian examples give case parameters and results with figures.

Installation

1. For user mode

pip install dyncfs

2. For developer mode.

conda create -n cfs python=3.13
conda activate cfs
conda install gfortran obspy tqdm -c conda-forge
conda install geographiclib mpi4py -c conda-forge # optional
git clone https://github.com/Zhou-Jiangcheng/pygrnwang
cd pygrnwang
pip install -e .
cd ..
git clone https://github.com/Zhou-Jiangcheng/dyncfs.git
cd dyncfs
pip install -e .

Usage

Start with the small executable tutorial, or adapt examples/wenchuan/wenchuan.ini / examples/ludian/ludian.ini. Prepare source_plane[m].csv, obs_plane[n].csv and model.nd in the input directory, and set absolute input/output paths. The full schema is in Input files.

1. Command-line usage

dyncfs --help

usage: dyncfs [-h] --config CONFIG [--create-static-lib] [--compute-static-cfs] [--compute-static-cfs-fix-depth] [--run-static] [--create-dynamic-lib] [--compute-dynamic-cfs] [--compute-dynamic-cfs-fix-depth] [--run-dynamic] [--run-all]

dyncfs command line tool

options:
  -h, --help            show this help message and exit
  --config CONFIG       Path to the configuration file
  --create-static-lib   Create static stress library
  --compute-static-cfs  Compute static dCFS on obs faults
  --compute-static-cfs-fix-depth
                        Compute static dCFS at fixed depth
  --run-static          Create static stress library and Compute static dCFS on obs faults and Compute static dCFS at fixed depth
  --create-dynamic-lib  Create dynamic stress library
  --compute-dynamic-cfs
                        Compute dynamic dCFS on obs faults
  --compute-dynamic-cfs-fix-depth
                        Compute dynamic dCFS at fixed depth
  --run-dynamic         Create dynamic stress library and Compute dynamic dCFS on obs faults and Compute dynamic dCFS at fixed depth
  --run-all             Create static and dynamic stress library and Compute static and dynamic dCFS

2. Import and use classes and functions in .py files

Replace case.ini below with your prepared configuration file.

from dyncfs.cfs_static import *

if __name__ == "__main__":
    config = CfsConfig()
    config.read_config("case.ini")
    create_static_lib(config)
    compute_static_cfs(config)

from dyncfs.cfs_dynamic import *

if __name__ == "__main__":
    config = CfsConfig()
    config.read_config("case.ini")
    create_dynamic_lib(config)
    compute_dynamic_cfs_parallel(config)

Note on parallel computing (compute_dynamic_cfs_parallel, compute_dynamic_cfs_fix_depth_parallel, run_all_dynamic, and processes_num > 1 in the command-line tool):

• Worker processes are started with the spawn method on all platforms (Windows, Linux and macOS), so the calling script must put its code under if __name__ == "__main__": as in the examples above. Otherwise the workers re-run the script and fail with RuntimeError: An attempt has been made to start a new process before the current process has finished its bootstrapping phase.
• Each worker process is limited to one BLAS/OpenMP thread (OMP_NUM_THREADS, MKL_NUM_THREADS, OPENBLAS_NUM_THREADS and VECLIB_MAXIMUM_THREADS are set to 1 only for the workers) to avoid oversubscription. Use processes_num to control the CPU usage, e.g. not more than the number of cores allocated by the job scheduler on a cluster.

References:

Wang, R. (1999). A simple orthonormalization method for stable and efficient computation of Green’s functions. Bulletin of the Seismological Society of America , 89 (3), 733–741. https://doi.org/10.1785/BSSA0890030733

Wang, R. (2003). Computation of deformation induced by earthquakes in a multi-layered elastic crust—FORTRAN programs EDGRN/EDCMP. Computers & Geosciences, 29(2), 195–207. https://doi.org/10.1016/S0098-3004(02)00111-5

Wang, R., & Wang, H. (2007). A fast converging and anti-aliasing algorithm for green’s functions in terms of spherical or cylindrical harmonics. Geophysical Journal International, 170(1), 239–248. https://doi.org/10.1111/j.1365-246X.2007.03385.x

Wang, R., Heimann, S., Zhang, Y., Wang, H., & Dahm, T. (2017). Complete synthetic seismograms based on a spherical self-gravitating earth model with an atmosphere–ocean–mantle–core structure. Geophysical Journal International, 210(3), 1739–1764. https://doi.org/10.1093/gji/ggx259

Zhou, J., Wang, R., & Zhang, Y. (2026). DynCFS: a program for modeling dynamic coulomb failure stress changes in layered elastic media. Geophysical Journal International, ggaf534. https://doi.org/10.1093/gji/ggaf534

Acknowledgment

Thanks to Haitao Qin from Tongji University for reporting a bug, which has been fixed in the latest version.