PAOFLOW.phonon.structure#

Structure bridge between PAOFLOW and phonopy/phono3py.

PAOFLOW stores the crystal structure (parsed from the DFT output) in the DataController using the following conventions:

alat Lattice parameter in Bohr (atomic units). a_vectors (3, 3) array; rows are the direct lattice vectors expressed

in units of alat (so the Cartesian lattice in Bohr is a_vectors * alat).

tau (natoms, 3) array of Cartesian atomic positions in Bohr. atoms length-natoms list of atom labels (e.g. 'Si', 'Fe1'). species list of (label, pseudo_file) tuples. omega cell volume in Bohr^3.

When phonopy is driven through its Quantum ESPRESSO interface (Phonopy(..., calculator='qe')) the lattice and positions are expressed in Bohr (the QE-native length unit), forces in Ry/Bohr, and the frequency conversion factor is set accordingly. PAOFLOW already stores the structure in Bohr, so the bridge keeps everything in Bohr: lattice row-wise in Bohr and atomic positions as fractional (scaled) coordinates. This module performs the bidirectional conversion and provides a round-trip verification helper.

Functions#

paoflow_to_phonopy(data_controller[, scale])

Build a phonopy.structure.atoms.PhonopyAtoms from PAOFLOW data.

phonopy_to_paoflow(cell[, alat])

Convert a PhonopyAtoms back to PAOFLOW structural quantities.

verify_round_trip(data_controller[, rtol, atol])

Check that PAOFLOW -> PhonopyAtoms -> PAOFLOW preserves the structure.

primitive_atom_info(data_controller)

Return the phonopy primitive-cell atom ordering for Born-charge I/O.

Module Contents#

PAOFLOW.phonon.structure.paoflow_to_phonopy(data_controller, scale=1.0)[source]#

Build a phonopy.structure.atoms.PhonopyAtoms from PAOFLOW data.

Parameters:

  • data_controller (DataController) – Provides the structural arrays/attributes described in the module docstring.

  • scale (float, optional) – Isotropic linear scale factor applied to the lattice vectors (the cell volume scales as scale**3). The fractional atomic positions are preserved, so atoms move with the cell. Used by the quasi-harmonic volume scan; defaults to 1.0 (no scaling).

Returns:

Primitive/unit cell in the phonopy QE convention (Bohr lattice, scaled positions, chemical symbols and default isotopic masses).

Return type:

phonopy.structure.atoms.PhonopyAtoms

PAOFLOW.phonon.structure.phonopy_to_paoflow(cell, alat=None)[source]#

Convert a PhonopyAtoms back to PAOFLOW structural quantities.

Parameters:

  • cell (phonopy.structure.atoms.PhonopyAtoms) – Cell to convert (Bohr lattice, scaled positions; QE convention).

  • alat (float, optional) – Lattice parameter in Bohr to use as the alat reference. When not supplied the norm of the first lattice vector (in Bohr) is used, which matches QE’s default alat convention for many Bravais lattices.

Returns:

Mapping with keys alat, a_vectors, tau, atoms, omega expressed in PAOFLOW conventions (Bohr / units of alat).

Return type:

dict

PAOFLOW.phonon.structure.verify_round_trip(data_controller, rtol=1e-08, atol=1e-08)[source]#

Check that PAOFLOW -> PhonopyAtoms -> PAOFLOW preserves the structure.

Compares the Cartesian lattice (Bohr), Cartesian atomic positions (Bohr) and chemical symbols/masses before and after the conversion.

Parameters:
Returns:

Diagnostics with the maximum lattice/position deviations (in Bohr), the symbol/mass match flags and an overall ok boolean.

Return type:

dict

PAOFLOW.phonon.structure.primitive_atom_info(data_controller)[source]#

Return the phonopy primitive-cell atom ordering for Born-charge I/O.

Born effective charges are a property of the primitive cell, so a phonopy BORN file lists one tensor per primitive atom in the phonopy primitive order (which may differ from the PAOFLOW tau order). This helper exposes that ordering and the per-atom masses/positions.

Returns:

symbols (list), masses (ndarray), scaled_positions (natom_prim, 3), cell (Bohr lattice rows) and natom.

Return type:

dict