Python API reference

The public Python API uses NumPy arrays throughout. Build and install the libswd extension before running numerical examples. HDF5 support also requires h5py.

Solver workspace

class specd.SpecWorkSpace(wavetype: str = None, has_att: bool = False)

Bases: object

compute_dispersion(frequencies_hz: ndarray, azimuths_deg=0.0, include_group: bool = True)

Compute a frequency/azimuth grid as a CSR dispersion table.

Mode counts may vary between solve points. Rows use frequency-major, azimuth-minor order and remain ordinary NumPy arrays.

compute_egn(freq: float, ang_in_deg=0.0, only_phase=False) → ndarray

compute eigenvalues/eigenvectors

Parameters:

• freq (float) – current frequency

• ang_in_deg (float) – phase velocity azimuthal angle, in deg

• only_phase (bool) – if False, only compute eigenvalues (phase velocities) if True, phase velocities and eigenfunctions will be computed

Returns:

c – phase velocities

Return type:

np.ndarray

get_egnfunc(imode: int, return_displ: bool, return_left=False)

get eigenfunctions at current frequency/mode

Parameters:

• imode (int) – mode number

• return_left (bool) – if true, return left eigenvectors else return right eigenvectors

• return_displ (bool) – if true, return displacement polarization amplitudes instead of eigenvectors. For VTI Rayleigh/Scholte waves, the horizontal and vertical amplitudes retain a real convention; the physical pi/2 phase offset of the vertical component is implicit. For example, the corresponding eigenvector is [u,v^{ar},chi^{ar}].

get_group_kl(imode: int)

compute group velocity sensitivity kernels for mode {imode}

Parameters:

imode (int) – compute kernels at imode, imode elong [0,max_mode)

Returns:

• frekl_c (np.ndarray) – group velocity kernels, shape(nkers,self._nz)

• frekl_q (np.ndarray) – group velocity Q kernels,shape(nkers,self._nz), only returns when self._has_att = True

get_kernel_names()

get names for Frechet derivative

Returns:

kl_name – list of kernel names

Return type:

list[str]

get_phase_kl(imode: int)

compute phase velocity sensitivity kernels for mode {imode}

Parameters:

imode (int) – compute kernels at imode, imode elong [0,max_mode)

Returns:

• frekl_c (np.ndarray) – phase velocity kernels, shape(nkers,self._nz)

• frekl_q (np.ndarray) – phase velocity Q kernels,shape(nkers,self._nz), only returns when self._has_att = True

get_znodes()

get mesh coordiantes, shape(nspec*NGLL+NGRL)

group_velocity()

compute group velocites for each model at current frequency

Returns:

u – group velocities at current frequency. For general anisotropy, shape is (2, nmodes) with x and y components by row.

Return type:

float/complex

Note

before calling this routine, use_qz should be True in self.compute_egn

initialize(wavetype: str, z: ndarray, rho: ndarray, vph=None, vpv=None, vsh=None, vsv=None, eta=None, Qa=None, Qc=None, Qn=None, Ql=None, c21=None, Qani=None, qfunc_id=1, scale_rho=0.0, scale_v=0.0, scale_z=0.0, disp=False, reference_frequency=1.0)

initialize working space for SEM

Parameters:

• wavetype (str) – wavetype, one of [‘love’,’rayl’,’aniso’]

• z (np.ndarray) – depth vector, should include discontinuities at half sapce

• rho (np.ndarray) – density, shape_like(z)

• vph/vpv/vsh/vsv (np.ndarray) – VTI parameters, shape_like(z)

• Qa/Qc/Qn/Ql (np.ndarray) – VTI constant quality factors, shape_like(z)

• c21 (np.ndarray) – 21 elastic tensor, shape(21,nz)

• nQani (int) – no. of Q models for fully anisotropy

• Qnai (np.ndarray) – quality factors, shape(nQnai,nz)

• disp (bool) – if True print model information

• reference_frequency (float) – frequency in Hz at which the input storage moduli (and therefore the real input velocities) are defined; default is 1 Hz

Note

The input parameters should be carefully chose by user. For Love wave, only vsh/vsv/Qsh/Qsv can be enabled, and for Rayleigh wave, only vph/vpv/vsv can ve enabled, and other params are for full anisotropy

CSR dispersion containers

class specd.ComplexCSR(indptr: ndarray, mode_index: ndarray, values: ndarray, component_names: Tuple[str, ...])

Bases: object

Complex CSR rows indexed by solve point and local mode number.

component_names: Tuple[str, ...]

classmethod from_rows(rows: Sequence[ndarray], component_names: Sequence[str], mode_rows: Sequence[ndarray] | None = None) → ComplexCSR

Pack variable-length NumPy rows into a CSR container.

indptr: ndarray

