PyTorch API reference

Install the optional backend with python -m pip install '.[torch]' and import it from specd.torch. It runs without the native extensions. See PyTorch backend for model conventions, differentiation, kernel units, and runnable examples.

Solver workspace

class specd.torch.SpecWorkSpace(wavetype=None, *, device=None, ngll=7, ngrl=30, halfspace_wavelengths=50)

Bases: object

Independent PyTorch implementation of the SpecSWD spectral solver.

Model tensors retain their graphs. Non-tensor inputs become float64 leaf tensors requiring gradients, accessible through parameters. Geometry, adaptive element counts, interpolation locations and mode selection are discrete, fixed decisions during differentiation.

compute_dispersion(frequencies_hz, azimuths_deg=0.0, include_group=True)

compute_egn(freq, ang_in_deg=0.0, only_phase=False)

get_egnfunc(imode, return_displ=True, return_left=False)

Return displacement at SEM nodes or the raw right eigenvector.

Anisotropic displacements use radial/transverse/vertical components; Rayleigh uses the native real polarization amplitude convention.

get_group_kl(imode)

get_kernel_names()

get_phase_kl(imode)

group_velocity()

All modes at once using operator JVPs and eigenvalue perturbation.

For P(k,f)r=0, dk/df = -(l^H P_f r)/(l^H P_k r). Forward-mode autodiff computes the operator partials without one eigensolver backward per mode. Keeping the eigenvectors in the graph supports group kernels.

initialize(wavetype, z, rho, *, vph=None, vpv=None, vsh=None, vsv=None, eta=None, Qa=None, Qc=None, Qn=None, Ql=None, c21=None, Qani=None, reference_frequency=1.0)

kernels(imode=0, *, observable='phase', component='real', create_graph=False)

Return named autograd derivatives on the original model grid.

Q derivatives here are d/dQ. get_phase_kl and get_group_kl convert these to d/d(Q^-1), matching the native kernel convention. Anisotropic group kernels use the radial group component.

property parameters

Tensor dispersion tables

class specd.torch.DispersionTable(frequency_hz: 'torch.Tensor', azimuth_deg: 'torch.Tensor', phase_rows: 'list', group_rows: 'list | None' = None, group_components: 'tuple' = ('radial',), phase_mode_rows: 'list | None' = None, group_mode_rows: 'list | None' = None)

Bases: object

azimuth_deg: Tensor

frequency_hz: Tensor

classmethod from_hdf5(path, *, device=None)

Read detached float64/complex128 tensors from a v1 dispersion file.

group_components: tuple = ('radial',)

group_mode_rows: list | None = None

group_row(row)

group_rows: list | None = None

phase_mode_rows: list | None = None

phase_row(row)

phase_rows: list

to_hdf5(path)

Write the existing specswd-dispersion v1 schema; detach at IO only.

Material helpers

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

specd.torch.isotropic_c21(rho, vp, vs)

Build (21,nz) stiffnesses without breaking the input autograd graph.