Your first calculation

This page runs one small calculation twice: first from the command line and then through the public Python API. Both paths use the same calcite stiffness tensor and must reproduce the same scientific result.

The example is intentionally short. Its purpose is to show the complete Quantas pattern:

input file
→ validated scientific calculation
→ typed result
→ deterministic report
→ native HDF5 file

The detailed interpretation of the elastic properties is developed in the Elasticity analysis tutorial.

Prepare a working directory

Create an empty directory and place the example input inside it:

mkdir quantas-first-calculation
cd quantas-first-calculation

Download calcite.dat

The file contains a title, the upper-triangular part of a stiffness matrix in Voigt notation, and an optional density. Elastic constants are expressed in GPa. The Elasticity reader validates the matrix and expands it to a symmetric \(6\times6\) tensor before the calculation starts.

Run the command-line calculation

Execute:

quantas elasticity run calcite.dat \
    --output calcite_elasticity.hdf5 \
    --report calcite_elasticity.log \
    --no-progress \
    --force

The command performs four main operations:

1. it reads and validates the input;

2. it calculates the compliance tensor, Voigt–Reuss–Hill averages, mechanical stability, and global directional extrema;

3. it writes a deterministic plain-text report;

4. it stores the complete result in native HDF5 format.

--no-progress only disables the transient terminal progress display. It does not change the calculation. --force permits the two requested files to be replaced when the example is repeated.

Check the terminal or report output

The report should contain the following checkpoints to the displayed precision:

Crystal system: trigonal_low
Mechanically stable: True
Hill bulk modulus / GPa: 83.099307
Hill shear modulus / GPa: 35.241563
Young minimum / GPa: 57.603207
Young maximum / GPa: 154.060777

The Hill values describe an equivalent isotropic polycrystalline aggregate. The Young-modulus extrema describe the directional response of the single crystal. They answer different physical questions and should not be compared as if they were the same type of average.

Two files should now be present:

calcite_elasticity.log

Human-readable plain text. It is useful for inspection, archiving, and attaching a stable record to a calculation.

calcite_elasticity.hdf5

Native structured result. It retains numerical arrays at full precision, metadata, normalized inputs and options, warnings, and the scientific payload needed by later plotting or export commands.

Repeat the calculation through Python

The equivalent public-API program is available here:

Download first_elasticity_api.py

Place the script beside calcite.dat and run:

python first_elasticity_api.py

The essential code is:

"""Run the first Quantas elasticity calculation through the public API."""

from __future__ import annotations

from pathlib import Path

from quantas.api import elasticity, rendering


INPUT = Path("calcite.dat")
RESULT = Path("calcite_elasticity_api.hdf5")
REPORT = Path("calcite_elasticity_api.log")


def main() -> None:
    """Calculate, report, and persist the calcite elasticity example."""
    result = elasticity.run(INPUT)
    payload = elasticity.get_result(result)

    report_text = rendering.render_tables(elasticity.build_report(result))
    REPORT.write_text(report_text, encoding="utf-8")
    elasticity.write_result(result, RESULT, report_text=report_text)

    young = payload.variations["young_modulus"]
    print(f"Crystal system: {payload.crystal_system}")
    print(f"Mechanically stable: {payload.stability.is_stable}")
    print(f"Hill bulk modulus / GPa: {payload.averages.hill.bulk_modulus:.6f}")
    print(f"Hill shear modulus / GPa: {payload.averages.hill.shear_modulus:.6f}")
    print(f"Young minimum / GPa: {young.minimum:.6f}")
    print(f"Young maximum / GPa: {young.maximum:.6f}")


if __name__ == "__main__":
    main()

The script uses only supported public namespaces:

from quantas.api import elasticity, rendering

elasticity.run returns a complete quantas.api.common.ResultData envelope. elasticity.get_result extracts and validates the typed Elasticity payload. The report builder returns frontend-neutral tables, and quantas.api.rendering.render_tables() converts those tables to deterministic plain text. The scientific calculation never depends on terminal or plotting objects.

Compare the two frontends

The API script creates:

calcite_elasticity_api.hdf5
calcite_elasticity_api.log

The displayed checkpoints must agree with the command-line calculation. A strict numerical comparison can be made directly from the two HDF5 files:

import numpy as np
from quantas.api import elasticity

cli = elasticity.get_result(
    elasticity.read_result("calcite_elasticity.hdf5")
)
api = elasticity.get_result(
    elasticity.read_result("calcite_elasticity_api.hdf5")
)

np.testing.assert_allclose(cli.stiffness, api.stiffness)
np.testing.assert_allclose(cli.compliance, api.compliance)
assert cli.averages == api.averages
assert cli.stability.is_stable == api.stability.is_stable

This equality is a central Quantas design rule: changing the frontend must not change the scientific result.

Where to continue

• Read Python API to understand result envelopes, typed payloads, observers, and module discovery.

• Read Command-line interface for command organization, common options, progress, reports, and exit behavior.

• Read Results, reports, and plots for the roles of HDF5, reports, exports, and plots.

• Continue with Tutorials for complete scientific examples.