Configuration reference#

Create a CfsConfig, then call read_config(path). A bare constructor leaves most attributes as None; it is not a ready-to-run configuration.

The parser expects all general sections even for a static-only job. Python-style lists are parsed with ast.literal_eval; booleans use ConfigParser syntax. Paths are literal strings: use forward slashes on Windows, without Python quotes, environment-variable placeholders or ~. Relative paths resolve against the process working directory, not the INI’s directory.

Reading a configuration creates the static/dynamic library and result directories. It does not comprehensively validate input geometry.

Paths and source/receiver settings#

Section/key	Meaning
`[path] path_input`	Directory containing the input files
`path_output`	Root for libraries, per-point files and results
`[input_addition] optimal_type`	0 fixed mechanism, 1 optimal rake, 2 optimal planes
`tectonic_stress_type`	1 full tensor, 2 principal-axis directions; read only for modes 1/2
`tectonic_stress`	Six NED tensor entries in MPa (type 1), or six angles in degrees (type 2)
`mu_f`, `B_pore`	Dimensionless friction and Skempton coefficients
`source_inds`, `obs_inds`	Lists of selected CSV IDs
`source_shapes`, `obs_shapes`	One `[n_strike, n_dip]` per selected plane
`source_ref`, `obs_ref`	Reference latitude/longitude in degrees for geometry and plotting
`earth_model_layer_num`	Model selection count forwarded to preprocessing
`use_spherical`	False: QSEIS2025; True: QSSP2020 for dynamic stress
`slip_thresh`	Slip threshold in m; positive values zero smaller slip/moment
`cut_stf`	Number of STF samples retained; values ≤0 disable truncation
`correct_zero_freq`	Optional boolean, default False; use static tensors for dynamic correction

Mode 1 requires tectonic_stress_type=1; type 2 raises ValueError. Static calculations remain EDGRN/EDCMP regardless of use_spherical.

Fixed-depth observation grid#

All [fixed_obs_depth] fields are parsed even if the grid is disabled.

Key	Meaning
`fixed_obs_depth`	Depth in km; CLI and complete workflows enable the grid only for values >0
`obs_lat_range`, `obs_lon_range`	Closed `[minimum, maximum]` ranges, degrees
`obs_delta_lat`, `obs_delta_lon`	Positive target increments, degrees
`receiver_mechanism`	Optional `[strike, dip, rake]` in degrees, or `None` (default)

Grid counts are computed by cal_grid_num, then coordinates use linspace including both endpoints. Choose ranges divisible by the increments. Longitude varies fastest; see output layouts. Direct low-level grid functions do not enforce the CLI’s positive-depth gate.

receiver_mechanism sets the receiver fault for --compute-static-cfs-fix-depth, --compute-dynamic-cfs-fix-depth and the fixed-depth step of the complete workflows. Mode 0 uses all three angles, mode 1 uses strike and dip and optimizes rake, and mode 2 ignores it. When it is None or absent, modes 0/1 derive a mechanism from the moment-weighted sum of the selected source mechanisms. A receiver_mechanism argument passed to a Python fixed-depth function takes precedence over the INI value.

Library coverage#

`[grn_region]` key	Meaning
`grn_source_depth_range`	Closed source-depth range, km
`grn_delta_source_depth`	Source-depth increment, km
`grn_obs_depth_range`	Closed receiver-depth range, km
`grn_delta_obs_depth`	Receiver-depth increment, km
`grn_dist_unit`	`km` or `deg`
`grn_dist_range`	Closed epicentral-distance range, in the selected unit
`grn_delta_dist`	Distance increment in the selected unit

Degree distances are converted to km during parsing. Depth lists use rounded interval counts and linspace. Select integral interval ratios, cover every source/receiver pair, and allow margin around queries. EDGRN requires at least two source depths; keep the minimum distance positive for the shared introductory configuration.

Derived static attributes include static_source_depth_range, static_source_delta_depth, static_dist_range, static_delta_dist and static_obs_depth_list. Dynamic attributes include event_depth_list and receiver_depth_list. Changing a general field after parsing does not automatically recompute all derived attributes; edit the INI and read it again when changing library geometry.

Sampling and parallelism#

