Library preparation and execution

Prepare inputs first, run a matching executor, then read the outputs. All paths passed to executors should be absolute. Use the backend tutorials to select numerical parameters and to understand model and spectrum reuse.

The native programs can change the process working directory. The Python execution functions report progress; inspect result files and logs to establish calculation success. MPI entries require mpi4py and an MPI launch with the prepared group width.

create_edgrn_bulk

pygrnwang.create_edgrn_bulk.pre_process_edgrn2(processes_num, path_green, grn_source_depth_range, grn_source_delta_depth, grn_dist_range, grn_delta_dist, obs_depth_list, wavenumber_sampling_rate=12, path_nd=None, earth_model_layer_num=None)

Prepare the edgrn library grid, input files and job groups.

Parameters:

• processes_num (int) – Positive worker count used to group jobs; MPI rank count must match the prepared group width.

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• grn_source_depth_range (list of float) – Minimum and maximum source depths in km.

• grn_source_delta_depth (float) – Positive source-depth grid increment in km.

• grn_dist_range (list of float) – Minimum and maximum epicentral distances in km.

• grn_delta_dist (float) – Positive regular epicentral-distance increment in km.

• obs_depth_list (list of float) – Nonempty receiver depth list in km, positive down.

• wavenumber_sampling_rate (float, optional) – Dimensionless spatial Nyquist oversampling factor for wavenumber integration. Default: 12.

• path_nd (str or None, optional) – Six-column named-discontinuity model path: depth (km), Vp/Vs (km/s), density (g/cm3), Qp/Qs. Bulk preprocessing requires a real path even though the signature default is None. Default: None.

• earth_model_layer_num (int or None, optional) – Number of numeric model rows retained, not the number of discontinuities; None retains all. Default: None.

Returns:

group_list (list) – Jobs grouped by processes_num; the same groups are saved as a pickle file.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• ValueError – The grid has fewer than 2 or more than 10000 distances, fewer than 2 or more than 401 source depths (the limits of edgrn2 and edcmp2), or an output path is longer than the 160 characters edgrn2 can hold.

Notes

See the edgrn tutorial for a complete prepare, run and read workflow. Preprocessing writes inputs and travel-time/model metadata; run the matching create_grnlib function to calculate Green functions.

pygrnwang.create_edgrn_bulk.create_grnlib_edgrn2_sequential(path_green, check_finished=False, max_retries=2)

Compute the prepared edgrn library sequentially.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

elapsed (datetime.timedelta) – Wall-clock duration of the computation loop.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – Jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_edgrn2).

Notes

See the edgrn tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_edgrn_bulk.create_grnlib_edgrn2_parallel(path_green, check_finished=False, memory_per_job_gb=0.05, max_retries=2)

Compute the prepared edgrn library with local worker processes.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• memory_per_job_gb (float or None, optional) – Peak memory of one edgrn2 process in GiB. A RuntimeWarning is issued when min(processes_num, number of jobs) such processes may not fit in the currently available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again; None skips the warning. Default: 0.05, above the measured commit of the bundled executable.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

elapsed (datetime.timedelta) – Wall-clock duration of the computation loop.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – Jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_edgrn2).

Notes

See the edgrn tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A job fails when the executable cannot start, exits with an error (for example after being killed for lack of memory) or leaves incomplete output files; it never gets a .finished marker. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs. On Windows call under an if __name__ == “__main__” guard.

pygrnwang.create_edgrn_bulk.create_grnlib_edgrn2_parallel_multi_nodes(path_green, check_finished=False, memory_per_job_gb=0.05, max_retries=2)

Compute the prepared edgrn library with MPI.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• memory_per_job_gb (float or None, optional) – Peak memory of one edgrn2 process in GiB. A RuntimeWarning is issued when the ranks on a node may not fit in its available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again; None skips the warning. Default: 0.05, above the measured commit of the bundled executable.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

elapsed (datetime.timedelta) – Wall-clock duration of the computation loop.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – mpi4py is unavailable, or (on rank 0) jobs still fail after the retries or the finished library is incomplete.

• ValueError – MPI rank count does not match the prepared group width.

Notes

See the edgrn tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A failed job does not stop the others: after all ranks finish, the jobs that did not complete are shared among the ranks and computed again, up to max_retries times. Rank 0 checks the library after all ranks finish; after an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_edgrn_bulk.check_grnlib_edgrn2(path_green)

Check that an edgrn library holds complete Green’s function tables.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

Returns:

problems (list of str) – One line per missing or incomplete table; empty when the library is complete.

Raises:

OSError – green_lib_info.json cannot be read.

Notes

For every receiver depth, edgrn.ss, edgrn.ds and edgrn.cl must hold one row per distance and source depth listed in their own parameter line. Rerun the create_grnlib function with check_finished=True to recompute only incomplete jobs.

create_edcmp_bulk

pygrnwang.create_edcmp_bulk.pre_process_edcmp2(processes_num, path_green, grn_source_depth_range, grn_source_delta_depth, grn_dist_range, grn_delta_dist, obs_depth_list, output_observables=(1, 0, 0, 0), layered=True, lam=30516224000, mu=33701888000)

Prepare the edcmp library grid, input files and job groups.

Parameters:

• processes_num (int) – Positive worker count used to group jobs; MPI rank count must match the prepared group width.

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• grn_source_depth_range (list of float) – Minimum and maximum source depths in km.

• grn_source_delta_depth (float) – Positive source-depth grid increment in km.

• grn_dist_range (list of float) – Minimum and maximum epicentral distances in km.

• grn_delta_dist (float) – Positive regular epicentral-distance increment in km.

• obs_depth_list (list of float) – Nonempty receiver depth list in km, positive down.

• output_observables (sequence of int, optional) – Four 0/1 flags in displacement, strain, stress, tilt order. Default: (1, 0, 0, 0).

• layered (bool, optional) – True uses the EDGRN layered-medium library; False selects the homogeneous half-space formula. Default: True.

• lam (float, optional) – First Lame parameter in Pa for the homogeneous half-space. Default: 30516224000.

• mu (float, optional) – Shear modulus in Pa for the homogeneous half-space. Default: 33701888000.

Returns:

group_list (list) – Jobs grouped by processes_num; the same groups are saved as a pickle file.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• ValueError – The grid has more than 500000 distances, the receiver limit of edcmp2, or an input, output or Green’s function path is longer than the 160 characters edcmp2 can hold.

Notes

See the edcmp tutorial for a complete prepare, run and read workflow. Preprocessing writes inputs and travel-time/model metadata; run the matching create_grnlib function to calculate Green functions. Run EDGRN preparation first: this function reads and updates its metadata, even for homogeneous-half-space mode.

pygrnwang.create_edcmp_bulk.create_grnlib_edcmp2_sequential(path_green, check_finished=False, max_retries=2)

