quantas qha

The QHA frontend builds a volume-dependent free-energy representation and minimizes it at every requested pressure-temperature state. Its command line therefore exposes scientific choices that are absent from HA: interpolation scheme, minimization model, polynomial degrees, derivative strategy, thermal-expansion route, and local-fit failure policy.

Generating and checking the phonon input

For independent CRYSTAL phonon calculations at several volumes, place one output path per line in a text file and run

quantas qha inpgen files.txt --list --interface crystal \
   --reference 0 --output material.yaml

When printed eigenvectors are available, Quantas validates that all sources use the same q mesh, q-point weights, supercell, units, and mode count. It then tracks modes between adjacent volumes, treats numerical degeneracies as subspaces, and writes the resulting continuity status and diagnostics to the YAML.

A monolithic CRYSTAL QHA output uses the source-managed route:

quantas qha inpgen qha.out --interface crystal-qha \
   --output material.yaml

If CRYSTAL reports that frequency continuity with volume was found, Quantas records mode_continuity: verified with method: crystal-qha rather than claiming that its own multi-file tracker established the result.

Use --debug to inspect ambiguous or low-overlap assignments. Use --quiet for silent successful batch generation; --quiet and --debug are mutually exclusive.

Warning

inpgen refuses incompatible q meshes and records unresolved mode assignments instead of silently reordering a scientifically unsupported dataset. Do not edit the resulting continuity status by hand to bypass the freq-scheme preflight check.

The equations and acceptance criteria are documented in Phonon input generation and mode continuity.

Adding volume-resolved Kieffer branches

add-kieffer requires one CRYSTAL ELASTCON or ELAPIEZO output for every QHA volume. The files may be supplied as positional arguments or through --elastic-list. Select the reader with --interface crystal, following the same interface naming used by inpgen. Quantas sorts the independently calculated elastic states, matches them to the QHA volumes under the explicit matching policy, applies the CRYSTAL finite-pressure correction when necessary, and writes a separate *-kieffer.yaml input.

For raw elastic tensors, pressure can be reconstructed directly from the static volume and energy arrays already stored in the QHA input:

quantas qha add-kieffer material.yaml --elastic-list elastic-files.txt \
   --interface crystal --pressure-source energy-eos --eos BM3 \
   --output material-kieffer-eos.yaml

quantas qha add-kieffer material.yaml --elastic-list elastic-files.txt \
   --interface crystal --pressure-source energy-polynomial --degree 3 \
   --output material-kieffer-poly.yaml

Both routes evaluate \(P(V)=-dE/dV\) at the sampled phonon volumes. The generated Kieffer provenance records the exact EOS or polynomial degree, fit parameters and diagnostics, input units, evaluated pressures, warnings, and every elastic-to-phonon volume association. At least three volume-energy points are required; a selected polynomial also needs enough points for its degree, while the energy EOS may impose a stricter model-specific minimum. Use --pressure-source manual when the dataset is insufficient for a fit. The polynomial route centres and scales the sampled volume coordinate before fitting; the transform is stored with the coefficients so that conditioning and the physical \(dE/dV\) derivative remain independently inspectable.

energy-eos and energy-polynomial deliberately require raw elastic tensors. Their parsed output-stress value is not substituted into the fit. The derived pressures are attached first and the hydrostatic Wallace CRYSTAL finite-pressure correction is then applied once, with both operations retained in provenance. The hydrostatic assumption is not valid for a path carrying substantial deviatoric stress.

The directional integration defaults to a 12 by 24 coarse quadrature refined by a factor of two. --mu-order, --phi-order, and --refinement-factor are convergence controls; changes should be supported by a sensitivity test for the material under study.

add-kieffer only stores the validated data. qha run reads and applies them when --kieffer is present; omission of the flag leaves the block inactive and reproduces the ordinary phonon-only workflow. Both freq and td schemes are supported, and the sampled acoustic component remains separate in the HDF5 result even though the total properties include it.

