API

The command line is the main interface. These are the functions behind it, for scripts.

xcap3d.Result

class xcap3d.Result

The record of a run (result.json): a dict, with shortcuts to the solution.

str() and repr() give the solution line of xcap3d run and a line with the stations, the jackknife’s 90th percentile Kagan angle and, with a non-DC search, the ISO, CLVD and DC percentages; for a run without a solution or that failed, its status and reason.

classmethod from_file(path)

The record in the result.json at path.

property depth

Depth of the solution [km].

property vr

Variance reduction [%].

property mt_ned

The double couple’s unit tensor (xx, xy, xz, yy, yz, zz), x north, y east, z down.

xcap3d.cli

The xcap3d command line: run, download, process, invert, replay, report, compare, catalog and build.

The output directory is --out, else XCAP3D_OUT, else ./xcap3d-out. The reference catalog files are read from the directory --catalogs, else XCAP3D_CATALOGS; without either, the record lists every reference as not given. The raw download goes to <out>/<id>/raw/ and the waveforms with the full instrument response removed to <out>/<id>/data-full/. With --label, result.json, report.html and the figures go to <out>/<id>/models/<label>/, so several Green’s-function sets can be compared on one download; without it they go to <out>/<id>/.

Defaults: the station jackknife on.

xcap3d.cli.run_event(event_id, gf, *, jackknife=None, edge_margin_km=10.0, near_field_cells=1, write_report=False, label=None, out=None, device='auto', release=None, catalogs=None, mt='dc', refine=False, grid_step=5.0, refine_step=1.0, verbose=True)

Run xcap3d run from a script: download if needed, invert, write result.json and return the record.

A production run reads <out>/<id>/data-full, made from the raw download <out>/<id>/raw when missing. A production run that ends without a solution (no station or depth left, a store that differs from the release, an incomplete download) writes a record with status ‘no_solution’ and the reason. A run that crashes writes a record with status ‘error’, the exception’s type and message, and raises it. The record’s run_spec names mt, refine, grid_step and refine_step only when they are not the defaults.

Parameters:

• event_id – SCEDC event id.

• gf – the database, a directory of HDF5 stores.

• jackknife – None or True for the station jackknife (uncertainty.fast_jackknife), False for none.

• edge_margin_km – drop a station whose box edge is closer than this to the epicenter [km].

• near_field_cells – drop a station-centered box’s station when the epicenter is within this many lattice cells of the station node.

• write_report – also write report.html next to result.json.

• label – name of the Green’s-function set; the products go to <out>/<id>/models/<label>/.

• out – output directory; default XCAP3D_OUT, else ./xcap3d-out.

• device – “auto” (a GPU if torch sees one), “cpu” (or None) or “cuda:N”, chosen once for every search of the run.

• release – the database’s release file; default <gf>/release.json. A production run needs one.

• catalogs – directory of the reference catalog files; default XCAP3D_CATALOGS.

• mt – ‘dc’ (default), ‘deviatoric’ (‘dev’) or ‘full’. The last two add the non-DC search at the chosen depth around the DC solution (orient.search_nondc) as the record’s non_dc block; the DC solution is unchanged.

• refine – after each double-couple search, search 1-deg nodes within Kagan 8 deg of up to 3 coarse minima (orient.refine_search) and keep the lowest misfit.

• grid_step – spacing of the strike/dip/rake grid [deg], more than 0 and at most 30.

• refine_step – spacing of the fine nodes of refine [deg], less than half its radius (1.6 grid_step); only with refine.

• verbose – print each stage as it starts and ends (download, processing, Green’s functions, QC, depth scan, moment tensor, jackknife); False prints only the solution line.

Returns:

The result record as written to result.json, a Result.

Raises:

SystemExit – an option has an invalid value, or the inversion cannot start.

xcap3d.cli.replay(result, out, data=None, device=None, catalogs=None)

Run a recorded production run again, offline, and return how the new record differs from the recorded one.

The inputs and release file must match the recorded sha256. The records are compared without paths, clock, file times and environment (printed as notes); the fits are compared by digest. The settings come from this code, so a default that changed since the run shows as a difference.

Parameters:

• result – path of the recorded result.json; the record must be complete.

• out – output directory for the replay.

• data – the download, if it has moved since the run; default the recorded path.

