Using xcap3d

Given an SCEDC event ID, xcap3d returns the moment tensor, the depth and a report. This page shows the steps one by one, the files they write, the main options, and how to look at many events.

The examples write DB for the Green’s-function database and ~/xcap3d_out for the output directory, where every event gets a folder <id>/.

The Green’s-function database

xcap3d does not compute Green’s functions during a run; it reads them from a database of strain Green’s tensor stores, one HDF5 file per station, each from three SPECFEM3D simulations with a unit force at the station. By reciprocity they give the seismogram at the station of a source anywhere in a box around it. The database is provided by the operator: point --gf at its directory. Its release.json lists the stores; a run checks every store it opens against it and names the release in result.json.

One command

xcap3d run 38695658 --gf DB --mt full --refine --out ~/xcap3d_out --report

run downloads the data, removes the instrument responses, inverts the data (depth scan with a grid search over strike, dip and rake at each depth, then the station jackknife) and, with --report, writes the report. The last line printed is the answer:

38695658 production: depth 15.5 km  FM 263/43/92  Mw 4.56  VR 67.8

FM is strike/dip/rake in degrees, VR the variance reduction in percent.

Step by step

The same work, one step at a time, e.g. to download many events before inverting them, or to invert again with other options without downloading:

xcap3d download 38695658 --out ~/xcap3d_out
xcap3d process 38695658 --out ~/xcap3d_out
xcap3d invert 38695658 --gf DB --mt full --refine --out ~/xcap3d_out
xcap3d report 38695658 --out ~/xcap3d_out

step	what it does	writes in <id>/
download EVENT_ID	fetches from the SCEDC FDSN service the event (origin, magnitude, phase picks), the station metadata with instrument responses and the raw seismograms of the CI stations within 100 km, 300 s before to 300 s after the origin	raw/
process EVENT_ID	removes the instrument response, rotates to Z, R, T, low-passes, resamples to 20 samples/s and sets the time windows from the picks	data-full/
invert EVENT_ID --gf DB	the inversion of run, with the same options, on the processed data; refuses when there are none	result.json, fits.h5; report.html with --report
report EVENT_ID	the report of a finished inversion	report.html and its figures

A step whose output is already there does nothing; move that folder away to repeat it: to download an event again, delete <out>/<id>/raw (there is no --refresh option). A download in which no channel returned data writes nothing. run writes the same files and also skips what is there, so run after process inverts the processed data, and the files are the same as those of the three steps.

From Python, xcap3d.run_event takes the settings of run by name and returns the record, an xcap3d.Result (a dict that prints the solution); download_event, process_event and invert_event are the three steps (API page). The example runs run_event.

Options

run and invert share these options; --help lists the rest.

option	default	meaning
--gf DB	required	the database directory
--release FILE	<DB>/release.json	the database’s release file
--out DIR	XCAP3D_OUT, else ./xcap3d-out	where <id>/ is written (also for download, process, report, compare)
--report	off	also write report.html
--device	auto	cpu, cuda:N, or auto (a GPU if PyTorch sees one)
--no-jackknife	jackknife on	skip the station jackknife (faster); uncertainty is then missing
--catalogs DIR	XCAP3D_CATALOGS	the directory holding the reference catalog files (below)
--mt	dc	dc: double couple only; dev (deviatoric): ISO fixed at 0, CLVD free; full: ISO and CLVD free. deviatoric and full also give the non-DC moment tensor at the chosen depth, around the DC solution (non_dc in the record, a lune in the report)
--refine	off	after the double-couple search at each depth, also search 1-deg nodes within 8 deg (Kagan) of up to 3 coarse minima and keep the lowest misfit; settings.refine in the record
--grid-step DEG	5	the strike/dip/rake spacing, more than 0 and at most 30 deg. On event 41249496 (64 stations, 18 depths, GPU) a 2-deg grid took 2.5 times as long and 33 against 12.7 GiB of GPU memory; 1 deg would not fit a 46 GiB GPU. --refine gives 1 deg near the minimum for about 1.5 times the time
--refine-step DEG	1	the spacing of the --refine nodes, less than half the refine radius (1.6 times the grid step); only with --refine

A CPU run of the example event needed 15 GB of memory: plan 16 GB per CPU run. Use a GPU (--device cuda:N) for production runs.

Outputs