Compute the prepared edcmp library sequentially.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – The layered model’s edgrn library is incomplete, jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_edcmp2).

Notes

See the edcmp tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. The output stays in ASCII; convert it with convert_pd2bin_edcmp2_all. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_edcmp_bulk.create_grnlib_edcmp2_parallel(path_green, check_finished=False, convert_bulk=True, remove=False, memory_per_job_gb=1.0, max_retries=2)

Compute the prepared edcmp library with local worker processes.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• convert_bulk (bool, optional) – Generate combined EDCMP float32 libraries after jobs finish. Default: True.

• remove (bool, optional) – Delete source ASCII files after converting them; keep False when inspecting backend output. Default: False.

• memory_per_job_gb (float or None, optional) – Peak memory of one edcmp2 process in GiB. A RuntimeWarning is issued when min(processes_num, number of jobs) such processes may not fit in the currently available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again; None skips the warning. Default: 1.0, the measured commit of the bundled executable.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

elapsed (datetime.timedelta) – Wall-clock duration of the computation loop.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – The layered model’s edgrn library is incomplete, jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_edcmp2).

Notes

See the edcmp tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A job fails when the executable cannot start, exits with an error (for example after being killed for lack of memory) or leaves incomplete output files; it never gets a .finished marker. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs. On Windows call under an if __name__ == “__main__” guard.

pygrnwang.create_edcmp_bulk.create_grnlib_edcmp2_parallel_multi_nodes(path_green, check_finished=False, memory_per_job_gb=1.0, max_retries=2)

Compute the prepared edcmp library with MPI.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• memory_per_job_gb (float or None, optional) – Peak memory of one edcmp2 process in GiB. A RuntimeWarning is issued when the ranks on a node may not fit in its available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again; None skips the warning. Default: 1.0, the measured commit of the bundled executable.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – mpi4py is unavailable, the layered model’s edgrn library is incomplete, or (on rank 0) jobs still fail after the retries or the finished library is incomplete.

• ValueError – MPI rank count does not match the prepared group width.

Notes

See the edcmp tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. The output stays in ASCII; convert it with convert_pd2bin_edcmp2_all. A failed job does not stop the others: after all ranks finish, the jobs that did not complete are shared among the ranks and computed again, up to max_retries times. Rank 0 checks the library after all ranks finish; after an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_edcmp_bulk.convert_pd2bin_edcmp2_all(path_green, remove=False)

Convert all completed edcmp outputs to float32 binary libraries.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• remove (bool, optional) – Delete source ASCII files after converting them; keep False when inspecting backend output. Default: False.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – A job’s output is incomplete; nothing is converted.

Notes

See the edcmp tutorial for a complete prepare, run and read workflow. Conversion is a storage operation; it does not resample or change physical units.

pygrnwang.create_edcmp_bulk.check_grnlib_edcmp2(path_green, check_values=False)

Check that an edcmp library holds every file the readers need.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_values (bool, optional) – Also read every binary file and report NaN or infinite values; this reads the whole library. Default: False.

Returns:

problems (list of str) – One line per missing or incomplete file; empty when the library is complete.

Raises:

OSError – green_lib_info.json cannot be read.

Notes

For every source depth, receiver depth and base mechanism, each output selected by output_observables must exist as <output>.bin with one row per distance, or as a complete hs.<output> file. Combined edcmp2_<output>.bin files, when present, must hold every job. The edgrn tables are checked by check_grnlib_edgrn2. Rerun the create_grnlib function with check_finished=True to recompute only incomplete jobs.

create_qseis06_bulk

Deprecated backend: QSEIS06. Use QSEIS2025 for new calculations. Rebuild the Green library and revalidate numerical settings, source and time conventions, and results when migrating.

pygrnwang.create_qseis06_bulk.pre_process_qseis06(processes_num, path_green, event_depth_list, receiver_depth_list, dist_range, delta_dist, N_each_group, time_window, sampling_interval, slowness_int_algorithm=0, slowness_window=None, time_reduction_velo=0, wavenumber_sampling_rate=12, anti_alias=0.01, free_surface=True, wavelet_duration=0, wavelet_type=1, flat_earth_transform=True, path_nd=None, earth_model_layer_num=None, check_finished_tpts_table=False)

Prepare the qseis06 library grid, input files and job groups.

Warning

QSEIS06 is deprecated. Use QSEIS2025 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

• processes_num (int) – Positive worker count used to group jobs; MPI rank count must match the prepared group width.

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• event_depth_list (list of float) – Source depth nodes in km, positive down; supply a nonempty sorted list.

• receiver_depth_list (list of float) – Receiver depth nodes in km, positive down; supply a nonempty sorted list.

• dist_range (list of float) – Minimum and maximum epicentral distances in km.

• delta_dist (float) – Positive regular distance increment in km. The last grid point can exceed the requested maximum by less than one increment.

• N_each_group (int) – Positive maximum number of distances in each backend input file; at most 101, the distance limit (nrmax) of the bundled qseis06 build.

• time_window (float) – Output time-window duration in seconds.

• sampling_interval (float) – Time step in seconds; choose it consistently with the highest modeled frequency.

• slowness_int_algorithm (int, optional) – QSEIS integration selector: 0 for the full wavefield; 1 or 2 for narrow tapered slowness windows. Default: 0.

• slowness_window (list of float or None, optional) – Four ordered slowness taper corners in s/km; None writes zeros for backend automatic limits. Default: None.

• time_reduction_velo (float, optional) – Reduction velocity in km/s; nonzero starts each trace at distance/velocity seconds, while zero disables reduction. Default: 0.

• wavenumber_sampling_rate (float, optional) – Dimensionless spatial Nyquist oversampling factor for wavenumber integration. Default: 12.

• anti_alias (float, optional) – Dimensionless time-domain alias suppression factor; use a small positive value below 1. Default: 0.01.

• free_surface (bool or int, optional) – Backend free-surface selection; see Notes for the backend-specific encoding. Default: True.

• wavelet_duration (int, optional) – Wavelet duration in native time samples, not seconds. Nonpositive values request the backend default of two samples. Default: 0.

• wavelet_type (int, optional) – 1 selects the normalized squared half-sinusoid; 2 selects its tapered Heaviside integral. Custom type 0 requires manually supplying wavelet samples; readers treat them as a moment-rate function, like type 1. Default: 1.

• flat_earth_transform (bool, optional) – Apply the backend flat-Earth transformation and receiver-radius distance correction. Default: True.

• path_nd (str or None, optional) – Six-column named-discontinuity model path: depth (km), Vp/Vs (km/s), density (g/cm3), Qp/Qs. Bulk preprocessing requires a real path even though the signature default is None. Default: None.

• earth_model_layer_num (int or None, optional) – Number of numeric model rows retained, not the number of discontinuities; None retains all. Default: None.