• device – default the device the run used.

• catalogs – directory of the reference catalog files; default XCAP3D_CATALOGS.

Returns:

The differences, empty when the records agree.

xcap3d.cli.download_event(event_id, out=None)

Download an event (QuakeML, StationXML and raw seismograms) into <out>/<id>/raw.

Does nothing if that folder exists (fetch.download_raw).

Parameters:

• event_id – SCEDC event id.

• out – output directory; default XCAP3D_OUT, else ./xcap3d-out.

Returns:

The raw folder.

xcap3d.cli.process_event(event_id, out=None)

Remove the full instrument response from <out>/<id>/raw into <out>/<id>/data-full, the folder run reads.

Does nothing if that folder exists (fetch.process_raw), and stops if an xcap3d of another store version made it.

Parameters:

• event_id – SCEDC event id.

• out – output directory; default XCAP3D_OUT, else ./xcap3d-out.

Returns:

The data-full folder.

xcap3d.cli.invert_event(event_id, gf, **settings)

Run run_event on waveforms already processed, never downloading.

Parameters:

• event_id – SCEDC event id.

• gf – as in run_event.

• **settings – the other keyword arguments of run_event.

Returns:

The result record.

Raises:

SystemExit – <out>/<id>/data-full holds no processed waveforms.

xcap3d.gf.release

The release file of a Green’s-function database: every station’s files with size, fingerprint and sha256.

xcap3d db release writes it as <db>/release.json, or elsewhere for a read-only database; it never modifies a store. A production run refuses a store that does not match its release and records the release in result.json, so a result names the exact Green’s functions it used.

The release states what the stations share (COMMON: engine, source pulse, time axis, lattice, frame, Q); stores that differ there cannot form one release. Per station it keeps the model text, the receiver position, the source-pulse family (filter and solver step, e.g. ks10@0.002s) checked against xcap3d.gf.pulse and, with --acceptance DIR, the acceptance record rollout_<STA>.json. Stores of two pulse families can form one release; a run records the family of every station it used.

The fingerprint is the sha256 of the size and the first and last MiB of a file: cheap enough for every run, and it covers the HDF5 superblock and attributes as well as data at the end. The whole-file sha256 is computed once and checked by xcap3d db check --full. A release written with --no-hash says hashed: false, and so does every result made with it.

xcap3d.gf.release.write_release(db, out=None, name=None, version=None, hashed=True, workers=1, acceptance=None)

Write the release file of a database and return its path.

Every store must meet the store contract (storeformat.check_store). Written to <db>/release.json (the default out), an existing file of version N is kept as <db>/release-vN.json and the new file, of version N + 1, is made read-only. With hashed, the digests go to <out>.hashes as they are computed, with each file’s size and modification time, so a stopped run resumes and never reuses the digest of a changed file.

Parameters:

• db – database directory.

• out – release file to write; default <db>/release.json.

• name – database name in the release id; default the directory name.

• version – release version; default N + 1, or 1 with an out elsewhere.

• hashed – compute every file’s sha256.

• workers – threads hashing files.

• acceptance – directory of the acceptance records rollout_<STA>.json; None for none.

Returns:

Path of the release file.

Raises:

ReleaseError – a store breaks the store contract, the stores differ in a COMMON attribute, version is not larger than the current one, or the archive name exists.

xcap3d.gf.release.read_release(db, path=None)

Read the release file of a database.

Parameters:

• db – database directory.

• path – release file; default <db>/release.json.

Returns:

The release record, with file (its path) and file_sha256.

Raises:

ReleaseError – the file is missing or cannot be used.

xcap3d.gf.release.station_problems(db, release, sta, full=False)

How a station’s files differ from the release.

Parameters:

• db – database directory.

• release – release record (read_release).

• sta – station name.

• full – also compare each file’s whole sha256.

Returns:

List of problems (missing, other size, other fingerprint, other sha256, not in the release); empty if none.

xcap3d.gf.storeformat

The Green’s-function store contract in machine-readable form and a read-only checker.

KEYS lists every dataset and attribute of an HDF5 store: type, unit, allowed values, meaning, and from which format version and for which store roles it is required. A store without format_version is version 0, the only version: the stores of the production and LA databases, as the builder writes them.

