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

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

class quantas.api.elasticity.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.elasticity.TensorRotationKind(*values)

Bases: str, Enum

Supported user descriptions of a tensor-component transformation.

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.create_input(source, destination, *, interface='crystal', jobname='Unknown')

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

Parameters:

sourcestr or Path: CRYSTAL or VASP output containing an elastic stiffness tensor and, when available, density metadata.
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 elasticity input path.

Raises:

ValueError: If the interface is unsupported or the source cannot be parsed.
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.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.describe_plots(result)

Return result-aware elasticity plot properties and representations.

Parameters:

resultResultData: Complete elasticity result envelope.

Returns:

PlotInventory: Available directional properties, branch metadata, principal-plane context, and three-dimensional geometries.

Parameters:

result (ResultData)

Return type:

PlotInventory

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

quantas.api.elasticity.write_table(result, destination)

Write principal-plane elasticity data as a neutral text table.

Parameters:

resultResultData: Complete elasticity result envelope.
destinationstr or Path: Destination path. The .dat suffix is applied when absent.

Returns:

Path: Written table path.

Raises:

ValueError: If result is not a valid elasticity result.

Parameters:

result (ResultData)
destination (str | Path)

Return type:

Path

Elasticity API

Minimal lifecycle

Passive contracts and selectors

Input and calculation

Reporting and plotting

Persistence

See also