Troubleshooting and known limitations

Start by running the smallest tutorial for the relevant backend in a fresh output directory. Retain the generated input, model, metadata and executable output when reporting a failure.

Installation or executable failures

A compatible wheel avoids a local Fortran build. A source installation requires gfortran; compiled executables also need their platform runtime libraries. A successful import pygrnwang alone does not demonstrate that a backend executable can run.

On Linux/macOS, the current bulk calculation helper looks for <environment>/bin/<solver>.bin, while standard wheels keep native executables under pygrnwang/exec/ and provide entry points without the .bin suffix. For current bulk calculation tutorials, use the documented source/editable installation, which places the expected files in the environment. The direct wrapper command can find a package binary, but this does not fix the bulk helper’s separate lookup path.

Check the active Python environment, package version and backend command. On Windows use an activated environment or conda run -n ENV python ...; launching an environment’s python.exe directly may omit DLL directories. Use short, local, writable paths if a legacy Fortran path-length or input filename issue is suspected. Inspect grn.inp or spec.inp for absolute paths to the intended files.

Some backend calls change working directory. Resolve model/output paths before the first call and avoid assuming the caller’s working directory remains unchanged.

Java or model failures

Both java and javac are required for Java mode. Missing tools or JAR select ObsPy when pytaup is imported. A selected Java backend that fails to compile or load a model raises an error; it is not silently retried with ObsPy. Start a new Python process after changing PATH.

For custom models, check numeric column count, velocity discontinuities, boundary names, model extent and model-directory write access. ObsPy may need to create an adjacent .npz. Match the travel-time model to the wave-propagation model and regenerate tables after a change.

Missing files, reshape errors or zero results

Symptom	Checks
Missing green_lib_info.json	Run preprocessing for this backend in the correct root
Missing requested observable	Confirm its build-time output flag was enabled
Missing QSSP spectra	First run requires cal_spec=True
Missing SPGRN2012 tp_table.bin	Sequential/MPI paths need explicit Python table preparation
Unexpected array size/reshape error	Check native sampling, actual distance grid, matching metadata and completed conversion
No signal in selected time window	Check native start time, phase arrival, source mechanism, output band and component
Non-finite or implausible result	Inspect executable logs, model material, source normalization and numerical convergence

A completed process or .finished marker is not a substitute for finite values and scientifically plausible output. A component may be physically zero for a particular mechanism/azimuth; inspect all components and a second mechanism before concluding a solver failed.

Arrival and waveform alignment

first_p/first_s equal None when a reader did not request a new travel-time calculation (shift=False). This is expected. A TauP first arrival of NaN means the phase query did not supply a usable arrival.

A trace beginning at index zero does not necessarily begin at source origin: QSEIS, SPGRN and QSSP have different time-reduction conventions. Check time origin. Avoid combining before_p and pad_zeros. Validate shift=True against a direct computation before using its piecewise resampling for scientific measurements.

Short or sharply truncated traces can show filter-padding errors or edge ringing. Keep the frequency band below Nyquist, retain time margins, and inspect the unfiltered trace and source-time function.

Known implementation limitations

These are observations from the current source audit, not changes to the numerical code made by the documentation project.

QSEIS06 derivative libraries. The finite-difference reader requires the extra spatial samples and metadata produced by pre_process_qseis06_strain_rate. An ordinary pre_process_qseis06 library cannot replace it. Retain ASCII when executing derivative jobs: the binary detector looks for grn_tz.npy and its binary-reader call omits the required sampling_num argument. Use convert_pd2bin=False, remove_pd=False for that path. The derivative tensor rotation uses -az_deg while the QSEIS2025 direct reader uses +az_deg; compare signs against an independently checked calculation rather than assuming equivalence. Prefer the tested direct QSEIS2025 strain/stress tutorial for an introductory tensor workflow; derivative convergence and sign checks require their own calculation.

QSEIS2025 template comments. Some legacy input-template descriptions swap the strain/stress labels on e*/s* filenames. The current Fortran calculation and Python reader use e* for strain and s* for stress. Follow the observable table in the tutorial and the actual output routine.

SPGRN2012 sequential/MPI travel-time tables. These creation paths update library metadata but do not create the Python P/S tables that the reader loads on every query. The complete tutorial explicitly creates those tables using the actual computed distance grid.

EDGRN source-depth sampling. The backend requires at least two source depth samples; the static tutorial builds 10 and 11 km while demonstrating a query at 10 km. A single-depth request does not make that Fortran constraint disappear.

MPI postprocessing and task groups. SPGRN MPI calls update shared metadata from each rank without a dedicated postprocessing barrier. QSSP MPI routines can access rank entries before excluding unused ranks in uneven groups. Multi-node MPI requires a separate cluster validation, including divisible task groups and metadata/postprocessing coordination. The local tutorial checks do not establish multi-node correctness.

Direct QSSP convenience calls. The separate read_by_qssp pathway includes source coordinates in its cache key but writes a source fixed at latitude/longitude 0/0; a nonzero-coordinate request must not be interpreted as a validated relocation of that source. Its completion hash also omits the focal mechanism, so changing mechanism can reuse old output when completion reuse is enabled. Use the precomputed-library tutorial as the documented complete workflow.

Boundary queries and reuse. Reader endpoint clamping/validation is not uniform, and completion flags do not hash models or parameters. Query inside the computed grid and use a new directory after changing physical or numerical settings.

Report a reproducible issue

Include the package/commit version, operating system, Python version, installation method, relevant compiler/JDK/MPI versions, backend name, smallest driver, model, green_lib_info.json and executable error output. State the expected physical quantity, component order, source amplitude and time reference. Attach the smallest failing data subset or describe how to generate it; a screenshot alone cannot establish a numerical problem.