Section/key	Meaning
`[time_window] sampling_interval_stf`	STF sample interval, s
`sampling_interval_cfs`	Dynamic sample interval, s
`sampling_num`	Number of dynamic output samples
`max_frequency`	QSSP2020 maximum frequency, Hz; missing/unparseable value uses Nyquist
`[parallel] processes_num`	Positive process count; 1 selects sequential dynamic synthesis
`check_finished`	Reuse eligible backend outputs and matching dynamic stress caches

The time window is (sampling_num-1)*sampling_interval_cfs. max_frequency is not forwarded to the QSEIS2025 builder.

Solver defaults#

With [default_config] default_config=True, the parser calls set_default() and ignores custom [static] and [dynamic] values.

Setting	Default
Static `wavenumber_sampling_rate`	12; also forwarded to QSEIS2025
Static `layered`	True
`max_slowness`	None for QSEIS2025; `1/min(nonzero Vs)+0.1` s/km for QSSP2020
`anti_alias`, `free_surface`	0.01, True
`wavelet_duration`	5 CFS samples; converted to seconds for QSSP
`output_observables`	QSEIS: `[0,0,0,1,0]`; QSSP: 11 entries with index 5 enabled
`slowness_int_algorithm`	0
`eps_estimate_wavenumber`	1e-6
`source_radius_ratio`	0.05
`slowness_window`	None
`time_reduction_velo`	0
`wavelet_type`	2
`flat_earth_transform`	True
QSSP `time_reduction`	-20 s
QSSP `source_radius`	0 km
`turning_point_filter`, `turning_point_d1`, `turning_point_d2`	0, 0, 0
`gravity_fc`, `gravity_harmonic`	0, 0
`cal_sph`, `cal_tor`	1, 1
`min_harmonic`, `max_harmonic`	6000, 25000
`physical_dispersion`	0
Derived `spec_time_window`	Same as `time_window`

These are implementation defaults, not universally converged scientific settings. DynCFS translates its common free_surface boolean differently for the two backend input conventions.

Custom solver settings#

With default_config=False, provide all settings shown in the bundled [static] and [dynamic] sections, including those for the other dynamic backend: the parser reads both groups.

For static layered=False, supply Lamé parameters lam and mu in Pa. The library wrapper still prepares and invokes EDGRN before EDCMP. For custom dynamics, max_slowness=None becomes None and slowness_window=[0,0,0,0] becomes None. Keep the stress observable enabled with the correct backend-specific list length.

The annotated bundled file is a detailed reference, but its paths and grid sizes must be adapted:

[static]
################################################################################
# wavenumber_sampling_rate: Sampling rate for wavenumber integration (the ratio
# between the Nyquist wavenumber and the really used wavenumber sample; the
# suggested value is 10-128: the larger this value is chosen, the more accurate
# are the results but also the more computation time will be required).
# The parameter value setting in [dynamic] part is the same as here.
# wavenumber_sampling_rate: default 12
################################################################################
wavenumber_sampling_rate = 12
################################################################################
# layered: Whether to use a layered earth model to calculate static stress,
# default True
################################################################################
layered = True
################################################################################
# If layered is False, set the elasticity parameter
# All units in Pa
# lam: default 30516224000
# mu: default 33701888000
################################################################################
lam = 30516224000
mu = 33701888000
################################################################################
## dynamic
################################################################################
[dynamic]
################################################################################
# Both in QSEIS2025 and QSSP2020
################################################################################
# max_slowness: Max slowness, should be larger than 1/vmin, unit in s/km,
# default None for QSEIS2025
# default equals to (1/vmin+0.1) for QSSP2020, precision to two decimal places.
################################################################################
max_slowness = None
################################################################################
# Anti false signal factor
# anti_alias: default 0.01
################################################################################
anti_alias = 0.01
################################################################################
# free_surface: Whether to use free surface reflection filter,
# default True
################################################################################
free_surface = True
################################################################################
# wavelet duration [unit = time sample rather than sec!], that is about
# equal to the half-amplitude cut-off period of the wavelet (> 0. if <= 0,
# then default value = 2 time samples will be used). default 5
################################################################################
wavelet_duration = 5
################################################################################
# output_observables: Output data type, 0 indicates no output, 1 indicates
# output
# disp | velo | acce | strain | strain_rate |
# stress | stress_rate | rotation | rotation_rate |
# gravitation | gravimeter | for QSSP2020,
# output_observables: default [0,0,0,0,0,1,0,0,0,0,0] for QSSP2020;
# disp | volume | strain | stress | rotation | for QSEIS2025,
# output_observables: default [0,0,0,1,0] for QSEIS2025,
# only output stress
################################################################################
output_observables = [0,0,0,1,0]
################################################################################
# Only in QSEIS2025
################################################################################
# slowness_int_algorithm: Select slowness integration algorithm
# (0 = suggested for full wave-field modelling; 1 or 2 = suggested when using a
# slowness window with narrow taper range - a technique for suppressing
# space-domain aliasing)
################################################################################
slowness_int_algorithm = 0
################################################################################
# eps_estimate_wavenumber: Be used to automatically estimate the wavenumber
# truncation limit when the full-wavefield option is selected (e.g., 1e-6).
# Smaller values yield a higher wavenumber cutoff, improving accuracy at the
# expense of greater computational cost.
################################################################################
eps_estimate_wavenumber = 1e-6
################################################################################
# source_radius_ratio: Set the ratio of the source disk radius to the minimum
# epicentral distance (e.g., 0.05); larger values converge faster but deviate
# more from a point source.
################################################################################
source_radius_ratio = 0.001
################################################################################
# slowness_window: 4 parameters for low and high slowness (Note 1)
# cut-offs [s/km] with tapering: 0 < slw1 < slw2 defining cosine taper at the
# lower end, and 0 < slw3 < slw4 defining the cosine taper at the higher end.
# default values will be used in case of inconsistent input of the cut-offs
# (possibly with much more computational effort)
################################################################################
slowness_window = [0, 0, 0, 0]
################################################################################
# time_reduction_velo: Time reduction velocity from event origin when computing
# dynamic stress, unit km/s. Time reduction = distance*time_reduction_velo
# default 0
################################################################################
time_reduction_velo = 0
################################################################################
# wavelet_type:
# 1 = default wavelet: normalized square half-sinusoid for simulating a physical
# delta impulse;
# 2 = tapered Heaviside wavelet, i.e. integral of wavelet 1.
# default 2
################################################################################
wavelet_type = 2
################################################################################
# flat_earth_transform: switch for flat-earth-transform,
# default True
################################################################################
flat_earth_transform = True
################################################################################
# Only in QSSP2020
################################################################################
# time_reduction: Time reduction from event origin when computing dynamic stress,
# default -20
################################################################################
time_reduction = -20
################################################################################
# source_radius: Radius of source, unit in km, default 0
################################################################################
source_radius = 0
################################################################################
# Whether to use turning-point filter, the range (d1, d2) of max. penetration
# depth (km) (d1 is meaningless if it is smaller than the receiver/source depth,
# and d2 is meaningless if it is equal to or larger than the earth radius)
# turning_point_filter: default False
# turning_point_d1: default 0
# turning_point_d2: default 0
################################################################################
turning_point_filter = False
turning_point_d1 = 0
turning_point_d2 = 0
################################################################################
# gravity_fc: Critical frequency (Hz), below which the self-gravitating effect
# should be included, default 0
# gravity_harmonic: Critical harmonic degree, default 0
################################################################################
gravity_fc = 0
gravity_harmonic = 0
################################################################################
# cal_sph: selection (1/0 = yes/no) of spheroidal modes (P-SV waves),
# default True
# cal_tor: selection of toroidal modes, default True
################################################################################
cal_sph = True
cal_tor = True
################################################################################
# Minimum and maximum cutoff harmonic degrees when computing Green's function
# Note: if the near-field static displacement is desired, the minimum cutoff
# harmonic degree should not be smaller than, e.g., 2000.
# min_harmonic: default 6000
# max_harmonic: default 25000
################################################################################
min_harmonic = 6000
max_harmonic = 25000
################################################################################
# Whether to include the physical dispersion according to
# Kamamori & Anderson (1977) physical_dispersion: default False
################################################################################
physical_dispersion = False
################################################################################

See dynamic calculations for zero-frequency correction and parallel execution for process behavior.