For --scheme freq, mode-Gruneisen analysis cannot yet include the continuous acoustic branches. Quantas therefore disables its normal CLI default when --kieffer is selected and records that decision in the run options. An explicit --mode-gruneisen or --thermal-expansion mode_gruneisen request is rejected. Production scripts should state --no-mode-gruneisen as in the example above; mixed_derivative and numerical thermal expansion remain available.

Choosing options

  • --scheme=freq retains mode-resolved information but requires defensible mode continuity. --scheme=td interpolates integrated harmonic properties and is less dependent on branch tracking.

  • --minimization=poly is flexible near a well-sampled minimum; --minimization=eos imposes a selected physical EOS form.

  • --thermal-expansion chooses among mixed-derivative, mode-Gruneisen, and numerical-volume routes. Their agreement is a diagnostic, not an identity guaranteed for every dataset.

  • --poly-grid-points and --poly-grid-separation control local derivatives after polynomial minimization. They do not change the equilibrium volume itself.

  • --failure-policy determines whether failed local states terminate, accumulate, or raise immediately; it does not convert an unsupported state into a valid one.

  • plot --axis temperature selects exact native pressures with --pressure; plot --axis pressure selects exact native temperatures with --temperature. Plot construction never interpolates or snaps the requested coordinate.

See Phonon input generation and mode continuity for input-generation science, Quasi-Harmonic Approximation: implementation and workflow for the decision guide, Quasi-Harmonic Approximation for reproducible calculations and method comparisons, and HA and QHA phonon YAML for input details.

Generated command reference

quantas qha

Evaluate quasi-harmonic thermodynamics over pressure and temperature.

The group provides input generation, a static energy–volume preflight, the full QHA workflow, pressure–temperature exports, and plotting. Scientific choices such as frequency versus thermodynamic interpolation, polynomial versus EOS minimization, and the thermal-expansion route are explicit command options.

Usage

quantas qha [OPTIONS] COMMAND [ARGS]...

add-kieffer

Create a new QHA YAML input with volume-resolved Kieffer cutoffs.

FILENAME must contain primitive Gamma-only phonons. Supply one completed CRYSTAL ELASTCON or ELAPIEZO output for every QHA volume, directly or through ‘–elastic-list’. Quantas matches volumes explicitly, applies the recorded hydrostatic pre-stress treatment once, evaluates the anisotropic acoustic averages, and preserves the source input unchanged.

Usage

quantas qha add-kieffer [OPTIONS] FILENAME [ELASTIC_OUTPUTS]...

Options

--interface <interface>

Interface used to read the elastic output files. This changes the physical model or interpretation and should be compared through the relevant scientific diagnostics.

Default:

'crystal'

Options:

crystal

--elastic-list <elastic_list>

Text file listing elastic outputs, one path per line. This changes the physical model or interpretation and should be compared through the relevant scientific diagnostics.

--pressure-source <pressure_source>

Source of hydrostatic pressure for raw elastic tensors. This changes the physical model or interpretation and should be compared through the relevant scientific diagnostics.

Default:

'auto'

Options:

auto | output-stress | manual | energy-eos | energy-polynomial

--pressure <manual_pressures>

Manual pressure in GPa; repeat once per elastic output. This changes the physical model or interpretation and should be compared through the relevant scientific diagnostics.

--eos <eos>

Energy EOS used with –pressure-source energy-eos. This changes the physical model or interpretation and should be compared through the relevant scientific diagnostics.

Default:

'BM3'

Options:

M | BM | BM2 | BM3 | BM4 | PT | PT2 | PT3 | PT4 | V | V2 | V3

--degree <polynomial_degree>

E(V) polynomial degree used with energy-polynomial pressure. Treat it as a numerical-method control and check sensitivity or convergence before changing the documented default.

Default:

3

--mu-order <mu_order>

