Elasticity API

quantas.api.elasticity exposes second-order elastic analysis, exact transverse extrema, optional two-dimensional sections, sampled three-dimensional surfaces, neutral reports and plots, and native HDF5 persistence.

Minimal lifecycle

from quantas.api import elasticity

options = elasticity.Options(calculate_2d=True)
result_data = elasticity.run("calcite.dat", options=options)
result = elasticity.get_result(result_data)
print(result.averages.hill.bulk_modulus)

Use calculate_3d and SurfaceOptions only when three-dimensional fields must be persisted in the result. A transient 3-D surface can also be built later from the stored stiffness tensor with build_3d_plots().

Passive contracts and selectors

quantas.api.elasticity.Input

alias of ElasticityInput

quantas.api.elasticity.Options

alias of ElasticityOptions

quantas.api.elasticity.SurfaceOptions

alias of ElasticitySurfaceOptions

quantas.api.elasticity.Result

alias of ElasticityResult

PlotProperty and SurfaceProperty accept young, compressibility, shear, and poisson. SurfaceGeometry accepts physical or unit_sphere.

quantas.api.elasticity.PlotProperty

alias of Literal[‘young’, ‘compressibility’, ‘shear’, ‘poisson’]

quantas.api.elasticity.SurfaceProperty

alias of Literal[‘young’, ‘compressibility’, ‘shear’, ‘poisson’]

quantas.api.elasticity.SurfaceGeometry

alias of Literal[‘physical’, ‘unit_sphere’]

Input and calculation

quantas.api.elasticity.read_input(source)

Read one Quantas elasticity input file.

Parameters:
sourcestr or Path

Text input containing the job name, elastic stiffness tensor, and optional density metadata.

Returns:
Input

Validated passive elasticity input contract.

Raises:
ValueError

If the file is malformed or scientifically inconsistent.

Parameters:

source (str | Path)

Return type:

ElasticityInput

quantas.api.elasticity.normalize_input(source)

Return a normalized elasticity input contract.

Parameters:
sourceInput, str, or Path

Existing passive input contract or text input path.

Returns:
Input

Validated elasticity input suitable for run().

Raises:
TypeError

If source is neither an Input object nor a path.

ValueError

If a supplied file cannot be parsed.

Parameters:

source (ElasticityInput | str | Path)

Return type:

ElasticityInput

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

Run a second-order elasticity workflow.

Parameters:
input_dataInput, str, or Path

Elasticity input contract or text input path.

optionsOptions or None, optional

Scientific and numerical calculation options. Defaults are used when omitted.

observerObserver or None, optional

Frontend-neutral event observer.

Returns:
ResultData

Complete result envelope containing an elasticity payload.

Raises:
ValueError

If the input or selected calculation is invalid.

Parameters:

  • input_data (ElasticityInput | str | Path)

  • options (ElasticityOptions | None)

  • observer (Observer | None)

Return type:

ResultData

quantas.api.elasticity.get_result(result)

Return the typed elasticity payload from a result envelope.

Parameters:
resultResultData

Complete Quantas result envelope.

Returns:
Result

Module-specific elasticity result.

Raises:
ValueError

If the envelope belongs to another module or lacks a valid payload.

Parameters:

result (ResultData)

Return type:

ElasticityResult

Reporting and plotting

quantas.api.elasticity.build_report(result)

Build frontend-neutral elasticity report tables.

Parameters:
resultResultData

Complete elasticity result envelope.

Returns:
list of ReportTable

Ordered raw-value tables ready for terminal, text, CSV, or GUI rendering.

Raises:
ValueError

If the result envelope is invalid.

Parameters:

result (ResultData)

Return type:

list[ReportTable]

quantas.api.elasticity.build_plots(result)

Build the default frontend-neutral elasticity plots.

Parameters:
resultResultData

Complete elasticity result envelope.

Returns:
PlotCollection

Neutral plot specifications for properties present in the result.

Raises:
ValueError

If the result envelope is invalid.

Parameters:

result (ResultData)

Return type:

PlotCollection

quantas.api.elasticity.build_2d_plots(result, properties=None)

Build selected two-dimensional elasticity plots.

Parameters:
resultResultData

Complete elasticity result envelope.

propertiestuple of PlotProperty or None, optional

Directional properties to include. Module defaults are used when omitted.

Returns:
PlotCollection

Neutral two-dimensional plot specifications.

Raises:
ValueError

If required directional data are unavailable.

Parameters:

  • result (ResultData)

  • properties (tuple[Literal['young', 'compressibility', 'shear', 'poisson'], ...] | None)

Return type:

PlotCollection

quantas.api.elasticity.build_3d_plots(result, options=None, *, properties=None, geometry='physical', color_mode='property', colormap='viridis', show_mesh=False, mesh_color='black', mesh_line_width=0.5)

Build selected three-dimensional elasticity surfaces.

Parameters:
resultResultData

Complete elasticity result envelope.

optionsSurfaceOptions or None, optional

Directional sampling controls.

propertiestuple of SurfaceProperty or None, optional

Surface properties to include.

geometrySurfaceGeometry, optional

Unit-sphere or physical-radius representation.

color_mode{“solid”, “property”}, optional

Surface coloring strategy.

colormapstr, optional

Renderer-neutral colormap identifier.

show_meshbool, optional

Include mesh-line metadata.

mesh_colorstr, optional

Mesh-line color identifier.

mesh_line_widthfloat, optional

Mesh-line width metadata.

Returns:
PlotCollection

Neutral three-dimensional surface specifications.

Raises:
ValueError

If options are invalid or required surface data are unavailable.

Parameters:

  • result (ResultData)

  • options (ElasticitySurfaceOptions | None)

  • properties (tuple[Literal['young', 'compressibility', 'shear', 'poisson'], ...] | None)

  • geometry (Literal['physical', 'unit_sphere'])

  • color_mode (Literal['solid', 'property'])

  • colormap (str)

  • show_mesh (bool)

  • mesh_color (str)

  • mesh_line_width (float)

Return type:

PlotCollection

Persistence

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

Write a native Quantas elasticity HDF5 result.

Parameters:
resultResultData

Complete elasticity result envelope.

destinationstr or Path

Destination path. The native HDF5 suffix is applied when required.

report_textstr or None, optional

Deterministic plain-text report to embed in diagnostics.

Returns:
Path

Final HDF5 path.

Raises:
ValueError

If result does not contain an elasticity payload.

Parameters:

  • result (ResultData)

  • destination (str | Path)

  • report_text (str | None)

Return type:

Path

quantas.api.elasticity.read_result(source)

Read a native Quantas elasticity HDF5 result.

Parameters:
sourcestr or Path

Native Quantas HDF5 file.

Returns:
ResultData

Restored result envelope.

Raises:
ValueError

If the file is not a supported elasticity result.

Parameters:

source (str | Path)

Return type:

ResultData

See also