# Changelog ## Unreleased ### QSEIS2025 library check with custom wavelets, 26 September 2026 - The QSEIS2025 library check reads the `output_observables` flags from the `OUTPUT FILES FOR GREEN'S FUNCTIONS` section of `grn.inp` instead of a fixed line. In 3.0.1, custom `wavelet_type=0` samples inserted into `grn.inp` moved the flags down, so a finished library was reported as unreadable, its jobs were computed twice more and the build raised `RuntimeError`. ## 3.0.1 ### Memory checks, retries and library checks for every backend, 25 September 2026 - Every backend run writes `.finished` only when the executable exits with code 0 and without a Fortran `STOP` error message; otherwise its log goes to `.failed`. Previously a process killed for lack of memory, or one that stopped on an input error (gfortran then exits with code 0), was still marked finished and skipped by `check_finished=True`. - The parallel and MPI builders of QSEIS06, QSEIS2025, EDGRN2 and EDCMP2 warn before any job starts when the processes running at once (per node for MPI) may need more than the available memory (`memory_per_job_gb`; Slurm/container cgroup limits count). The run goes on; jobs that run out of memory are computed again (below). QSSP2020 and SPGRN accept the same argument; their warning is off by default because their memory depends on the input. - A failed job no longer stops or hangs a build. All builders run the remaining jobs, compute the failed ones again up to `max_retries=2` times, check the library and raise `RuntimeError` listing what is still missing. MPI builders share the failed jobs among all ranks. Ctrl+C stops a build at once and kills the running backend processes. - New `check_grnlib_qseis06`, `check_grnlib_qseis2025`, `check_grnlib_qssp2020`, `check_grnlib_spgrn2012`, `check_grnlib_spgrn2020`, `check_grnlib_edgrn2` and `check_grnlib_edcmp2` check any library. A job that runs again first deletes its earlier output. - Conversions skip incomplete jobs, write binary files atomically and delete ASCII output only after its binary file exists; they used to delete partial output. QSSP2020 conversion now reads strain and rotation files under their real names (the flag order was swapped in `output_type_list`). - Preprocessors reject paths longer than the 160 characters the executables read, QSEIS `N_each_group` above 101, and EDGRN grids beyond its limits. - SPGRN2012 sequential and MPI builders now write the travel-time tables, as the parallel builder did; SPGRN MPI builders update the metadata from rank 0 only, and QSSP MPI builders no longer fail on a short last group. ### Displacement requested directly from readers, 15 September 2026 - `seek_qseis06` and `seek_qseis2025` now treat custom `wavelet_type=0` samples as a moment-rate function, like type 1. Non-rate outputs such as `disp`, `strain` and `stress` are integrated once, and `acce` is differentiated. Previously type 0 returned the stored rate kernels for every requested output type. - The regional QSEIS examples request `disp`, `strain` and `stress` directly. SPGRN2012 applies the analytic 64 s source to every Green function in `library-source-matched/` and reads `disp` from it; rebuild outputs of the previous SPGRN2012 example before reuse. Reruns matched the earlier QSEIS arrays to roundoff; SPGRN2012 differed by relative L2 `2.3e-7`, changing its 900 km comparison value from 0.0534% to 0.0535%. - The Quickstart now presents the 300/600/900 km QSEIS2025 calculation. QSEIS06 and SPGRN2012 are labeled deprecated in every figure legend or title. The English and Chinese comparison reports no longer contain their sections on remaining timing/spatial differences and confirmed causes. ### Fresh displacement and stress comparison, 15 September 2026 - Added a new five-backend displacement comparison and QSEIS2025/QSSP2020 six-component stress at 300/600/900 km, with fresh AK135-FC libraries, source/receiver depths 10/1 km, 0.25 s sampling, a common 2 Hz Nyquist band and a normalized 1.25 s source. Added full-window and strong-wave plots, downloadable arrays/metrics/model and a portable replotting script. - Documented the isolated QSEIS06 zero-smoothing control and matched-radius equality with QSEIS2025. Distinguished Gaussian wavenumber smoothing from the temporal STF, common continuous integration from native direct outputs, and timing diagnostics from the unshifted comparison metrics. - Added a Chinese result summary and preserved the previous 64 s comparison separately. Standard tutorial parameters and QSEIS2025's introductory 100 s crop remain unchanged; the new scientific record is Windows-only. ### Earlier tutorial documentation - Unified all five regional examples at a 0.125 Hz Nyquist limit, with verified native frequency grids, the same mechanism, moment and physical 64 s source. SPGRN2012 now uses its native impulse branch and an analytic forward source convolution over the complete FFT period before integration and cropping. - Added a QSEIS2025 `--regional --point-source` control to quantify its default frequency-dependent Gaussian spatial smoothing. Matched frequency limits and temporal sources alone did not remove the regional QSEIS/spherical residuals; the new comparison records both the remaining error and the spatial-source test. - Recalculated SPGRN2020 with its complete-wavefield option and QSSP2020 with harmonic settings 2000/8000 after identifying insufficient low-frequency cutoffs in the initial examples. Added convergence evidence, corrected harmonic-parameter documentation and plotted SPGRN2020 on its native source-origin time axis. - Added QSEIS06/QSEIS2025 `--regional` calculations at 300/600/900 km, with a 4092 s native window and 0–1020 s exports. The default QSEIS2025 introduction retains its 0–100 s crop. Added a reproducible five-backend comparison and included the regional calculations in tutorial CI. - Matched regional QSEIS's effective source time function to SPGRN2020 using 1024 custom moment-rate nodes with numerical damping precompensated. Kept the source's unit area and 32 s centroid, read rate kernels explicitly, and integrated them once in the examples before updating the comparison. Recorded that the remaining QSEIS/SPGRN2020 differences increased to about 12.7–23.0%, ruling out the previous STF mismatch as their main explanation. - Marked QSEIS06 and SPGRN2012 as deprecated in pygrnwang. New calculations should use QSEIS2025 and SPGRN2020 respectively; existing interfaces and tutorials remain available. Migration requires rebuilding libraries and validating the replacement backend's settings and output conventions. - Added an English user guide and API reference, with Chinese installation and QSEIS2025 quickstart pages. - Added small executable tutorials for QSEIS2025, QSEIS06, SPGRN2012, SPGRN2020, QSSP2020 and EDGRN/EDCMP. - Cropped the default QSEIS2025 introductory displacement, strain and stress arrays and figures to 0–100 s inclusive (201 samples at 0.5 s). The native 127.5 s, 256-sample Green's library and other backend examples retain their original windows. - Documented coordinate/component order, source normalization, time reduction, waveform units and solver-specific limitations. - Added strict documentation builds, example validation and GitHub Pages deployment configuration. This documentation change preserves calculation signatures, return types and numerical code. It records existing behavior and known limitations. ## Current 3.0.0 development baseline The baseline used for this documentation declares Python 3.9+ and setuptools 77+. Travel-time calculations use a lazily compiled Java subprocess bridge, with ObsPy as the automatic alternative when a JDK is unavailable. JPype is no longer a dependency. Wheels contain a package-local TauP.jar and install a copy into the environment's scripts directory. These entries describe the checked-out source baseline; they do not assert a new PyPI release date. For earlier releases, consult the [repository history](https://github.com/Zhou-Jiangcheng/pygrnwang/commits/main/).