SEISMIC API

quantas.api.seismic exposes directional Christoffel analysis from phase velocity through group velocity, polarization tracking, acoustic enhancement, caustic candidates, neutral summaries and surfaces, CSV export, and native HDF5 persistence.

Minimal lifecycle

from quantas.api import seismic

options = seismic.Options(
    level="group",
    ntheta=61,
    nphi=121,
    track_polarization_axes=True,
)
result_data = seismic.run("hydroxylapatite.dat", options=options)
result = seismic.get_result(result_data)
print(result.field.phase.phase_speeds.shape)

The sampling resolution is controlled by ntheta and nphi. Batch size controls memory and throughput only; it does not change the sampled directions or numerical accuracy.

Passive contracts and selectors

class quantas.api.seismic.ElasticMedium(elastic_tensor, density)

Bases: object

Associate an elastic stiffness tensor with a material density.

Parameters:

elastic_tensorElasticTensor: Elastic stiffness tensor expressed in GPa.
densityfloat: Material density in kg m^-3.

Raises:

TypeError: If elastic_tensor is not an ElasticTensor instance.
ValueError: If density is non-finite or not strictly positive.

Parameters:

elastic_tensor (ElasticTensor)
density (float)

quantas.api.seismic.Input: alias of SeismicInput

quantas.api.seismic.Options: alias of SeismicOptions

quantas.api.seismic.PlotOptions: alias of SeismicPlotOptions

quantas.api.seismic.SurfaceOptions: alias of SeismicSurfaceOptions

quantas.api.seismic.Result: alias of SeismicResult

quantas.api.seismic.InputInterface: alias of Literal[‘crystal’, ‘vasp’]

The public enums below are the same types used by Options and SurfaceOptions; CLI and GUI clients do not need imports from implementation packages.

class quantas.api.seismic.Hemisphere(*values)

Bases: str, Enum

Supported polar domains for regular spherical grids.

class quantas.api.seismic.SamplingLevel(*values)

Bases: str, Enum

Highest acoustic quantity evaluated by a sampling operation.

class quantas.api.seismic.WaveMode(*values)

Bases: str, Enum

Identify the three acoustic modes in ascending phase-speed order.

The two quasi-shear modes are labelled according to the conventional split-shear notation: \(V_{S1}\) is the faster mode and \(V_{S2}\) is the slower mode.

class quantas.api.seismic.TensorRotation(matrix, kind=TensorRotationKind.MATRIX, angles=None, angle_unit=None, description=None)

Bases: object

User-defined transformation from the source to the analysis frame.

The stored matrix follows the Quantas component convention

T'_{ij...} = R_ia R_jb ... T_ab....

Parameters:

matrixarray_like: Proper orthogonal matrix with shape (3, 3). Its rows are the analysis-frame basis vectors expressed in the source frame.
kindTensorRotationKind or str, optional: Description used to construct the matrix.
anglestuple of float or None, optional: Input angles for an xyz construction.
angle_unitstr or None, optional: Unit of angles. Currently "degree" or "radian".
descriptionstr or None, optional: Optional user-facing description saved with result provenance.

Raises:

ValueError: If the matrix or angular provenance is invalid.

Parameters:

matrix (NDArray[float64])
kind (TensorRotationKind)
angles (tuple[float, float, float] | None)
angle_unit (str | None)
description (str | None)

classmethod from_matrix(matrix, *, description=None)

Build a transformation from an explicit rotation matrix.

Parameters:

matrixarray_like: Proper orthogonal 3 x 3 component-transformation matrix.
descriptionstr or None, optional: Optional provenance note.

Returns:

TensorRotation: Validated matrix transformation.

Parameters:

matrix (ArrayLike)
description (str | None)

Return type:

TensorRotation

classmethod from_xyz(x, y, z, *, degrees=True, description=None)

Build a transformation from ordered right-handed XYZ rotations.

The rotations are applied about the fixed source axes in the order x, then y, then z. For column-vector matrices this gives R = Rz(z) @ Ry(y) @ Rx(x). The resulting matrix is used directly in the Quantas tensor-component transformation.

Parameters:

x, y, zfloat: Rotation angles about the fixed source Cartesian axes.
degreesbool, optional: Interpret the supplied angles as degrees when True.
descriptionstr or None, optional: Optional provenance note.

Returns:

TensorRotation: Validated XYZ transformation.

Parameters:

x (float)
y (float)
z (float)
degrees (bool)
description (str | None)

Return type:

TensorRotation

as_mapping()

Return a serialization-friendly provenance mapping.

Returns:

dict: Rotation kind, convention, matrix and optional angular input.

Return type:

dict[str, Any]

class quantas.api.seismic.TensorRotationKind(*values)

Bases: str, Enum

Supported user descriptions of a tensor-component transformation.

SurfaceType accepts phase, slowness, or group. SurfaceGeometry accepts physical or unit_sphere.

quantas.api.seismic.SurfaceType: alias of Literal[‘phase’, ‘slowness’, ‘group’]

quantas.api.seismic.SurfaceGeometry: alias of Literal[‘physical’, ‘unit_sphere’]

Input and calculation

quantas.api.seismic.create_input(source, destination, *, interface='crystal', jobname='Unknown')

Create a Quantas seismic input from an external-code output.

Parameters:

sourcestr or Path: CRYSTAL or VASP output containing an elastic stiffness tensor and enough structural metadata to determine a finite positive density.
destinationstr or Path: Destination text path. The .dat suffix is applied when absent.
interface{“crystal”, “vasp”}, optional: External-code reader used to interpret source.
jobnamestr, optional: Human-readable title written to the generated input.

Returns:

Path: Written Quantas seismic input path.

Raises:

ValueError: If the interface is unsupported, the source cannot be parsed, or finite positive density metadata are unavailable.
OSError: If the destination cannot be written.

