Travel times with TauP

Travel-time queries use a Java subprocess when both java and javac are on PATH and a bundled TauP.jar can be found. Otherwise the public first-arrival functions use ObsPy. JPype is not required. Importing pygrnwang.pytaup detects availability but does not start Java or compile the bridge.

The package bundles TauP 2.6.1; commands or requirements from the latest TauP documentation need not match this bundled version. The package wrapper is the interface described here.

Setup and selection

Install a JDK to use Java mode: a runtime containing java alone is insufficient because the bridge must first be compiled with javac. Use java -version and javac -version in the same environment where Python will run. After changing PATH, start a new Python process because backend selection occurs at module import.

Resource lookup checks the package’s exec/TauP.jar first, then sys.exec_prefix/Scripts/TauP.jar on Windows or sys.exec_prefix/bin/TauP.jar elsewhere. Standard wheels contain the package copy and install the environment copy.

The bridge is compiled lazily into a temporary directory once per Python process. Each individual query starts a Java subprocess. Java compilation, model-loading or query errors are reported as exceptions; automatic fallback means selection when Java/JAR is unavailable, not retrying every Java error with ObsPy.

Single-location queries

cal_first_p and cal_first_s return seconds; cal_first_p_s returns (first_p, first_s). Their source/receiver depths and distance are in km. The default model is ak135. For a custom model pass a .nd filename. When the receiver is deeper than the source, these first-arrival helpers swap the two depths to use reciprocity.

“First P” and “first S” refer to the earliest arrival in the package’s explicit phase lists:

Family	Queried names
P	p, P, pP, Pg, Pn, Pdiff, PKP
S	s, S, sS, pS, Sg, Sn, Sdiff, SKS

These are not a promise that every conceivable P-like or S-like branch is included. No arrival yields NaN. Check finiteness before aligning a waveform or converting a time to a sample index.

taup_time_java is the Java-specific interface for a user-provided phases_list. It returns a dictionary with parallel lists phase, puristphase, time and rayparameter. Empty lists mean no arrival. Ray parameter is seconds per radian, preserving TauP’s underlying convention. Convert to seconds per degree by multiplying by pi / 180; it is not already a s/km slowness.

Custom models

taup_create_npz_file(nd_file) prepares a model for the selected backend. In Java mode it returns the .nd path unchanged. In ObsPy mode it builds and returns an adjacent .npz. Use its returned path when scripting both backends. Java’s direct file reader is not an ObsPy .npz reader.

The four-column travel-time model uses depth, P/S velocity and density. The preprocessing helpers remove attenuation from the six-column wave model. Prepare the custom model in the main process before creating workers to avoid simultaneous model builds. Keep a writable model directory for ObsPy and rebuild the model if the .nd contents change.

Distance tables

create_tpts_table writes tp_table.bin and ts_table.bin in <path_green>/<source_depth:.2f>/<receiver_depth:.2f>/. Each is a headerless float32 array in exactly the order of dist_km_list; its unit is seconds. The function writes files and returns no array.

Java mode sends the complete distance list to a single Java process, reusing one model during that query. It is preferable to repeated individual queries on a distance grid. In ObsPy mode, max_workers controls the process pool; lists shorter than 50 distances run serially.

check_finished=True skips calculation only when both output files exist. It does not validate their length, distances or model identity. Reuse only when all inputs match and verify the stored grid. The supplied tutorials perform the relevant table preparation as part of a complete calculation.

SPGRN2020 also writes native Fortran tptable.dat and tstable.dat including takeoff angles in degrees and slowness in s/m. Multiply this native slowness by 1000 for s/km. Those files have their own reader and are not interchangeable with the Python tp_table.bin/ts_table.bin arrays.