check_store lists the problems of one store and check_db those of a database, including what a shallow / deep pair and the stores of one database must share. Both open files read-only. A problem is a string “<kind>: <text>” with the kind in KINDS.

The HDF5 files are read without visititems, which asks for the chunked dataset’s storage size and so walks its whole chunk index (seconds per file on NFS).

xcap3d.gf.storeformat.check_store(path, data=True)

List the problems of one store, read-only.

Parameters:

• path – an HDF5 store.

• data – also read one column per force and check it is finite and not all zero.

Returns:

<text>”; empty for a good store.

Return type:

List of problems, “<kind>

xcap3d.gf.storeformat.check_db(db, data=True, workers=1)

List the problems of every store of a database, read-only.

Checks the primary stores (<db>/*.h5, <db>/deep/*.h5) and the shallow stores they name, then what the database must share: no orphan shallow store, one layout per station, one value of each COMMON attribute.

Parameters:

• db – database directory.

• data – as in check_store.

• workers – processes checking stores.

Returns:

[problems]}, database=[problems], stamps_before, stamps_after), the stamps showing that no file changed.

Return type:

dict(stores={relative path

xcap3d.report.products

fits.h5: the observed and synthetic windows of a production run at every scanned depth.

Written from the stations and solutions the run held, so a report or viewer can draw the fits without re-deriving them. Layout: file attributes format_version, dt and components; one group per depth ("11.5"; attributes depth, strike, dip, rake, m0, mw); one subgroup per loaded station (attributes dist, weight, shift, cc and t0, the window start [s after the origin], one value per component, and in_search); and in it one dataset per component (Pz, Pr, Sz, Sr, Sh) of shape (2, n): the observed window and the unshifted synthetic of that depth’s solution, in the data’s units (m0 times the Green’s functions times the tensor, as invert.grid_search defines it). The shift is the lag at which data sample t + shift / dt best matches synthetic sample t. Stations the amplitude screen or the pre-pass left out have in_search false, weight 0 and NaN shift and CC. fits_digest is the sha256 of the content; result.json names it, so a record and its fits.h5 can be matched.

xcap3d.report.products.fits_digest(fits)

sha256 of the content of fits, the same for the run’s arrays and for the file written from them.

Parameters:

fits – {depth: fits_of(…)}, or read_all of a file.

Returns:

Hex digest.

xcap3d.report.products.write_fits(path, fits, dt)

Write the fits of a run to path, through a temporary file.

Parameters:

• path – the fits.h5 file.

• fits – {depth: fits_of(…)}.

• dt – sample interval [s].

xcap3d.report.report

Reports: the per-event report.html, the compare.html of one event over several Green’s-function sets, and the catalog.html index, from the records of record.py.

Replaces genFIGURE.csh + genREPORT.csh. No number is changed: the fit figure re-reads the waveforms at the chosen depth without inverting. The figures are in viz.py.

xcap3d.report.report.write_event_report(result, out_dir, event_meta=None, refs=None, figures=True)

Write report.html and its figures from a result record.

The page carries its figures as data URIs, so it shows them anywhere on its own; the PNG files stay for the catalog page and for reuse.

A labeled model run (greens key, <id>/models/<label>/) links back to the event’s comparison page.

Parameters:

• result – the result.json record; must be of schema SCHEMA.

• out_dir – directory for the page and figures.

• event_meta – overrides the record’s event.

• refs – overrides the record’s references.

• figures – draw the figures; False re-renders the page around existing PNGs.

Returns:

Path of report.html.

Raises:

ValueError – the record is not of schema SCHEMA.

xcap3d.report.report.write_compare(event_dir, labels=None, reference=None)

Write <event_dir>/compare.html: every model of one event in one self-contained page.

A strip lists all models (mechanism, Mw, depth, VR, and Kagan / dMw / ddepth to the reference) above the event page of the selected model, switched by the drop-down, the arrow keys or the strip; #m=<label>&ref=<label> in the URL selects. Figures are embedded as data URIs; records without figures get them first (write_event_report).

Parameters:

• event_dir – the event directory holding models/<label>/result.json.

• labels – models to include, in this order; default all, alphabetical.

• reference – the reference model; default the first label.

Returns:

Path of compare.html.

Raises:

ValueError – the event has no model result.