• check_finished_tpts_table (bool, optional) – Reuse existing P/S table files without validating their model or grid provenance. Default: False.

Returns:

group_list (list) – Jobs grouped by processes_num; the same groups are saved as a pickle file.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• ValueError – N_each_group exceeds the distance limit of the qseis06 executable, or a job input path is longer than the 160 characters it can read.

Notes

See the qseis06 tutorial for a complete prepare, run and read workflow. Preprocessing writes inputs and travel-time/model metadata; run the matching create_grnlib function to calculate Green functions. free_surface=True retains the free surface; False filters its effects.

pygrnwang.create_qseis06_bulk.pre_process_qseis06_strain_rate(processes_num, path_green, path_bin, event_depth_list, receiver_depth_list, dist_range, delta_dist, N_each_group, time_window, sampling_interval, slowness_int_algorithm=0, slowness_window=None, time_reduction_velo=0, wavenumber_sampling_rate=12, anti_alias=0.01, free_surface=True, wavelet_duration=0, wavelet_type=1, flat_earth_transform=True, path_nd=None, earth_model_layer_num=None, k_dr=0.001, dz=0.1, diff_accu_order=4, check_finished_tpts_table=False)

Prepare the qseis06 library grid, input files and job groups.

Warning

QSEIS06 is deprecated. Use QSEIS2025 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

• processes_num (int) – Positive worker count used to group jobs; MPI rank count must match the prepared group width.

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• path_bin (str) – Legacy executable-path metadata for the finite-difference library; execution is handled by the installed QSEIS wrapper.

• event_depth_list (list of float) – Source depth nodes in km, positive down; supply a nonempty sorted list.

• receiver_depth_list (list of float) – Receiver depth nodes in km, positive down; supply a nonempty sorted list.

• dist_range (list of float) – Minimum and maximum epicentral distances in km.

• delta_dist (float) – Positive regular distance increment in km. The last grid point can exceed the requested maximum by less than one increment.

• N_each_group (int) – Positive maximum number of distances in each backend input file; at most 101, the distance limit (nrmax) of the bundled qseis06 build.

• time_window (float) – Output time-window duration in seconds.

• sampling_interval (float) – Time step in seconds; choose it consistently with the highest modeled frequency.

• slowness_int_algorithm (int, optional) – QSEIS integration selector: 0 for the full wavefield; 1 or 2 for narrow tapered slowness windows. Default: 0.

• slowness_window (list of float or None, optional) – Four ordered slowness taper corners in s/km; None writes zeros for backend automatic limits. Default: None.

• time_reduction_velo (float, optional) – Reduction velocity in km/s; nonzero starts each trace at distance/velocity seconds, while zero disables reduction. Default: 0.

• wavenumber_sampling_rate (float, optional) – Dimensionless spatial Nyquist oversampling factor for wavenumber integration. Default: 12.

• anti_alias (float, optional) – Dimensionless time-domain alias suppression factor; use a small positive value below 1. Default: 0.01.

• free_surface (bool or int, optional) – Backend free-surface selection; see Notes for the backend-specific encoding. Default: True.

• wavelet_duration (int, optional) – Wavelet duration in native time samples, not seconds. Nonpositive values request the backend default of two samples. Default: 0.

• wavelet_type (int, optional) – 1 selects the normalized squared half-sinusoid; 2 selects its tapered Heaviside integral. Custom type 0 requires manually supplying wavelet samples; readers treat them as a moment-rate function, like type 1. Default: 1.

• flat_earth_transform (bool, optional) – Apply the backend flat-Earth transformation and receiver-radius distance correction. Default: True.

• path_nd (str or None, optional) – Six-column named-discontinuity model path: depth (km), Vp/Vs (km/s), density (g/cm3), Qp/Qs. Bulk preprocessing requires a real path even though the signature default is None. Default: None.

• earth_model_layer_num (int or None, optional) – Number of numeric model rows retained, not the number of discontinuities; None retains all. Default: None.

• k_dr (float, optional) – Dimensionless relative radial step: dr = distance * k_dr. Avoid zero epicentral distance. Default: 0.001.

• dz (float, optional) – Receiver-depth finite-difference increment in km. Default: 0.1.

• diff_accu_order (int, optional) – Central-difference accuracy order; one of 2, 4, 6 or 8. Default: 4.

• check_finished_tpts_table (bool, optional) – Reuse existing P/S table files without validating their model or grid provenance. Default: False.

Returns:

group_list (list) – Jobs grouped by processes_num; the same groups are saved as a pickle file.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• ValueError – diff_accu_order is not supported, N_each_group exceeds the distance limit of the qseis06 executable, or a job input path is longer than the 160 characters it can read.

Notes

See the qseis06 tutorial for a complete prepare, run and read workflow. Preprocessing writes inputs and travel-time/model metadata; run the matching create_grnlib function to calculate Green functions. free_surface=True retains the free surface; False filters its effects.

pygrnwang.create_qseis06_bulk.create_grnlib_qseis06_sequential(path_green, check_finished=False, convert_pd2bin=True, remove_pd=True, max_retries=2)

Compute the prepared qseis06 library sequentially.

Warning

QSEIS06 is deprecated. Use QSEIS2025 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• convert_pd2bin (bool, optional) – Convert completed ASCII waveforms to the compact float32 reader format. Default: True.

• remove_pd (bool, optional) – Delete original ASCII output; retain it while validating a new calculation. Default: True.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – Jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_qseis06).

Notes

See the qseis06 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_qseis06_bulk.create_grnlib_qseis06_parallel(path_green, check_finished=False, convert_pd2bin=True, remove_pd=True, memory_per_job_gb=0.75, max_retries=2)

Compute the prepared qseis06 library with local worker processes.

Warning

QSEIS06 is deprecated. Use QSEIS2025 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• convert_pd2bin (bool, optional) – Convert completed ASCII waveforms to the compact float32 reader format. Default: True.

• remove_pd (bool, optional) – Delete original ASCII output; retain it while validating a new calculation. Default: True.

• memory_per_job_gb (float or None, optional) – Peak memory of one qseis06 process in GiB. A RuntimeWarning is issued when min(processes_num, number of jobs) such processes may not fit in the currently available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again; None skips the warning. Default: 0.75, the measured commit of the bundled executable.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – Jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_qseis06).

Notes

See the qseis06 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A job fails when the executable cannot start, exits with an error (for example after being killed for lack of memory) or leaves incomplete output files; it never gets a .finished marker. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs. On Windows call under an if __name__ == “__main__” guard.

pygrnwang.create_qseis06_bulk.create_grnlib_qseis06_parallel_multi_nodes(path_green, check_finished=False, memory_per_job_gb=0.75, max_retries=2)

Compute the prepared qseis06 library with MPI.

Warning