Parameters:

source (str | Path)
destination (str | Path)
interface (Literal['crystal', 'vasp'])
jobname (str)

Return type:

Path

quantas.api.seismic.read_input(source)

Read one Quantas seismic input file.

Parameters:

sourcestr or Path: Text input containing stiffness and density.

Returns:

Input: Validated passive seismic input contract.

Raises:

ValueError: If the file is malformed or lacks valid density/stiffness data.

Parameters:

source (str | Path)

Return type:

SeismicInput

quantas.api.seismic.normalize_input(source)

Return a normalized seismic input contract.

Parameters:

sourceInput, ElasticMedium, str, or Path: Existing input, physical elastic medium, or text input path.

Returns:

Input: Validated seismic input suitable for run().

Raises:

TypeError: If the source type is unsupported.
ValueError: If physical input data are invalid.

Parameters:

source (SeismicInput | ElasticMedium | str | Path)

Return type:

SeismicInput

quantas.api.seismic.run(input_data, options=None, observer=None)

Run a directional seismic-wave workflow.

Parameters:

input_dataInput, ElasticMedium, str, or Path: Seismic input, physical medium, or text input path.
optionsOptions or None, optional: Sphere sampling, degeneracy, tracking, and field controls.
observerObserver or None, optional: Frontend-neutral event observer.

Returns:

ResultData: Complete result envelope containing a seismic payload.

Raises:

ValueError: If stiffness, density, or numerical options are invalid.

Parameters:

input_data (SeismicInput | ElasticMedium | str | Path)
options (SeismicOptions | None)
observer (Observer | None)

Return type:

ResultData

quantas.api.seismic.get_result(result)

Return the typed seismic payload from a result envelope.

Parameters:

resultResultData: Complete Quantas result envelope.

Returns:

Result: Module-specific seismic result.

Raises:

ValueError: If the envelope is not a valid seismic result.

Parameters:

result (ResultData)

Return type:

SeismicResult

Reports, summaries, and surfaces

quantas.api.seismic.build_report(result, *, level='extended')

Build frontend-neutral seismic report tables.

Parameters:

resultResultData: Complete seismic result envelope.
level{“standard”, “extended”, “debug”}, optional: Scientific report detail.

Returns:

list of ReportTable: Ordered extrema, anisotropy, wave-property, and diagnostic tables.

Raises:

ValueError: If the result envelope is invalid.

Parameters:

result (ResultData)
level (Literal['standard', 'extended', 'debug'])

Return type:

list[ReportTable]

quantas.api.seismic.describe_plots(result)

Return result-aware seismic plot properties and representations.

Parameters:

resultResultData: Complete seismic result envelope.

Returns:

PlotInventory: Available scalar fields, acoustic surface families, modes, projections, geometries, and result-conditioned overlay contexts.

Parameters:

result (ResultData)

Return type:

PlotInventory

quantas.api.seismic.build_summary(result, options=None)

Build a frontend-neutral summary of extrema and anisotropy.

Parameters:

resultResultData: Complete seismic result envelope.
optionsPlotOptions or None, optional: Quantity and branch selections used in the summary.

Returns:

SphericalSummarySpec: Structured extrema, directions, and anisotropy metadata.

Raises:

ValueError: If required spherical fields are unavailable.

Parameters:

result (ResultData)
options (SeismicPlotOptions | None)

Return type:

SphericalSummarySpec

quantas.api.seismic.build_plots(result, options=None)

Build frontend-neutral seismic plots.

Parameters:

resultResultData: Complete seismic result envelope.
optionsPlotOptions or None, optional: Selected quantities, sections, and plot metadata.

Returns:

PlotCollection: Neutral two-dimensional and summary plot specifications.

Raises:

ValueError: If requested quantities are unavailable.

Parameters:

result (ResultData)
options (SeismicPlotOptions | None)

Return type:

PlotCollection

quantas.api.seismic.build_surfaces(result, options=None)

Build frontend-neutral seismic surface plots.

Parameters:

resultResultData: Complete seismic result envelope.
optionsSurfaceOptions or None, optional: Surface geometry, quantities, color fields, and mesh controls.

Returns:

PlotCollection: Neutral three-dimensional surface specifications.

Raises:

ValueError: If requested fields are unavailable or incompatible.

Parameters:

result (ResultData)
options (SeismicSurfaceOptions | None)

Return type:

PlotCollection

Export and persistence

quantas.api.seismic.write_csv(result, destination)

Write sampled seismic data in CSV form.

Parameters:

resultResultData: Complete seismic result envelope.
destinationstr or Path: Destination CSV path.

Returns:

Path: Final CSV path.

Raises:

ValueError: If the result envelope is invalid.

Parameters:

result (ResultData)
destination (str | Path)

Return type:

Path

quantas.api.seismic.write_result(result, destination, *, report_text=None)

Write a native Quantas seismic HDF5 result.

Parameters:

resultResultData: Complete seismic result envelope.
destinationstr or Path: Destination path.
report_textstr or None, optional: Deterministic report text to embed in diagnostics.

Returns:

Path: Final native HDF5 path.

Raises:

ValueError: If the result envelope is invalid.

Parameters:

result (ResultData)
destination (str | Path)
report_text (str | None)

Return type:

Path

quantas.api.seismic.read_result(source)

Read a native Quantas seismic HDF5 result.

Parameters:

sourcestr or Path: Native Quantas HDF5 path.

Returns:

ResultData: Restored result envelope.

Raises:

ValueError: If the file is not a supported seismic result.

Parameters:

source (str | Path)

Return type:

ResultData

SEISMIC API

Minimal lifecycle

Passive contracts and selectors

Input and calculation

Reports, summaries, and surfaces

Export and persistence

See also