Author: He XingChen

Last Updated: 2026-08-22

API Reference

Main Functions

run_hash()

Determine focal mechanism from P-wave polarities.

result = run_hash(p_azi, p_the, p_pol, p_qual, **kwargs)

Parameters:

Name	Type	Default	Description
p_azi	ndarray	required	Azimuths (degrees), shape (nsta,) or (nsta, nmc)
p_the	ndarray	required	Takeoff angles (degrees)
p_pol	ndarray	required	Polarities: 1=up, -1=down
p_qual	ndarray	required	Quality: 0=impulsive, 1=emergent
dang	float	5.0	Grid angle increment
nmc	int	30	Monte Carlo trials
maxout	int	500	Max output mechanisms
badfrac	float	0.1	Allowed bad polarity fraction
npolmin	int	8	Minimum polarities
max_agap	float	90.0	Max azimuth gap
max_pgap	float	60.0	Max plunge gap

Returns:

Key	Type	Description
success	bool	Solution found
strike_avg	float	Strike (degrees)
dip_avg	float	Dip (degrees)
rake_avg	float	Rake (degrees)
quality	str	A, B, C, D, E, or F
mfrac	float	Misfit fraction (0-1)
prob	float	Solution probability
stdr	float	Station distribution ratio
nout2	int	Number of solutions

---

run_hash_with_amp()

Determine mechanism using polarities + S/P amplitude ratios.

result = run_hash_with_amp(p_azi, p_the, p_pol, sp_amp, **kwargs)

Additional Parameter:

Name	Type	Description
sp_amp	ndarray	S/P ratios (log10), 0.0 = no data

Additional Returns:

Key	Type	Description
mavg	float	Amplitude misfit (log10)
npol	int	Polarity count
nspr	int	S/P ratio count

---

run_hash_batch() / run_hash_batch_with_amp()

Process many events in one native call (event-level OpenMP).

results = run_hash_batch(events, nmc=30, backend="fortran", num_threads=16)

run_hash_from_file()

Process events from HASH input file.

results = run_hash_from_file("example.inp")

---

Quality Rating

Grade	Criteria
A	prob > 0.8, var ≤ 25°, misfit ≤ 15%, stdr ≥ 0.5
B	prob > 0.6, var ≤ 35°, misfit ≤ 20%, stdr ≥ 0.4
C	prob > 0.5, var ≤ 45°, misfit ≤ 30%, stdr ≥ 0.3
D	Solution found but below C criteria
E	Azimuth or plunge gap too large
F	No acceptable mechanism found

---

Modules

Module	Functions	Description
driver.py	run_hash, run_hash_with_amp, run_hash_batch, run_hash_from_file	Main entry points
backend/fortran_backend.py	run_event, run_event_amp, run_batch, build_velocity_table, get_tts	Native backend binding
io.py	read_phase_file, write_mechanism_output	File I/O
utils.py	fp_coord_angles_to_vectors, fp_coord_vectors_to_angles	Coordinate conversions

---

Low-Level Backend Methods

These live on the Fortran backend instance (via backend.get_backend("fortran")) and are used by the test suite to pin results to the original HASH:

run_event()

Full polarity-only pipeline for one event (equivalent to run_hash without input normalization).

run_event_amp()

Full polarity + S/P amplitude pipeline for one event.

run_batch() / run_batch_amp()

Batch pipelines (CSR-style flat arrays) used by run_hash_batch and run_hash_batch_with_amp.

mech_prob()

Preferred mechanism(s) and probability from a set of acceptable mechanisms.

result = backend.mech_prob(nf, faults, slips, cangle=45.0, prob_max=0.1)

get_misfit() / get_misfit_amp() / get_gap()

Misfit fractions, station distribution ratio, and azimuthal/takeoff gaps for a given mechanism.

build_velocity_table() / get_tts()

Takeoff-angle table construction and interpolation for 1D velocity models.

get_rotation_grid()

The cached rotation grid for a given dang (b1/b2/b3 direction cosines).

---

Takeoff Angle API

Public wrappers over the native velocity tables (cnchash.takeoff):

Callable	Description
TakeoffTable(depth, velocity, params=None, backend="auto")	Build a takeoff-angle table from a 1D velocity model (MK_TABLE). Tables are cached per model content
TakeoffTable.takeoff(distance, source_depth)	Scalar lookup; raises TakeoffRangeError outside the usable range
TakeoffTable.takeoff_batch(distances, source_depths)	Vectorized lookup with broadcasting; NaN outside the range
compute_takeoff_angles(depth, velocity, distances, source_depths, ...)	One-shot convenience: build table and look up
DEFAULT_TABLE_PARAMS	Default table ranges (del 0-120 km step 1, dep 0-35 km step 1, nump 1000)

Convention: degrees from the vertical, 0 = straight up, 90 = horizontal, 180 = straight down.

---

Complete Original-HASH Coverage

The Python interface covers the full original Fortran functionality:

Original Fortran	Python interface
driver1 (FPFIT file takeoffs)	read_phase_file parses file azimuth/takeoff/uncertainties; process_event Monte Carlos with per-station uncertainties
driver2 (velocity tables)	velocity_models argument + TakeoffTable; depth perturbation + model rotation
driver3 (S/P amplitudes)	read_amp_file + read_statcor_file + ratmin SNR filtering; automatically runs run_hash_with_amp
driver5 (SIMULPS takeoffs)	read_simul_takeoff_file + simul argument; polarities matched by event id/station name
CHECK_POL / GETSTAT	read_polarity_reversal_file / read_station_file (incl. TRI format)
MK_TABLE / GET_TTS	TakeoffTable / compute_takeoff_angles
MECH_ROT	kagan_angle(n1, s1, n2, s2) (native binding)
Core version	backend.get_backend("fortran").native_version()