Gauss-Legendre order in cos(theta) before refinement. Treat it as a numerical-method control and check sensitivity or convergence before changing the documented default.

Default:

12

--phi-order <phi_order>

Periodic azimuthal quadrature order before refinement. Treat it as a numerical-method control and check sensitivity or convergence before changing the documented default.

Default:

24

--refinement-factor <refinement_factor>

Integer refinement applied to both directional orders. Treat it as a numerical-method control and check sensitivity or convergence before changing the documented default.

Default:

2

--batch-size <batch_size>

Maximum Christoffel directions evaluated per batch. Treat it as a numerical-method control and check sensitivity or convergence before changing the documented default.

Default:

512

-o, --output <outfile>

Output YAML file. Default: INPUT stem + ‘-kieffer.yaml’. This controls persistence or presentation and does not change the scientific model.

-f, --force

Replace existing generated files without an interactive confirmation. Use this deliberately in reproducible scripts because overwritten results cannot be recovered by Quantas.

Arguments

FILENAME

Required argument

ELASTIC_OUTPUTS

Optional argument(s)

export

Export QHA pressure–temperature tables from a native HDF5 result.

FILENAME supplies the archived grids, uncertainties, and structural path. Export a single property, the structural subset, or the complete pressure–temperature table without rerunning the calculation.

Usage

quantas qha export [OPTIONS] FILENAME

Options

-o, --output <outfile>

Output table file. Default: input file base name + ‘_table.dat’. The command reads an existing result and does not rerun the scientific workflow.

--property <property_name>

Single QHA property to export, for example VT, KT, G, or equilibrium_volume. Use ‘structure’ to export equilibrium lattice parameters and anisotropic thermal expansion only. Default: export all pressure-temperature properties.

--format <table_format>

Output table format. The command reads an existing result and does not rerun the scientific workflow.

Default:

'txt'

Options:

txt | csv

--no-uncertainty

Do not include uncertainty columns, even when available. The command reads an existing result and does not rerun the scientific workflow.

Arguments

FILENAME

Required argument

inpgen

Generate a Quantas HA/QHA YAML input from supported phonon output.

FILENAME may be one output, a CRYSTAL QHA output, or a text list of volume-dependent outputs when ‘–list’ is selected. The generated YAML preserves supplied q-point weights, normalization, and mode-continuity metadata and should be reviewed before calculation.

Usage

quantas qha inpgen [OPTIONS] FILENAME

Options

-o, --output <outfile>

Output Quantas YAML file. Default: input file base name + ‘.yaml’. Review the generated file before using it as scientific input.

--interface <interface>

Interface used to read the QM phonon output. Review the generated file before using it as scientific input.

Default:

'crystal'

Options:

crystal | crystal-qha | phonopy

--list

Treat FILENAME as a text file listing QM output files. Review the generated file before using it as scientific input.

--reference <reference>

Reference file index for multi-file input generation. Review the generated file before using it as scientific input.

Default:

0

--jobname <jobname>

Job description written to the YAML input. If omitted, it is requested interactively. Review the generated file before using it as scientific input.

-Z, --formula-units <formula_units>

Number of chemical formula units in the normalization cell. Review the generated file before using it as scientific input.

Default:

1

-q, --quiet

Do not print input-generation output on screen. Review the generated file before using it as scientific input.

--debug

Print mode-by-mode phonon continuity diagnostics. Review the generated file before using it as scientific input.

Arguments

FILENAME

Required argument

inspect

Inspect the sampled static energy–volume relation before a full QHA run.

FILENAME is fitted independently with a polynomial and an energy EOS unless either preview is disabled. The command reports the implied pressure coverage and fit quality, helping identify unsupported pressure ranges before the more expensive phonon calculation is started.

Usage

quantas qha inspect [OPTIONS] FILENAME

Options

--eos <eos>

Equation-of-state family and order used for the preview fit. This changes the physical model or interpretation and should be compared through the relevant scientific diagnostics.

Default:

'BM3'