mode_index: ndarray

property nentry: int

property nrow: int

row(row: int) → Tuple[ndarray, ndarray]

Return (mode_index, values) as zero-copy NumPy views.

validate(nrow: int, name: str = 'csr') → None

values: ndarray

class specd.DispersionTable(frequency_hz: ndarray, azimuth_deg: ndarray, phase_velocity: ComplexCSR, group_velocity: ComplexCSR | None = None, velocity_units: str = 'km/s')

Bases: object

CSR dispersion data on a frequency/azimuth grid.

azimuth_deg: ndarray

frequency_hz: ndarray

classmethod from_hdf5(path) → DispersionTable

Read and validate a version-1 SpecSWD CSR HDF5 file.

classmethod from_rows(frequency_hz, phase_rows: Sequence[ndarray], *, azimuth_deg=(0.0,), phase_mode_rows: Sequence[ndarray] | None = None, group_rows: Sequence[ndarray] | None = None, group_components: Sequence[str] = ('radial',), group_mode_rows: Sequence[ndarray] | None = None, velocity_units: str = 'km/s') → DispersionTable

Create a table directly from variable-length solver outputs.

group_row(frequency_index: int, azimuth_index: int = 0) → Tuple[ndarray, ndarray]

group_velocity: ComplexCSR | None = None

property nsolve: int

phase_row(frequency_index: int, azimuth_index: int = 0) → Tuple[ndarray, ndarray]

phase_velocity: ComplexCSR

solve_row(frequency_index: int, azimuth_index: int = 0) → int

Map grid indices to the frequency-major CSR row.

to_hdf5(path) → None

Write schema-versioned CSR data using HDF5 compound complex values.

validate() → None

velocity_units: str = 'km/s'

Complete solver output

class specd.RaggedComplexField(indptr: ndarray, values: ndarray, component_names: Tuple[str, ...], units: str = 'normalized')

Bases: object

Variable-length complex samples with a fixed component dimension.

component_names: Tuple[str, ...]

indptr: ndarray

property nrow: int

row(row: int) → ndarray

Return one field as a zero-copy (npoint,ncomponent) view.

units: str = 'normalized'

validate(nrow: int | None = None) → None

values: ndarray

class specd.KernelTable(parameter_names: Tuple[str, ...], velocity: ndarray, propagation_q_inverse: ndarray | None = None)

Bases: object

Projected kernels with shape (nmode,nparameter,ndepth).

parameter_names: Tuple[str, ...]

propagation_q_inverse: ndarray | None = None

velocity: ndarray

class specd.SolverOutput(dispersion: DispersionTable, wave_type: int, attenuation: bool, kernel_type: int, kernel_observable: str, model_depth: ndarray, sem_depth_indptr: ndarray, sem_depth_values: ndarray, eigenfunctions: RaggedComplexField, elastic_kernels: KernelTable | None = None, acoustic_kernels: KernelTable | None = None)

Bases: object

Complete command-line result backed only by NumPy containers.

acoustic_kernels: KernelTable | None = None

attenuation: bool

dispersion: DispersionTable

eigenfunctions: RaggedComplexField

elastic_kernels: KernelTable | None = None

classmethod from_hdf5(path) → SolverOutput

Read complete output written by a C++ or Python solver.

kernel_observable: str

kernel_type: int

model_depth: ndarray

sem_depth_indptr: ndarray

sem_depth_row(solve_row: int) → ndarray

Return the physical SEM depth coordinates for one solve row.

sem_depth_values: ndarray

to_hdf5(path) → None

Write the complete version-1 solver output.

validate() → None

wave_type: int

Constant-Q helpers

specd.constant_q_response(freq, quality_factor, reference_frequency=1.0)

Return M(omega) / M0 for storage modulus M0 at the reference.

The response uses the positive-frequency convention of SpecSWD:

s = (1 + i/Q) * (freq/reference_frequency)**alpha, alpha = 2/pi * atan(1/Q).

specd.constant_q_response_derivatives(freq, quality_factor, reference_frequency=1.0)

Return s, ds/domega, ds/d(Q^-1), and the mixed derivative.

Thomson-Haskell comparison solver

class specd.THSolver(thick: ndarray, vp: ndarray, vs: ndarray, rho: ndarray, spherical: bool = False)

Bases: object

compute_swd(wavetype: str, mode: int, T: ndarray) → ndarray

compute dispersion (phase/group) for a give wavetype

Parameters:

• wavetype (str) – wave type, one of [‘Rc’,’Rg’,’Lc’,’Lg’]

• mode (int) – which mode it will return, >=0

• T (np.ndarray) – period, in s

Returns:

cg – phase velocity (for Rc,Lc) or group velocity (Rg,Lg)

Return type:

np.ndarray