QSEIS06 is deprecated. Use QSEIS2025 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• memory_per_job_gb (float or None, optional) – Peak memory of one qseis06 process in GiB. A RuntimeWarning is issued when the ranks on a node may not fit in its available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again; None skips the warning. Default: 0.75, the measured commit of the bundled executable.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – mpi4py is unavailable, or (on rank 0) jobs still fail after the retries or the finished library is incomplete.

• ValueError – MPI rank count does not match the prepared group width.

Notes

See the qseis06 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. The output stays in ASCII; convert it with convert_pd2bin_qseis06_all. A failed job does not stop the others: after all ranks finish, the jobs that did not complete are shared among the ranks and computed again, up to max_retries times. Rank 0 checks the library after all ranks finish; after an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_qseis06_bulk.convert_pd2bin_qseis06_all(path_green, remove=False)

Convert all completed qseis06 outputs to float32 binary libraries.

Warning

QSEIS06 is deprecated. Use QSEIS2025 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• remove (bool, optional) – Delete source ASCII files after converting them; keep False when inspecting backend output. Default: False.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

OSError – Required files are missing or output paths cannot be read or written.

Notes

See the qseis06 tutorial for a complete prepare, run and read workflow. Conversion is a storage operation; it does not resample or change physical units. Jobs with incomplete output are skipped and keep their files, so they can be inspected and recomputed.

pygrnwang.create_qseis06_bulk.check_grnlib_qseis06(path_green, check_values=False)

Check that a qseis06 library holds every file the readers need.

Warning

QSEIS06 is deprecated. Use QSEIS2025 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_values (bool, optional) – Also read every binary Green’s function file and report NaN or infinite values; this reads the whole library. Default: False.

Returns:

problems (list of str) – One line per missing or incomplete file; empty when the library is complete.

Raises:

OSError – green_lib_info.json or group_list.pkl cannot be read.

Notes

Every prepared job, including the extra finite-difference jobs of pre_process_qseis06_strain_rate, must hold the displacement and volume-change components (tr, tz, tv, tt) as float32 binary files of the size the readers expect, or as complete ASCII files with one row per sample and one column per distance. The P and S travel-time tables must hold one value per distance. Rerun the create_grnlib function with check_finished=True to recompute only incomplete jobs.

create_qseis2025_bulk

pygrnwang.create_qseis2025_bulk.pre_process_qseis2025(processes_num, path_green, event_depth_list, receiver_depth_list, dist_range, delta_dist, N_each_group, time_window, sampling_interval, output_observables, slowness_int_algorithm=0, eps_estimate_wavenumber=1e-06, source_radius_ratio=0.05, slowness_window=None, time_reduction_velo=0, wavenumber_sampling_rate=12, anti_alias=0.01, free_surface=0, wavelet_duration=0, wavelet_type=1, flat_earth_transform=True, path_nd=None, earth_model_layer_num=None, check_finished_tpts_table=False)

Prepare the qseis2025 library grid, input files and job groups.

Parameters:

• processes_num (int) – Positive worker count used to group jobs; MPI rank count must match the prepared group width.

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• event_depth_list (list of float) – Source depth nodes in km, positive down; supply a nonempty sorted list.

• receiver_depth_list (list of float) – Receiver depth nodes in km, positive down; supply a nonempty sorted list.

• dist_range (list of float) – Minimum and maximum epicentral distances in km.

• delta_dist (float) – Positive regular distance increment in km. The last grid point can exceed the requested maximum by less than one increment.

• N_each_group (int) – Positive maximum number of distances in each backend input file; at most 101, the distance limit (nrmax) of the bundled qseis2025 build.

• time_window (float) – Output time-window duration in seconds.

• sampling_interval (float) – Time step in seconds; choose it consistently with the highest modeled frequency.

• output_observables (list of int) – Five 0/1 flags in displacement (or velocity), volume, strain, stress, rotation order; rate versus integrated quantities depend on wavelet_type.

• slowness_int_algorithm (int, optional) – QSEIS integration selector: 0 for the full wavefield; 1 or 2 for narrow tapered slowness windows. Default: 0.

• eps_estimate_wavenumber (float, optional) – Full-wavefield wavenumber truncation tolerance; smaller values increase accuracy and computation. Default: 1e-06.

• source_radius_ratio (float, optional) – Dimensionless Gaussian spatial-smoothing ratio. At each frequency and receiver, the native radius is source_radius_ratio * min(sqrt(r**2 + (zs-zr)**2), Vp_source/(f+df)), using epicentral distance r, source/receiver depths zs/zr, source-layer P-wave speed, frequency f and FFT increment df in consistent units. Coordinates and speed include any selected Earth flattening. The kernel is multiplied by exp(-(k*radius)**2/2) at wavenumber k; this is not a fixed-radius source disk. Zero disables smoothing. Larger values generally reduce the automatically estimated wavenumber cutoff and computation time. Default: 0.05.

• slowness_window (list of float or None, optional) – Four ordered slowness taper corners in s/km; None writes zeros for backend automatic limits. Default: None.

• time_reduction_velo (float, optional) – Reduction velocity in km/s; nonzero starts each trace at distance/velocity seconds, while zero disables reduction. Default: 0.

• wavenumber_sampling_rate (float, optional) – Dimensionless spatial Nyquist oversampling factor for wavenumber integration. Default: 12.

• anti_alias (float, optional) – Dimensionless time-domain alias suppression factor; use a small positive value below 1. Default: 0.01.

• free_surface (bool or int, optional) – Backend free-surface selection; see Notes for the backend-specific encoding. Default: 0.

• wavelet_duration (int, optional) – Wavelet duration in native time samples, not seconds. Nonpositive values request the backend default of two samples. Default: 0.

• wavelet_type (int, optional) – 1 selects the normalized squared half-sinusoid; 2 selects its tapered Heaviside integral. Custom type 0 requires manually supplying wavelet samples; readers treat them as a moment-rate function, like type 1. Default: 1.

• flat_earth_transform (bool, optional) – Apply the backend flat-Earth transformation and receiver-radius distance correction. Default: True.

• path_nd (str or None, optional) – Six-column named-discontinuity model path: depth (km), Vp/Vs (km/s), density (g/cm3), Qp/Qs. Bulk preprocessing requires a real path even though the signature default is None. Default: None.

• earth_model_layer_num (int or None, optional) – Number of numeric model rows retained, not the number of discontinuities; None retains all. Default: None.

• check_finished_tpts_table (bool, optional) – Reuse existing P/S table files without validating their model or grid provenance. Default: False.

Returns:

group_list (list) – Jobs grouped by processes_num; the same groups are saved as a pickle file.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• ValueError – N_each_group exceeds the distance limit of the qseis2025 executable, or a job input path is longer than the 160 characters it can read.

Notes