Options:

M | BM | BM2 | BM3 | BM4 | PT | PT2 | PT3 | PT4 | V | V2 | V3

--degree <degree>

Polynomial degree used for the preview polynomial fit. Treat it as a numerical-method control and check sensitivity or convergence before changing the documented default.

Default:

3

--eunit <eunit>

Measurement unit for energy values. Input values are converted to Quantas internal canonical units before float64 calculation and persistence.

Default:

'Ha'

Options:

Ha | eV | Ry

--vunit <vunit>

Measurement unit for volume values. Input values are converted to Quantas internal canonical units before float64 calculation and persistence.

Default:

'A'

Options:

A | bohr

--punit <punit>

Measurement unit for pressure values. Input values are converted to Quantas internal canonical units before float64 calculation and persistence.

Default:

'GPa'

Options:

GPa | kbar

--no-polynomial

Do not include the polynomial pressure estimate. This controls validation, diagnostics, or failure handling and should not be used to conceal unsupported input data.

--no-eos

Do not include the EOS pressure estimate. This controls validation, diagnostics, or failure handling and should not be used to conceal unsupported input data.

-q, --quiet

Do not print output on screen. This controls persistence or presentation and does not change the scientific model.

-r, --report <report>

Write a deterministic plain-text scientific report. When omitted, run commands use the primary input name with a ‘.log’ suffix; reports contain no ANSI styling or live progress.

Arguments

FILENAME

Required argument

plot

Generate line plots or pressure–temperature maps from a QHA HDF5 result.

FILENAME is not refitted. Repeating ‘–property’ selects several products, while ‘–2d’ requests filled maps only when the stored pressure and temperature axes contain enough points. Unit and style options affect presentation only.

Usage

quantas qha plot [OPTIONS] FILENAME

Options

-p, --property <property_names>

QHA property to plot, for example VT, KT, KS, alphaV, Cp, Cv, or heat_capacities. Can be used more than once. Default: standard properties.

--axis <curve_axis>

Independent variable used for one-dimensional line sections. This affects the generated figure only and does not modify the stored scientific result.

Default:

'temperature'

Options:

temperature | pressure

--pressure <selected_pressures>

Exact native pressure included in temperature sections. May be repeated; default: all pressures. This affects the generated figure only and does not modify the stored scientific result.

--temperature <selected_temperatures>

Exact native temperature included in pressure sections. May be repeated; default: all temperatures. This affects the generated figure only and does not modify the stored scientific result.

--2d

Generate filled pressure-temperature contour maps when enough data are available. This affects the generated figure only and does not modify the stored scientific result.

--cmap <cmap>

Colormap used for two-dimensional contour maps. This affects the generated figure only and does not modify the stored scientific result.

Default:

'viridis'

Options:

viridis | plasma | inferno | magma | cividis | turbo

--contour-mode <contour_mode>

Filled contour rendering mode. This affects the generated figure only and does not modify the stored scientific result.

Default:

'smooth'

Options:

discrete | smooth

--levels <levels>

Number of contour levels or isolines. This affects the generated figure only and does not modify the stored scientific result.

Default:

12

--isolines, --no-isolines

Draw contour lines on two-dimensional maps. This affects the generated figure only and does not modify the stored scientific result.

Default:

True

--isoline-labels, --no-isoline-labels

Label contour lines with isovalues. This affects the generated figure only and does not modify the stored scientific result.

Default:

True

--temperature-unit <temperature_unit>

Display temperature unit used only for plotting. Default: HDF5 result unit. This affects the generated figure only and does not modify the stored scientific result.

Options:

K | C | Celsius | Fahrenheit | Rankine

--pressure-unit <pressure_unit>

Display pressure unit used only for plotting. Default: HDF5 result unit. This affects the generated figure only and does not modify the stored scientific result.

Options:

Pa | kPa | MPa | GPa | bar | kbar | Mbar

--energy-unit <energy_unit>

