PAOFLOW.inputs.lattice_format#

Reconstruct Bravais lattice vectors from Quantum ESPRESSO ibrav.

This module implements the lattice-vector conventions of Quantum ESPRESSO’s PW/src/latgen.f90 (documented in INPUT_PW). Given a QE ibrav index and the six celldm parameters it returns the three primitive lattice vectors (as the rows of a (3, 3) array) in Bohr — the same layout and units used elsewhere in PAOFLOW (PAOFLOW.inputs.file_io.struct_from_outputfile_QE()).

The per-ibrav vector definitions are kept in a registry (_IBRAV_BUILDERS) so the canonical forms can be reused by a future inverse map (explicit lattice / AFLOW ibrav=0 → canonical QE ibrav + celldm).

celldm convention#

Following QE, celldm is a length-6 array:

celldm[0] — a (the lattice parameter) in Bohr.
celldm[1] — b/a.
celldm[2] — c/a.
celldm[3] — first cosine (meaning depends on ibrav).
celldm[4] — second cosine (meaning depends on ibrav).
celldm[5] — third cosine (meaning depends on ibrav).

Public API#

lattice_format_QE() — (ibrav, celldm) → lattice vectors (Bohr).
celldm_from_namelist() — assemble celldm from a parsed QE &system block, accepting either the celldm(i) convention or the A/B/C/cosAB/cosAC/cosBC convention.

Functions#

`lattice_format_QE`(ibrav, celldm)	Return the primitive lattice vectors for a QE `ibrav`.
`celldm_from_namelist`(system_block, ibrav)	Assemble a length-6 `celldm` array from a parsed QE `&system` block.
`cell_lengths_angles`(lattice)	Return `(a, b, c, alpha, beta, gamma)` for a set of cell vectors.
`bravais_to_ibrav`(symbol[, spacegroup])	Map an AFLOW Bravais-lattice symbol to a candidate QE `ibrav`.
`qe_ibrav_from_lattice`(lattice[, bravais_hint, ...])	Classify an explicit lattice as a QE `ibrav` + `celldm`.

Module Contents#

PAOFLOW.inputs.lattice_format.lattice_format_QE(ibrav, celldm)[source]#

Return the primitive lattice vectors for a QE ibrav.

Parameters:

ibrav (int) – Quantum ESPRESSO Bravais-lattice index. All non-zero QE values are supported: 1, 2, 3, -3, 4, 5, -5, 6, 7, 8, 9, -9, 91, 10, 11, 12, -12, 13, -13, 14.
celldm (array_like) – Length-6 array of QE celldm parameters. celldm[0] is the lattice parameter a in Bohr; celldm[1] = b/a, celldm[2] = c/a and celldm[3:6] are the cosines whose meaning depends on ibrav (see module docstring).

Returns:

(3, 3) array whose rows are the primitive lattice vectors in Bohr.

Return type:

numpy.ndarray

Raises:

ValueError – If ibrav is 0 (explicit CELL_PARAMETERS required) or not a recognised QE Bravais-lattice index.

PAOFLOW.inputs.lattice_format.celldm_from_namelist(system_block, ibrav)[source]#

Assemble a length-6 celldm array from a parsed QE &system block.

Accepts either of the two mutually exclusive QE conventions:

celldm(1)..``celldm(6)`` directly; or
A, B, C (Ångström) with cosAB, cosAC, cosBC.

The cosine slots are filled following QE’s cell_base mapping, which depends on ibrav:

ibrav = 14: celldm[3]=cosBC, celldm[4]=cosAC, celldm[5]=cosAB.
ibrav in {-12, -13} (unique axis b): celldm[4]=cosAC.
all other ibrav needing one cosine: celldm[3]=cosAB.

Parameters:

system_block (dict) – Mapping of lower-case &system keywords to their raw string values, as produced by PAOFLOW.inputs.file_io.struct_from_inputfile_QE().
ibrav (int) – QE Bravais-lattice index (controls the cosine mapping above).

Returns:

Length-6 celldm array with celldm[0] in Bohr.

Return type:

numpy.ndarray

Raises:

ValueError – If neither celldm(1) nor A is present in the block.

PAOFLOW.inputs.lattice_format.cell_lengths_angles(lattice)[source]#

Return (a, b, c, alpha, beta, gamma) for a set of cell vectors.

Parameters:: lattice (array_like) – (3, 3) array whose rows are the cell vectors (any length unit).
Returns:: Lengths a, b, c (same unit as lattice) and angles alpha, beta, gamma in degrees. alpha is the angle between vectors 2 and 3, beta between 1 and 3, gamma between 1 and 2.
Return type:: tuple

PAOFLOW.inputs.lattice_format.bravais_to_ibrav(symbol, spacegroup=None)[source]#

Map an AFLOW Bravais-lattice symbol to a candidate QE ibrav.

Parameters:

symbol (str) – AFLOW Bravais-lattice symbol (e.g. 'FCC', 'BCC', 'HEX', 'ORCC') or Pearson-style two-letter code (e.g. 'cF').
spacegroup (int, optional) – Space-group number. Currently unused for the base mapping but accepted so callers can pass it through; variant/sign disambiguation is done geometrically.

Returns:

The candidate ibrav (the magnitude/base variant), or None if the symbol is not recognised.

Return type:

int or None

PAOFLOW.inputs.lattice_format.qe_ibrav_from_lattice(lattice, bravais_hint=None, spacegroup=None, symprec=0.0001)[source]#

Classify an explicit lattice as a QE ibrav + celldm.

Parameters:

lattice (array_like) – (3, 3) primitive cell, rows are the lattice vectors in Bohr.
bravais_hint (str, optional) – AFLOW Bravais-lattice symbol (e.g. 'FCC'); when given it narrows the candidate ibrav and makes classification robust. When omitted, every supported ibrav is tried in order of decreasing symmetry.
spacegroup (int, optional) – Space-group number (passed through to bravais_to_ibrav()).
symprec (float, optional) – Absolute tolerance (Bohr) for length comparisons; the angular tolerance is derived from it. Defaults to 1e-4.

Returns:

{'ibrav': int, 'celldm': ndarray, 'M': ndarray} on success, where M is the integer unimodular matrix mapping the input basis to the QE primitive basis (so fractional coordinates transform as f_qe = f_in @ inv(M)). On failure returns {'ibrav': 0, 'celldm': None, 'M': None} and the caller should keep the explicit CELL_PARAMETERS description.

Return type:

dict