See the qseis2025 tutorial for a complete prepare, run and read workflow. Preprocessing writes inputs and travel-time/model metadata; run the matching create_grnlib function to calculate Green functions. free_surface=0 includes the free surface; 1 removes it; 2 removes it with amplitude correction for surface receivers.

pygrnwang.create_qseis2025_bulk.create_grnlib_qseis2025_sequential(path_green, check_finished=False, convert_pd2bin=True, remove_pd=True, max_retries=2)

Compute the prepared qseis2025 library sequentially.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• convert_pd2bin (bool, optional) – Convert completed ASCII waveforms to the compact float32 reader format. Default: True.

• remove_pd (bool, optional) – Delete original ASCII output; retain it while validating a new calculation. Default: True.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – Jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_qseis2025).

Notes

See the qseis2025 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_qseis2025_bulk.create_grnlib_qseis2025_parallel(path_green, check_finished=False, convert_pd2bin=True, remove_pd=True, memory_per_job_gb=1.4, max_retries=2)

Compute the prepared qseis2025 library with local worker processes.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• convert_pd2bin (bool, optional) – Convert completed ASCII waveforms to the compact float32 reader format. Default: True.

• remove_pd (bool, optional) – Delete original ASCII output; retain it while validating a new calculation. Default: True.

• memory_per_job_gb (float or None, optional) – Peak memory of one qseis2025 process in GiB. A RuntimeWarning is issued when min(processes_num, number of jobs) such processes may not fit in the currently available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again; None skips the warning. Default: 1.4, the measured commit of the bundled executable.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – Jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_qseis2025).

Notes

See the qseis2025 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A job fails when the executable cannot start, exits with an error (for example after being killed for lack of memory) or leaves incomplete output files; it never gets a .finished marker. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs. On Windows call under an if __name__ == “__main__” guard.

pygrnwang.create_qseis2025_bulk.create_grnlib_qseis2025_parallel_multi_nodes(path_green, check_finished=False, convert_pd2bin=True, remove_pd=True, memory_per_job_gb=1.4, max_retries=2)

Compute the prepared qseis2025 library with MPI.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• convert_pd2bin (bool, optional) – Convert completed ASCII waveforms to the compact float32 reader format. Default: True.

• remove_pd (bool, optional) – Delete original ASCII output; retain it while validating a new calculation. Default: True.

• memory_per_job_gb (float or None, optional) – Peak memory of one qseis2025 process in GiB. A RuntimeWarning is issued when the ranks on a node may not fit in its available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again; None skips the warning. Default: 1.4, the measured commit of the bundled executable.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – mpi4py is unavailable, or (on rank 0) jobs still fail after the retries or the finished library is incomplete.

• ValueError – MPI rank count does not match the prepared group width.

Notes

See the qseis2025 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A failed job does not stop the others: after all ranks finish, the jobs that did not complete are shared among the ranks and computed again, up to max_retries times. Rank 0 checks the library after all ranks finish; after an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_qseis2025_bulk.convert_pd2bin_qseis2025_all(path_green, remove=False)

Convert all completed qseis2025 outputs to float32 binary libraries.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• remove (bool, optional) – Delete source ASCII files after converting them; keep False when inspecting backend output. Default: False.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

OSError – Required files are missing or output paths cannot be read or written.

Notes

See the qseis2025 tutorial for a complete prepare, run and read workflow. Conversion is a storage operation; it does not resample or change physical units. Jobs with incomplete output are skipped and keep their files, so they can be inspected and recomputed.

pygrnwang.create_qseis2025_bulk.check_grnlib_qseis2025(path_green, check_values=False)

Check that a qseis2025 library holds every file the readers need.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_values (bool, optional) – Also read every binary Green’s function file and report NaN or infinite values; this reads the whole library. Default: False.

Returns:

problems (list of str) – One line per missing or incomplete file; empty when the library is complete.

Raises:

OSError – green_lib_info.json cannot be read.

Notes

For every source depth, receiver depth and distance group, each observable selected in the job’s grn.inp must exist as a float32 binary file of the size the readers expect, or as complete ASCII files with one row per sample and one column per distance. The P and S travel-time tables must hold one value per distance. Rerun the create_grnlib function with check_finished=True to recompute only incomplete jobs.

create_spgrn2012_bulk

Deprecated backend: SPGRN2012. Use SPGRN2020 for new calculations. Rebuild the Green library and revalidate numerical settings, source and time conventions, and results when migrating.

pygrnwang.create_spgrn2012_bulk.pre_process_spgrn2012(processes_num, path_green, event_depth_list, receiver_depth_list, spec_time_window, sampling_interval, max_frequency, max_slowness, anti_alias, gravity_fc, gravity_harmonic, cal_sph, cal_tor, source_radius, cal_gf, time_window, t0, v0, source_duration, dist_range, delta_dist_range, path_nd=None, earth_model_layer_num=None, physical_dispersion=0)

Prepare the spgrn2012 library grid, input files and job groups.

Warning

SPGRN2012 is deprecated. Use SPGRN2020 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

• processes_num (int) – Positive worker count used to group jobs; MPI rank count must match the prepared group width.

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• event_depth_list (list of float) – Source depth nodes in km, positive down; supply a nonempty sorted list.

• receiver_depth_list (list of float) – Receiver depth nodes in km, positive down; supply a nonempty sorted list.

• spec_time_window (float) – Spectral calculation duration in seconds; it must cover the requested output window.

• sampling_interval (float) – Time step in seconds; choose it consistently with the highest modeled frequency.

• max_frequency (float) – Highest modeled frequency in Hz; must be compatible with the time step.

• max_slowness (float) – Maximum modeled slowness in s/km; in SPGRN, nonpositive requests the complete wavefield.

• anti_alias (float) – Dimensionless time-domain alias suppression factor; use a small positive value below 1.

• gravity_fc (float) – Critical frequency in Hz below which self-gravity is included together with the harmonic cutoff.

• gravity_harmonic (int) – Critical spherical harmonic degree for self-gravity.

• cal_sph (int) – 1 enables spheroidal (P-SV) modes; 0 disables them.

• cal_tor (int) – 1 enables toroidal (SH) modes; 0 disables them.

• source_radius (float) – Source patch radius in km.

• cal_gf (int) – 1 updates source spectra; 0 reuses spectra with identical model and spectral parameters.

• time_window (float) – Output time-window duration in seconds.

• t0 (float) – Reference start time in seconds in the SPGRN2012 rule t_start = t0 + distance/v0.

• v0 (float) – SPGRN2012 reduction velocity in km/s; use a nonzero value consistent with the desired phase window.

• source_duration (float) – Squared half-sinusoid source-time-function duration in seconds; zero requests the backend minimum.

• dist_range (list of float) – Minimum and maximum epicentral distances in km.

• delta_dist_range (list of float) – Smallest and largest distance increments in km at the near and far limits; equal values produce a regular grid.