file in <id>/	what it is
raw/	the raw download: event.xml (QuakeML), stations.xml (StationXML), waveforms.mseed, request.json (the request)
data-full/	the processed data: per station <NET>.<STA>.{r,t,z}.npy (cm/s), and meta.json with the event, the station coordinates, picks and time windows, and every station dropped with the reason; processing.json (from process) says how they were processed
result.json	the record of the inversion (below)
fits.h5	observed and synthetic waveforms in every time window of every station at every scanned depth
report.html, *.png	the report and its figures (below)

A data-full/ made by an older xcap3d is refused: move it away and run xcap3d process again.

The main keys of result.json:

key	contents
solution	depth, strike, dip, rake, Mw, M0 (N m), VR, stations and components used, the tensor mt_ned
depth_scan	the best mechanism, Mw, misfit and VR at each depth
depth_confidence	the depths within 10 % of the best misfit, and whether the best depth is at the edge of the scan
uncertainty	the station jackknife: each station left out in turn; the median and 90th percentile Kagan angle and the standard error of the depth
verdict	a one-line assessment, e.g. “well constrained”, with caveats
stations	per station: distance, azimuth, component weights, cross-correlation, time shifts, vr (its variance reduction, 1 - its misfit / its data energy over its used components, a fraction), and why it was left out
references	published mechanisms of the event in the reference catalogs; references_missing names the catalogs without it
database, inputs	the release used, and the sha256 of every input file
run_spec, settings, environment	every setting as run, the passbands and windows, the software versions and the device
status	complete; product_error when the inversion ran but the record could not be built (exit status 2); no_solution when there is no solution (exit status 3); error when the run crashed

Known issue, the QC weights: the Huber weights act on the absolute component residual, so a large, well-fit component can be down-weighted while a small, poorly correlated one keeps full weight. The 2021 code also removed components with CC below 40-65 %. A combined rule is being studied.

A run without a solution (no station or depth left, a store that differs from the release, an incomplete download) still writes result.json, with status no_solution and the reason, and prints the reason. A run that crashes writes status error with the exception’s type (error) and message (reason), then stops with the exception, so no earlier record is left standing. report refuses both kinds of record and catalog lists those events in one line.

Reference catalogs

The record and the report compare the solution with published solutions of the same event, read from these files in the directory --catalogs DIR (default XCAP3D_CATALOGS). None ships with xcap3d; a missing file is not an error, references_missing names it. A row that cannot be read is skipped, with one warning per file.

file in DIR	source
published_catalog.csv	the published 2021 catalog: gCAP3D, Wang & Zhan (2020)
scedc_cmt.csv	SCEDC moment tensors (SCSN)
HASH_FM_M3.cata	SCEDC HASH first-motion mechanisms

Many events: the catalog

Loop over the events in the shell, then put them on one page:

for id in 38695658 39322287 40735352; do
    xcap3d run $id --gf DB --out ~/xcap3d_out --report
done
xcap3d catalog ~/xcap3d_out

catalog writes catalog.html and catalog_map.png in that folder: one row per event that has a report, linked to it.

Visualizing

report.html shows the solution, the verdict and the published mechanisms of the event; the misfit and mechanism against depth (depth.png); the station map (map.png); observed and synthetic waveforms of every station at the chosen depth (fits.png, nearest first, each station with its VR and its rank); the station table, best VR first; and the settings, the database release and the software versions. xcap3d report EVENT_ID writes it again from result.json and fits.h5 without inverting again.

The station map shows four groups, with their counts in the key: used (filled, the area by the summed weight of the station’s components), deselected by the QC or the source margin (filled gray, the reason in the station table), not in the database (open circles) and without data (gray crosses).

The maps draw the Natural Earth 10m land, coastline and populated places. The first report without them downloads them (9 MB, 60 MB on disk) into cartopy’s data folder, once; offline, or when the download fails, it says no map and leaves the maps out.

xcap3d viz wavefield draws a store’s wavefield, a frame strip (PNG) and an animation (mp4, or GIF without imageio-ffmpeg; install the wavefield extra) of the strain at the nodes of one slice for one force:

xcap3d viz wavefield STA --gf DB --force fz --slice depth=15 --out wavefield

Other commands

compare, replay, db release, db check, build model and build sgt serve the operator, who builds and checks the database and compares databases; each has --help. Adding stations means building them and running xcap3d db release DB, which writes the next version and keeps the previous one.