Display energy unit used only for plotting energy, entropy and heat-capacity quantities. This affects the generated figure only and does not modify the stored scientific result.

Options:

J/mol | kJ/mol | Ha | eV | Ry

--dulong-petit, --no-dulong-petit

Draw the Dulong-Petit limit on Cv and combined heat-capacity plots when atom-count metadata are available. This affects the generated figure only and does not modify the stored scientific result.

Default:

True

-o, --output <output_dir>

Output directory for plot files. Default: input file base name + ‘_plots’. This affects the generated figure only and does not modify the stored scientific result.

--preset <figure_preset>

Choose a named figure style. ‘screen’ favors interactive viewing, ‘publication’ uses print-oriented geometry and resolution, and ‘monochrome’ adds grayscale-safe rendering; the preset affects presentation only.

Default:

'screen'

Options:

screen | publication | monochrome

--format <image_format>

Choose the static figure file format supported by the Matplotlib renderer. The format changes serialization only; vector formats are preferable when downstream editing is required.

Default:

'png'

Options:

png | pdf | svg

--dpi <dpi>

Override the raster resolution supplied by the selected figure preset. This affects PNG or other raster output only and does not change sampled scientific data.

--show

Display figures interactively after files are generated. Leave this disabled on headless, batch, or continuous-integration systems.

--list-properties

List available properties and exit without generating figures. This is a discovery option: it prints the available choices and exits without calculation or file creation.

Arguments

FILENAME

Required argument

run

Run a quasi-harmonic calculation from a Quantas YAML input file.

FILENAME supplies the multi-volume static and vibrational dataset. Quantas builds the selected volume representation, minimizes the Gibbs energy at every pressure-temperature state, reconstructs thermodynamic and structural properties, records fit diagnostics and fallback provenance, and writes a native HDF5 archive. ‘–kieffer’ activates the separately stored acoustic cutoff series throughout the sampled and equilibrium-volume calculations.

Usage

quantas qha run [OPTIONS] FILENAME

Options

-S, --scheme <scheme>

QHA interpolation scheme. This changes the physical model or interpretation and should be compared through the relevant scientific diagnostics.

Default:

'freq'

Options:

freq | td

--mode-continuity <mode_continuity>

Override the phonon-mode continuity status stored in the input file. This changes the physical model or interpretation and should be compared through the relevant scientific diagnostics.

Options:

verified | assumed | unknown | unreliable

--kieffer

Read and activate the volume-resolved Kieffer cutoff series embedded in FILENAME. Frequency QHA disables the default mode-Gruneisen output because the continuous acoustic branches are not yet weighted there; an explicit ‘–mode-gruneisen’ request remains an error.

-N, --minimization <minimization>

Volume minimization method. This changes the physical model or interpretation and should be compared through the relevant scientific diagnostics.

Default:

'poly'

Options:

poly | eos

-E, --eos <eos>

Equation-of-state family and order used for EOS minimization. This changes the physical model or interpretation and should be compared through the relevant scientific diagnostics.

Default:

'BM3'

Options:

M | BM | BM2 | BM3 | BM4 | PT | PT2 | PT3 | PT4 | V | V2 | V3

--gruneisen, --no-gruneisen

Calculate the thermodynamic Gruneisen parameter. This changes the physical model or interpretation and should be compared through the relevant scientific diagnostics.

Default:

True

--mode-gruneisen, --no-mode-gruneisen

Calculate mode-resolved Gruneisen parameters for the frequency scheme. This changes the physical model or interpretation and should be compared through the relevant scientific diagnostics.

Default:

True

--thermal-expansion <thermal_expansion_method>

Method used to calculate volumetric thermal expansion. mode_gruneisen is available only with –scheme=freq. This changes the physical model or interpretation and should be compared through the relevant scientific diagnostics.

Default:

'mixed_derivative'

Options:

mixed_derivative | mode_gruneisen | numerical

