quantas ha

The HA frontend evaluates vibrational thermodynamics independently at every sampled volume. It does not minimize the free energy with respect to volume and does not create a pressure axis.

Generating the phonon input

The shared inpgen command supports three interface routes:

quantas ha inpgen phonon.out --interface crystal --output material.yaml

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

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

--reference selects the source structure used for reference metadata and final branch labels in a multi-file series. It does not change the local adjacent-volume overlap assignments performed by the mode tracker.

--formula-units records the number of chemical formula units represented by the normalization cell. This value participates in later molar conversions and should not be chosen from the phonon supercell size alone.

--debug prints mode-by-mode continuity diagnostics for multi-volume inputs: raw source modes, frequencies, selected and competing overlaps, overlap gap, degenerate-subspace singular value, leave-one-out diagnostics for weak overlaps, and global frequency-path fit diagnostics. --quiet suppresses normal successful output. The two options are mutually exclusive.

Adding Kieffer acoustic branches

add-kieffer is available only for primitive Gamma-only phonons calculated with the identity supercell. It reads one elastic output at the same volume, selected with --interface crystal, and writes a new input whose calculated Gamma frequencies are unchanged. The three Kieffer branches are stored as a separate additive component.

Use --pressure-source auto for the usual case. A raw CRYSTAL tensor is corrected from its unstrained-stress pressure with the finite-pressure transformation of Erba et al. (2014); a tensor produced with CRYSTAL’s PRESSURE keyword is recognized as already corrected. Use --pressure-source manual --pressure VALUE only when no usable output-stress pressure is available.

The energy-eos and energy-polynomial pressure sources require a multi-volume energy path and are therefore available only through quantas qha add-kieffer. A single HA state must use output-stress, applied pre-stress, or an explicitly supplied pressure.

The stored block is deliberately opt-in. Run the enriched file with --kieffer to add the acoustic contribution. Running the same file without the flag performs the ordinary Gamma-phonon calculation, which provides a controlled comparison without editing either input. The report identifies activation and includes the Kieffer reference; the native HDF5 archive retains the acoustic component separately from the totals.

Note

HA itself does not require phonon branch continuity across volume. The shared generator nevertheless records continuity when it can, so the same YAML can later be used safely by QHA. See Phonon input generation and mode continuity for the scientific procedure.

Important distinctions

  • --temperature controls the calculated grid and stored arrays.

  • unit options on run describe the YAML values; unit options on plot or export convert an existing result for presentation.

  • plotting during run is a convenience. The standalone plot command is preferable when several figure variants are required.

  • plot --axis temperature produces one curve per selected sampled volume; plot --axis volume produces one curve per selected stored temperature. --volume and --temperature accept only exact native-grid values.

  • plot --2d adds a V–T map when both coordinate axes contain at least two points. It does not interpolate the result grid.

  • q-point weights are taken from the input and normalized; the CLI does not derive missing symmetry multiplicities.

See Phonon input generation and mode continuity for input-generation science, Harmonic Approximation: implementation and workflow for HA implementation choices, Harmonic Approximation for a complete MgO calculation, and HA and QHA phonon YAML for the input contract.

Generated command reference

quantas ha

Evaluate harmonic vibrational thermodynamics on one or more fixed volumes.

The group converts supported phonon outputs to the Quantas YAML contract, runs temperature-dependent harmonic sums, exports numerical properties, and renders figures from native HDF5 results. HA does not minimize volume or introduce a pressure coordinate.

Usage

quantas ha [OPTIONS] COMMAND [ARGS]...

add-kieffer

Create a new HA YAML input with Kieffer sine-wave acoustic cutoffs.

FILENAME must be a primitive, single-volume Gamma-only phonon input. Supply one completed CRYSTAL ELASTCON or ELAPIEZO output either as a positional argument or through ‘–elastic-list’. Quantas derives the three acoustic cutoff frequencies from the incremental elastic tensor and writes a separate YAML file without replacing any calculated mode.

Usage

quantas ha 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 one harmonic property from a Quantas HA HDF5 result.

FILENAME is read without rerunning HA. Select the stored property and an optional display unit; ‘–ask-unit’ is intended for interactive terminal use, whereas an explicit ‘–unit’ is preferable in scripts.

Usage

quantas ha export [OPTIONS] FILENAME

Options

-o, --output <outfile>

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

--property <property_name>

HA property to export, for example F, Cv, S, Utot, or free_energy. The command reads an existing result and does not rerun the scientific workflow.

Default:

'F'

--unit <unit>

Output unit for energy-like data, for example Ha, eV, Ry, or kJ/mol. Input values are converted to Quantas internal canonical units before float64 calculation and persistence.

--ask-unit

Prompt for the output unit during export. Input values are converted to Quantas internal canonical units before float64 calculation and persistence.

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

plot

Generate static figures from a Quantas HA HDF5 result.

FILENAME provides the stored temperature and volume grids. Property and unit choices affect only the rendered representation; the numerical HDF5 arrays are never rounded or rewritten.

Usage

quantas ha plot [OPTIONS] FILENAME

Options

-o, --output <outbase>

Output figure basename. Default: input file without extension. This affects the generated figure only and does not modify the stored scientific result.

--property <property_name>

HA property to plot, for example F, Cv, S, Utot, or all. Default: standard compact set. This affects the generated figure only and does not modify the stored scientific result.

--axis <curve_axis>

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

Default:

'temperature'

Options:

temperature | volume

--volume <selected_volumes>

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

--temperature <selected_temperatures>

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

--2d

Generate native-grid volume-temperature contour maps when possible. 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 volume-temperature 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

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

--unit <unit>

Energy unit used for plotted energy-like values. Defaults to stored HDF5 units. This affects the generated figure only and does not modify the stored scientific result.

Arguments

FILENAME

Required argument

run

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

FILENAME supplies static energies, volumes, phonon frequencies, q-point weights, and normalization metadata. The command evaluates every requested temperature at every stored volume, writes a native HDF5 result and deterministic report, and can optionally render a compact plot set. ‘–kieffer’ additionally reads the validated acoustic cutoff block embedded by ‘add-kieffer’.

Usage

quantas ha run [OPTIONS] FILENAME

Options

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

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

--funit <funit>

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

Default:

'cm^-1'

Options:

cm-1 | cm^-1 | THz | Hz

--tunit <tunit>

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

Default:

'K'

Options:

K | C

-B, --benchmark

Render backend timing events in addition to the scientific report. Benchmarking is diagnostic only and does not change harmonic sums, stored arrays, or numerical precision.

--kieffer

Read and activate the validated Kieffer cutoff state embedded in FILENAME. The three sine-wave acoustic branches are added to the Gamma phonons and retained separately; omitting the flag leaves the block inactive.

-p, --plot

Create static Matplotlib plots after the calculation. This affects the generated figure only and does not modify the stored scientific result.

--plot-property <plot_property>

HA property to plot after the run, for example F, Cv, S, Utot, or all. Default: standard compact set. This affects the generated figure only and does not modify the stored scientific result.

--plot-unit <plot_unit>

Energy unit used for plotted energy-like values. Defaults to stored result units. This affects the generated figure only and does not modify the stored scientific result.

--plot-preset <plot_preset>

Standard figure styling. Screen favors interactive output; publication uses print-ready geometry and resolution; monochrome adds grayscale-safe rendering.

Default:

'screen'

Options:

screen | publication | monochrome

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

-o, --output <output>

Output HDF5 file. Default: input file base name + ‘_HA.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