• path_nd (str or None, optional) – Six-column named-discontinuity model path: depth (km), Vp/Vs (km/s), density (g/cm3), Qp/Qs. Bulk preprocessing requires a real path even though the signature default is None. Default: None.

• earth_model_layer_num (int or None, optional) – Number of numeric model rows retained, not the number of discontinuities; None retains all. Default: None.

• physical_dispersion (int, optional) – 0 disables, 1 enables the backend physical-dispersion correction associated with attenuation. Default: 0.

Returns:

group_list (list) – Jobs grouped by processes_num; the same groups are saved as a pickle file.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• ValueError – An input or output path is longer than the 160 characters spgrn2012 can hold.

Notes

See the spgrn2012 tutorial for a complete prepare, run and read workflow. Preprocessing writes inputs and travel-time/model metadata; run the matching create_grnlib function to calculate Green functions.

pygrnwang.create_spgrn2012_bulk.create_grnlib_spgrn2012_sequential(path_green, check_finished=False, max_retries=2)

Compute the prepared spgrn2012 library sequentially.

Warning

SPGRN2012 is deprecated. Use SPGRN2020 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – Jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_spgrn2012).

Notes

See the spgrn2012 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. The travel-time tables are written after the run. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_spgrn2012_bulk.create_grnlib_spgrn2012_parallel(path_green, check_finished=False, memory_per_job_gb=None, max_retries=2)

Compute the prepared spgrn2012 library with local worker processes.

Warning

SPGRN2012 is deprecated. Use SPGRN2020 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• memory_per_job_gb (float or None, optional) – Peak memory of one spgrn2012 process in GiB. A RuntimeWarning is issued when min(processes_num, number of jobs) such processes may not fit in the currently available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again. spgrn2012 allocates most arrays from the input, so there is no fixed value; None skips the warning. Default: None.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – Jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_spgrn2012).

Notes

See the spgrn2012 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A job fails when the executable cannot start, exits with an error (for example after being killed or refused memory) or leaves incomplete output files; it never gets a .finished marker. The travel-time tables are written after the run. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs. On Windows call under an if __name__ == “__main__” guard.

pygrnwang.create_spgrn2012_bulk.create_grnlib_spgrn2012_parallel_multi_nodes(path_green, check_finished=False, memory_per_job_gb=None, max_retries=2)

Compute the prepared spgrn2012 library with MPI.

Warning

SPGRN2012 is deprecated. Use SPGRN2020 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• memory_per_job_gb (float or None, optional) – Peak memory of one spgrn2012 process in GiB. A RuntimeWarning is issued when the ranks on a node may not fit in its available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again. spgrn2012 allocates most arrays from the input, so there is no fixed value; None skips the warning. Default: None.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – mpi4py is unavailable, or (on rank 0) jobs still fail after the retries or the finished library is incomplete.

• ValueError – MPI rank count does not match the prepared group width.

Notes

See the spgrn2012 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A failed job does not stop the others: after all ranks finish, the jobs that did not complete are shared among the ranks and computed again, up to max_retries times. After all ranks finish, rank 0 records the distances in green_lib_info.json, writes the travel-time tables and checks the library; after an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_spgrn2012_bulk.check_grnlib_spgrn2012(path_green, check_values=False)

Check that a spgrn2012 library holds every file the readers need.

Warning

SPGRN2012 is deprecated. Use SPGRN2020 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_values (bool, optional) – Also read every Green’s function file and report NaN or infinite values; this reads the whole library. Default: False.

Returns:

problems (list of str) – One line per missing or incomplete file; empty when the library is complete.

Raises:

OSError – green_lib_info.json cannot be read.

Notes

For every source/receiver depth pair, GreenInfo must list the same distances and samples as green_lib_info.json, grn_d must hold every distance, and the P and S travel-time tables tp_table.bin and ts_table.bin must hold one value per distance. Spectra under GreenSpec are not checked. Rerun the create_grnlib function with check_finished=True to recompute only incomplete jobs.

create_spgrn2020_bulk

pygrnwang.create_spgrn2020_bulk.pre_process_spgrn2020(processes_num, path_green, event_depth_list, receiver_depth_list, spec_time_window, sampling_interval, max_frequency, max_slowness, anti_alias, gravity_fc, gravity_harmonic, cal_sph, cal_tor, source_radius, cal_gf, time_window, green_before_p, source_duration, dist_range, delta_dist_range, path_nd=None, earth_model_layer_num=None, physical_dispersion=0)

Prepare the spgrn2020 library grid, input files and job groups.

Parameters:

• processes_num (int) – Positive worker count used to group jobs; MPI rank count must match the prepared group width.

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• event_depth_list (list of float) – Source depth nodes in km, positive down; supply a nonempty sorted list.

• receiver_depth_list (list of float) – Receiver depth nodes in km, positive down; supply a nonempty sorted list.

• spec_time_window (float) – Spectral calculation duration in seconds; it must cover the requested output window.

• sampling_interval (float) – Time step in seconds; choose it consistently with the highest modeled frequency.

• max_frequency (float) – Highest modeled frequency in Hz; must be compatible with the time step.

• max_slowness (float) – Maximum modeled slowness in s/km; in SPGRN, nonpositive requests the complete wavefield.

• anti_alias (float) – Dimensionless time-domain alias suppression factor; use a small positive value below 1.

• gravity_fc (float) – Critical frequency in Hz below which self-gravity is included together with the harmonic cutoff.

• gravity_harmonic (int) – Critical spherical harmonic degree for self-gravity.

• cal_sph (int) – 1 enables spheroidal (P-SV) modes; 0 disables them.

• cal_tor (int) – 1 enables toroidal (SH) modes; 0 disables them.

• source_radius (float) – Source patch radius in km.

• cal_gf (int) – 1 updates source spectra; 0 reuses spectra with identical model and spectral parameters.

• time_window (float) – Output time-window duration in seconds.

• green_before_p (float) – Positive seconds before direct P at the start of an SPGRN2020 trace.

• source_duration (float) – Squared half-sinusoid source-time-function duration in seconds; zero requests the backend minimum.

• dist_range (list of float) – Minimum and maximum epicentral distances in km.

• delta_dist_range (list of float) – Smallest and largest distance increments in km at the near and far limits; equal values produce a regular grid.

• path_nd (str or None, optional) – Six-column named-discontinuity model path: depth (km), Vp/Vs (km/s), density (g/cm3), Qp/Qs. Bulk preprocessing requires a real path even though the signature default is None. Default: None.

• earth_model_layer_num (int or None, optional) – Number of numeric model rows retained, not the number of discontinuities; None retains all. Default: None.

• physical_dispersion (int, optional) – 0 disables, 1 enables the backend physical-dispersion correction associated with attenuation. Default: 0.

Returns:

group_list (list) – Jobs grouped by processes_num; the same groups are saved as a pickle file.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• ValueError – An input or output path is longer than the 160 characters spgrn2020 can hold.

Notes

See the spgrn2020 tutorial for a complete prepare, run and read workflow. Preprocessing writes inputs and travel-time/model metadata; run the matching create_grnlib function to calculate Green functions.

pygrnwang.create_spgrn2020_bulk.create_grnlib_spgrn2020_sequential(path_green, check_finished=False, max_retries=2)

Compute the prepared spgrn2020 library sequentially.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – Jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_spgrn2020).

Notes

See the spgrn2020 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_spgrn2020_bulk.create_grnlib_spgrn2020_parallel(path_green, check_finished=False, memory_per_job_gb=None, max_retries=2)

Compute the prepared spgrn2020 library with local worker processes.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• memory_per_job_gb (float or None, optional) – Peak memory of one spgrn2020 process in GiB. A RuntimeWarning is issued when min(processes_num, number of jobs) such processes may not fit in the currently available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again. spgrn2020 allocates its arrays from the input, so there is no fixed value; None skips the warning. Default: None.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – Jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_spgrn2020).

Notes

See the spgrn2020 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A job fails when the executable cannot start, exits with an error (for example after being killed or refused memory) or leaves incomplete output files; it never gets a .finished marker. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs. On Windows call under an if __name__ == “__main__” guard.

pygrnwang.create_spgrn2020_bulk.create_grnlib_spgrn2020_parallel_multi_nodes(path_green, check_finished=False, memory_per_job_gb=None, max_retries=2)

Compute the prepared spgrn2020 library with MPI.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• memory_per_job_gb (float or None, optional) – Peak memory of one spgrn2020 process in GiB. A RuntimeWarning is issued when the ranks on a node may not fit in its available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again. spgrn2020 allocates its arrays from the input, so there is no fixed value; None skips the warning. Default: None.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – mpi4py is unavailable, or (on rank 0) jobs still fail after the retries or the finished library is incomplete.

• ValueError – MPI rank count does not match the prepared group width.

Notes

See the spgrn2020 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A failed job does not stop the others: after all ranks finish, the jobs that did not complete are shared among the ranks and computed again, up to max_retries times. After all ranks finish, rank 0 records the distances in green_lib_info.json and checks the library; after an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_spgrn2020_bulk.check_grnlib_spgrn2020(path_green, check_values=False)

Check that a spgrn2020 library holds every file the readers need.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_values (bool, optional) – Also read every Green’s function file and report NaN or infinite values; this reads the whole library. Default: False.

Returns:

problems (list of str) – One line per missing or incomplete file; empty when the library is complete.

Raises:

OSError – green_lib_info.json cannot be read.

Notes

For every source/receiver depth pair, GreenInfo must list the same distances and samples as green_lib_info.json, grn_d must hold every distance, and tptable.dat and tstable.dat must hold one entry per distance. Spectra under GreenSpec are not checked. Rerun the create_grnlib function with check_finished=True to recompute only incomplete jobs.

create_qssp2020_bulk

pygrnwang.create_qssp2020_bulk.pre_process_qssp2020(processes_num, path_green, event_depth_list, receiver_depth_list, spec_time_window, sampling_interval, max_frequency, max_slowness, anti_alias, turning_point_filter, turning_point_d1, turning_point_d2, free_surface_filter, gravity_fc, gravity_harmonic, cal_sph, cal_tor, min_harmonic, max_harmonic, source_radius, source_duration, output_observables, time_window, time_reduction, dist_range, delta_dist, path_nd=None, earth_model_layer_num=None, physical_dispersion=0, check_finished_tpts_table=False)

Prepare the qssp2020 library grid, input files and job groups.

Parameters:

• processes_num (int) – Positive worker count used to group jobs; MPI rank count must match the prepared group width.

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• event_depth_list (list of float) – Source depth nodes in km, positive down; supply a nonempty sorted list.

• receiver_depth_list (list of float) – Receiver depth nodes in km, positive down; supply a nonempty sorted list.

• spec_time_window (float) – Spectral calculation duration in seconds; it must cover the requested output window.

• sampling_interval (float) – Time step in seconds; choose it consistently with the highest modeled frequency.

• max_frequency (float) – Highest modeled frequency in Hz; must be compatible with the time step.

• max_slowness (float) – Maximum modeled slowness in s/km; in SPGRN, nonpositive requests the complete wavefield.

• anti_alias (float) – Dimensionless time-domain alias suppression factor; use a small positive value below 1.

• turning_point_filter (int) – 1 selects the QSSP turning-depth filter; 0 disables it.

• turning_point_d1 (float) – Minimum allowed turning depth in km when the turning-point filter is enabled.

• turning_point_d2 (float) – Maximum allowed turning depth in km when the turning-point filter is enabled.

• free_surface_filter (int) – QSSP switch: 1 includes free-surface reflection, 0 removes it.

• gravity_fc (float) – Critical frequency in Hz below which self-gravity is included together with the harmonic cutoff.

• gravity_harmonic (int) – Critical spherical harmonic degree for self-gravity.

• cal_sph (int) – 1 enables spheroidal (P-SV) modes; 0 disables them.

• cal_tor (int) – 1 enables toroidal (SH) modes; 0 disables them.

• min_harmonic (int) – Control for estimating the low-frequency baseline of the frequency-dependent upper harmonic cutoff. This is not the lowest retained degree: the spectral sum still starts at degree zero. Converge it together with max_harmonic for the requested observables.

• max_harmonic (int) – Upper harmonic cutoff cap. It also influences the spatial differential-transform order through the internal maximum degree, so changing it can affect synthesis even when the stored spectral cutoff is unchanged. Converge it together with min_harmonic.

• source_radius (float) – Source patch radius in km.

• source_duration (float) – Squared half-sinusoid source-time-function duration in seconds; zero requests the backend minimum.

• output_observables (list of int) – Eleven 0/1 flags: displacement, velocity, acceleration, strain, strain rate, stress, stress rate, rotation, rotation rate, gravitation, gravimeter.

• time_window (float) – Output time-window duration in seconds.

• time_reduction (float) – QSSP trace start time in seconds relative to source origin, not a velocity.

• dist_range (list of float) – Minimum and maximum epicentral distances in km.

• delta_dist (float) – Positive regular distance increment in km. The last grid point can exceed the requested maximum by less than one increment.

• path_nd (str or None, optional) – Six-column named-discontinuity model path: depth (km), Vp/Vs (km/s), density (g/cm3), Qp/Qs. Bulk preprocessing requires a real path even though the signature default is None. Default: None.

• earth_model_layer_num (int or None, optional) – Number of numeric model rows retained, not the number of discontinuities; None retains all. Default: None.

• physical_dispersion (int, optional) – 0 disables, 1 enables the backend physical-dispersion correction associated with attenuation. Default: 0.

