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.

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.

See 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]...

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

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.

--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.

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

-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