-T, --temperature <MIN MAX STEP>

Temperature range. Changing it changes the states, data, or directions evaluated and may therefore affect runtime and the stored result.

Default:

'298.15 298.15 1.0'

-P, --pressure <MIN MAX STEP>

Pressure range. Changing it changes the states, data, or directions evaluated and may therefore affect runtime and the stored result.

Default:

'0.0 0.0 1.0'

-D, --energy-degree <energy_degree>

Polynomial degree for static energy, free energy, and thermodynamic-property fits. Treat it as a numerical-method control and check sensitivity or convergence before changing the documented default.

Default:

3

-F, --frequency-degree <frequency_degree>

Polynomial degree for mode-resolved frequency fits. Treat it as a numerical-method control and check sensitivity or convergence before changing the documented default.

Default:

3

--poly-derivatives <polynomial_derivative_method>

Method used to calculate KT and Kp after polynomial minimization. Treat it as a numerical-method control and check sensitivity or convergence before changing the documented default.

Default:

'local_grid'

Options:

local_grid | analytic

--poly-grid-points <polynomial_grid_points>

Odd number of volumes in the local polynomial derivative grid. Treat it as a numerical-method control and check sensitivity or convergence before changing the documented default.

Default:

5

--poly-grid-separation <polynomial_grid_separation>

Adjacent local-grid spacing as a percentage of equilibrium volume. Treat it as a numerical-method control and check sensitivity or convergence before changing the documented default.

Default:

0.05

--gruneisen-min-cv-fraction <gruneisen_min_cv_fraction>

Minimum Cv/Dulong-Petit fraction for the macroscopic Gruneisen ratio. This controls validation, diagnostics, or failure handling and should not be used to conceal unsupported input data.

Default:

0.01

--max-failures <max_failures>

Maximum number of consecutive failed fits before stopping. This controls validation, diagnostics, or failure handling and should not be used to conceal unsupported input data.

Default:

5

--failure-policy <failure_policy>

Policy applied when local fits fail. This controls validation, diagnostics, or failure handling and should not be used to conceal unsupported input data.

Default:

'stop'

Options:

continue | stop | raise

--eunit <eunit>

Energy unit. Input values are converted to Quantas internal canonical units before float64 calculation and persistence.

Default:

'Ha'

--vunit <vunit>

Volume unit. Input values are converted to Quantas internal canonical units before float64 calculation and persistence.

Default:

'A'

--funit <funit>

Frequency unit. Input values are converted to Quantas internal canonical units before float64 calculation and persistence.

Default:

'cm^-1'

--tunit <tunit>

Temperature unit. Input values are converted to Quantas internal canonical units before float64 calculation and persistence.

Default:

'K'

--punit <punit>

Pressure unit. Input values are converted to Quantas internal canonical units before float64 calculation and persistence.

Default:

'GPa'

-o, --output <output>

Output HDF5 file. Default: input file base name + ‘_QHA.hdf5’. This controls persistence or presentation and does not change the scientific model.

-f, --force

Replace existing generated files without an interactive confirmation. Use this deliberately in reproducible scripts because overwritten results cannot be recovered by Quantas.

-r, --report <report>

Write a deterministic plain-text scientific report. When omitted, run commands use the primary input name with a ‘.log’ suffix; reports contain no ANSI styling or live progress.

-v, --verbosity <verbosity>

Select report detail: ‘standard’ gives the normal scientific summary, ‘extended’ adds complete tables, and ‘debug’ adds numerical diagnostics. The choice never changes stored numerical results.

Default:

'standard'

Options:

standard | extended | debug

-q, --quiet

Suppress terminal presentation while preserving calculation, HDF5 output, and the report. This is useful for scripts, redirected jobs, and automated validation.

--progress, --no-progress

Enable or disable transient Rich progress on an interactive terminal. Progress events are operational only and are never written to reports or HDF5 histories.

Default:

True

Arguments

FILENAME

Required argument