Metadata-Version: 2.4
Name: dyncfs
Version: 3.0.2
Summary: A Python library for computing Coulomb Failure Stress Change.
Author-email: Zhou Jiangcheng <zhou-jiangcheng@outlook.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Zhou-Jiangcheng/dyncfs
Project-URL: Documentation, https://zhou-jiangcheng.github.io/dyncfs/
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygrnwang>=3.0.2
Requires-Dist: matplotlib>=3.9.2
Dynamic: license-file

# dyncfs

**[Documentation](https://zhou-jiangcheng.github.io/dyncfs/)** · [Quickstart](https://zhou-jiangcheng.github.io/dyncfs/quickstart.html) · [中文入门](https://zhou-jiangcheng.github.io/dyncfs/zh/index.html) · [Examples](https://github.com/Zhou-Jiangcheng/dyncfs/tree/main/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](https://github.com/Zhou-Jiangcheng/pygrnwang) package, while travel-time calculations and geographic coordinate transformations are implemented using [obspy](https://github.com/obspy/obspy).

The [Wenchuan](https://zhou-jiangcheng.github.io/dyncfs/cases/wenchuan.html) and
[Ludian](https://zhou-jiangcheng.github.io/dyncfs/cases/ludian.html) 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](docs/quickstart.md), 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](docs/input-files.md).

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.
