Library layout and data formats#

Keep each backend and numerical configuration in a separate library root. green_lib_info.json describes the grid, sample interval, time window and other parameters required by the corresponding reader. It is part of the data, not a disposable cache.

Backend directories#

Backend	Important paths beneath its library root
QSEIS06/2025	`<source:.2f>/<receiver:.2f>/<group>_<offset>/grn.inp` and basis output files
SPGRN2012/2020	`GreenSpec/<source:.2f>/<receiver:.2f>/` and `GreenFunc/<source:.2f>/<receiver:.2f>/`
QSSP2020	`GreenSpec/<source:.2f>/<receiver:.2f>/spec.inp`; `GreenFunc/<source:.2f>/<receiver:.2f>/<tensor-source>/`
EDGRN	`edgrn2/<receiver:.2f>/`, including `edgrn.ss`, `edgrn.ds` and `edgrn.cl`
EDCMP	`edcmp2/<source:.2f>/<receiver:.2f>/<basis-index>/`, with five basis indices
All preprocessed libraries	`green_lib_info.json`, task-group `.pkl` files and the model/`noQ.nd`

Depth directory names have two decimal places. Choose depths that remain distinct after this formatting; otherwise separate requested depths can refer to the same directory. QSEIS distances are grouped to limit one backend job’s receiver count. Its ordinary group suffix is _0; derivative libraries may have additional offset suffixes.

The actual sampled distance grid can extend beyond an input upper bound when the interval does not divide the range exactly. Query the computed grid recorded in metadata rather than inferring a different grid with an unmatched linspace. SPGRN may use variable distance spacing and stores its actual dist_list after the backend finishes.

ASCII and binary#

QSEIS ASCII files use source-type prefixes such as ex, ss, ds, cl and observable extensions. Conversion writes grn_<component>.bin. These binary arrays use float32, grouped by distance, basis source and time as expected by the matching reader.

QSSP writes one file per selected observable component and six spherical moment-source bases, mrr, mtt, mpp, mrt, mrp, mtp. Conversion removes the time column and writes receiver-major float32 data. Native SPGRN files contain Fortran records and metadata; they are not plain arrays of three equally sized displacement channels.

EDCMP hs.disp, hs.strain, hs.stress and hs.tilt are static output tables. Conversion writes float32 component arrays and, where the bulk converter is used, combined grids for efficient bulk lookup. The main reader can read the per-basis data.

Use the matching package converter and reader. Raw numpy.fromfile without the exact layout can silently produce plausible but incorrectly ordered data. Binary files are not self-describing, and native Fortran record structure/byte order can depend on how a backend was built. Keep the executable/package version and metadata with archived data.

Conversion and cleanup#

QSEIS creation functions generally convert after computing. QSSP’s sequential/parallel paths default to convert_pd2bin=True, remove_pd=True, so ASCII files can disappear after conversion. During a first run, retaining ASCII helps inspect units, headers and failures. Disable removal with remove_pd=False where that argument exists.

EDCMP sequential creation does not perform the bulk conversion automatically; call convert_pd2bin_edcmp2_all explicitly if it is required. Its tutorial shows the complete sequence.

Before removing ASCII, confirm that the binary reader reproduces the expected array shape, finite values and representative traces. Do not move only the .bin files while leaving the metadata or required travel-time tables behind.

Travel-time files and trusted libraries#

Python-created tp_table.bin/ts_table.bin store one float32 time per distance. SPGRN2020 tptable.dat/tstable.dat instead contain native Fortran onset/takeoff/slowness records; use their designated reader.

The task-group .pkl files are internal serialized Python task lists. Only run preprocessing/creation against libraries you created or trust, because loading pickle can execute Python code. For sharing scientific results, include neutral arrays, model text and JSON metadata alongside the full library when practical.

Tutorial artifacts#

Each script uses examples/output/<backend> by default, with a library subdirectory and saved observable arrays, PNG figures and summary.json. Use --output-dir to select a separate location and --reuse to read a completed tutorial run. Reuse writes summary-reuse.json and preserves the original construction report. Figures show the saved arrays; the summary reports shape, finite-value checks, elapsed time and output size.