• check_finished_tpts_table (bool, optional) – Reuse existing P/S table files without validating their model or grid provenance. Default: False.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• ValueError – An input, spectrum or output path is longer than the 160 characters qssp2020 can hold.

Notes

See the qssp2020 tutorial for a complete prepare, run and read workflow. Preprocessing writes inputs and travel-time/model metadata; run the matching create_grnlib function to calculate Green functions. A first computation must include both spectral and time-domain stages. See the QSSP2020 tutorial for harmonic-cutoff convergence and comparison settings.

pygrnwang.create_qssp2020_bulk.create_grnlib_qssp2020_sequential(path_green, cal_spec=True, check_finished=False, convert_pd2bin=True, remove_pd=True, max_retries=2)

Compute the prepared qssp2020 library sequentially.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• cal_spec (bool, optional) – Compute spectra before time-domain synthesis. Keep True for a new QSSP library; False requires compatible existing spectra. Default: True.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• convert_pd2bin (bool, optional) – Convert completed ASCII waveforms to the compact float32 reader format. Default: True.

• remove_pd (bool, optional) – Delete original ASCII output; retain it while validating a new calculation. Default: True.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – Jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_qssp2020).

Notes

See the qssp2020 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_qssp2020_bulk.create_grnlib_qssp2020_parallel(path_green, cal_spec=True, check_finished=False, convert_pd2bin=True, remove_pd=True, memory_per_job_gb=None, max_retries=2)

Compute the prepared qssp2020 library with local worker processes.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• cal_spec (bool, optional) – Compute spectra before time-domain synthesis. Keep True for a new QSSP library; False requires compatible existing spectra. Default: True.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• convert_pd2bin (bool, optional) – Convert completed ASCII waveforms to the compact float32 reader format. Default: True.

• remove_pd (bool, optional) – Delete original ASCII output; retain it while validating a new calculation. Default: True.

• memory_per_job_gb (float or None, optional) – Peak memory of one qssp2020 process in GiB, for the larger of the spectral and time-domain stages. A RuntimeWarning is issued when min(processes_num, number of a stage’s jobs) such processes may not fit in the currently available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again. qssp2020 allocates its arrays from the input, so there is no fixed value; None skips the warning. Default: None.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – Jobs still fail after the retries, or the finished library is incomplete (see check_grnlib_qssp2020).

Notes

See the qssp2020 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. A job fails when the executable cannot start, exits with an error (for example after being killed or refused memory) or leaves incomplete output files; it never gets a .finished marker. A failed job does not stop the others: afterwards the jobs that did not complete are computed again, up to max_retries times, and the library is checked. Ctrl+C stops the run at once and kills the running backends. After an error, rerun with check_finished=True to compute only unfinished jobs. On Windows call under an if __name__ == “__main__” guard.

pygrnwang.create_qssp2020_bulk.create_grnlib_qssp2020_spec_parallel_multi_nodes(path_green, check_finished=False, memory_per_job_gb=None, max_retries=2)

Compute the prepared qssp2020 library with MPI.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• memory_per_job_gb (float or None, optional) – Peak memory of one qssp2020 spectral process in GiB. A RuntimeWarning is issued when the ranks on a node may not fit in its available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again. qssp2020 allocates its arrays from the input, so there is no fixed value; None skips the warning. Default: None.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – mpi4py is unavailable, or (on rank 0) spectral jobs still fail after the retries.

• ValueError – There are fewer MPI ranks than the prepared group width.

Notes

See the qssp2020 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. This computes the spectral stage only; run create_grnlib_qssp2020_func_parallel_multi_nodes afterwards. Ranks beyond the group width stay idle. A failed job does not stop the others: after all ranks finish, the jobs that did not complete are shared among the ranks and computed again, up to max_retries times. After an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_qssp2020_bulk.create_grnlib_qssp2020_func_parallel_multi_nodes(path_green, check_finished=False, memory_per_job_gb=None, max_retries=2)

Compute the prepared qssp2020 library with MPI.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_finished (bool, optional) – Reuse jobs marked finished whose output is complete; recompute the others. Markers do not verify that inputs are unchanged. Default: False.

• memory_per_job_gb (float or None, optional) – Peak memory of one qssp2020 time-domain process in GiB. A RuntimeWarning is issued when the ranks on a node may not fit in its available memory (including Slurm/container cgroup limits); the run goes on and jobs that run out of memory are computed again. qssp2020 allocates its arrays from the input, so there is no fixed value; None skips the warning. Default: None.

• max_retries (int, optional) – Extra passes over the jobs that did not complete, for example because they ran out of memory; each pass recomputes only those jobs, with the same worker count. Default: 2.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

• OSError – Required files are missing or output paths cannot be read or written.

• RuntimeError – mpi4py is unavailable, or (on rank 0) jobs still fail after the retries or the finished library is incomplete.

• ValueError – There are fewer MPI ranks than the prepared group width.

Notes

See the qssp2020 tutorial for a complete prepare, run and read workflow. Prepare jobs first. Backend runners can change the process working directory; use absolute paths and restore the caller directory if needed. Run it after the spectral stage has finished. The output stays in ASCII; convert it with convert_pd2bin_qssp2020_all. Ranks beyond the group width stay idle. A failed job does not stop the others: after all ranks finish, the jobs that did not complete are shared among the ranks and computed again, up to max_retries times. Rank 0 checks the library after all ranks finish; after an error, rerun with check_finished=True to compute only unfinished jobs.

pygrnwang.create_qssp2020_bulk.convert_pd2bin_qssp2020_all(path_green)

Convert all completed qssp2020 outputs to float32 binary libraries.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

Returns:

None – Writes backend inputs, metadata or output files to the library.

Raises:

OSError – Required files are missing or output paths cannot be read or written.

Notes

See the qssp2020 tutorial for a complete prepare, run and read workflow. Conversion is a storage operation; it does not resample or change physical units. Source/receiver depth pairs with incomplete output are skipped and keep their files, so they can be inspected and recomputed.

pygrnwang.create_qssp2020_bulk.check_grnlib_qssp2020(path_green, check_values=False)

Check that a qssp2020 library holds every file the readers need.

Parameters:

• path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.

• check_values (bool, optional) – Also read every binary Green’s function file and report NaN or infinite values; this reads the whole library. Default: False.

Returns:

problems (list of str) – One line per missing or incomplete file; empty when the library is complete.

Raises:

OSError – green_lib_info.json cannot be read.

Notes

For every source depth, receiver depth and moment-tensor component, each observable selected by output_observables must exist as a float32 .bin file of the size the readers expect, or as a complete .dat file with one row per sample and one column per distance. The P and S travel-time tables must hold one value per distance. Spectra under GreenSpec are not checked. Rerun the create_grnlib function with check_finished=True to recompute only incomplete jobs.