API overview

The supported Python contract begins at quantas.api. Applications, notebooks, services, the command-line interface, and future graphical frontends should import from these namespaces rather than from implementation packages. Those packages may change as the code evolves and are not application contracts.

The API is organized by scientific domain rather than as one flat collection of functions:

from quantas.api import (
    common,
    elasticity,
    eos,
    ha,
    interop,
    profiles,
    qha,
    registry,
    rendering,
    seismic,
    thermoelasticity,
)

Only names exported through the __all__ attribute of these modules are part of the supported public surface. A class may be implemented internally in another package, but users should import and reference it through its quantas.api alias.

The reference pages use explicit autodoc directives for those aliases rather than expanding every imported module member. Automated tests require every exported name to be documented exactly once and reject undocumented or accidentally promoted symbols.

API lifecycle patterns

Most scientific modules follow a single-shot lifecycle:

input or path
-> normalize_input
-> run
-> ResultData
-> typed module payload
-> report / plots / export / HDF5

HA, QHA, Elasticity, SEISMIC, and Thermoelasticity expose passive Input, Options, and Result contracts around this pattern. EOS is deliberately different: one dataset can produce many immutable fit records, so its public surface is organized around fit requests, batch plans, archives, sessions, diagnostics, and post-fit calculations.

Result envelopes and typed payloads

Single-shot workflows return quantas.api.common.ResultData. The envelope contains common metadata, normalized input, resolved options, warnings, persistent events, and one module-specific payload. The module-specific get_result function validates the envelope before returning the typed payload:

from quantas.api import qha

result_data = qha.run("phonons.yaml", options=qha.Options())
result = qha.get_result(result_data)
print(result.equilibrium_volume.shape)

Do not extract a payload by assuming a string key when a typed accessor is available.

Frontend-neutral reporting and plotting

Calculations build quantas.api.common.ReportTable and quantas.api.common.PlotCollection objects. Concrete plain-text and Matplotlib output is produced separately by quantas.api.rendering. This keeps numerical workflows independent from terminals, notebooks, web applications, and graphical interfaces.

Observers and progress

Long-running public operations accept an quantas.api.common.Observer. Events contain messages, levels, structured data, and optional normalized progress. The calculator does not create a Rich progress bar or GUI widget; the frontend decides how events are presented.

Runtime dependencies and optional features

Importing quantas remains lightweight. The base scientific runtime includes odrpack for orthogonal-distance EOS regression and spglib for crystallographic symmetry and structure-normalization operations. These packages are required dependencies even though their functionality is imported only when the corresponding workflow is used.

Static plotting remains optional and requires the plot extra. A missing required runtime backend indicates an incomplete or broken installation rather than an intentionally unavailable Quantas capability.

Public namespaces

Namespace	Purpose	Continue with
`quantas.api.common`	Shared envelopes, neutral report/plot contracts, and events.	Common public contracts
`quantas.api.ha`	Harmonic thermodynamic calculations.	Harmonic Approximation API
`quantas.api.qha`	Quasi-harmonic inspection, calculation, validation, and comparison.	Quasi-Harmonic Approximation API
`quantas.api.elasticity`	Second-order elastic analysis and directional surfaces.	Elasticity API
`quantas.api.seismic`	Christoffel phase/group analysis, polarization, and enhancement.	SEISMIC API
`quantas.api.eos`	EOS datasets, fitting, archives, diagnostics, and calculations.	EOS API
`quantas.api.thermoelasticity`	QSA calibration, P–T reconstruction, and geological profiles.	Thermoelasticity API
`quantas.api.profiles`	Frontend-neutral terrestrial profile specifications.	Terrestrial profile API
`quantas.api.rendering`	Supported rendering bridge for neutral tables and plots.	Rendering API
`quantas.api.registry`	Capability-based discovery for frontends and services.	Capability registry API
`quantas.api.interop`	Explicit transformations between scientific workflows.	Interoperability API