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

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.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.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