Lattice dynamics

Elastic constants

elastic_constants

elastic_constants(system, calculator, *, strain=0.001, relax=True, max_force=0.0001, max_steps=5000, symmetry=None)

Elastic constants from the stress under small strains.

Parameters:

Name	Type	Description	Default
system	System	The crystal, periodic in every direction, or a sheet: periodic along two vectors in the x-y plane and not along a third along z. Best at zero stress (relax its box first with minimize(..., cell="full")).	required
calculator	Calculator	Computes the virial, and energies and forces to relax the positions.	required
strain	float64	Magnitude of the strains applied in each direction, positive and negative; shear strains are engineering strains. Default 1e-3.	0.001
relax	bool	Relax the positions under each strain. Default True.	True
max_force	float64	Convergence of each relaxation in eV/Å. Default 1e-4.	0.0001
max_steps	int32	Largest number of steps of each relaxation. Default 5000.	5000
symmetry	bool	Take the stress under a strain that a symmetry operation of the crystal, found by spglib, makes from another one as the image of its stress: True, False, or by default whenever spglib is installed.	None

Returns:

Type	Description
ElasticResult or SheetElasticResult	The (6, 6) elastic constants in GPa; of a sheet, the (3, 3) elastic constants in N/m.

Raises:

Type	Description
InvalidParameter	If the box is neither periodic nor that of a sheet, the strain is not positive, the calculator has no virial, a relaxation does not converge, or symmetry is True without spglib.

ElasticResult dataclass

ElasticResult(constants, errors=None)

Bases: Result

Elastic constants of a crystal.

Attributes:

Name	Type	Description
constants	ndarray	(6, 6) float64 elastic constants in GPa, in Voigt order xx, yy, zz, yz, xz, xy; column k is the stress per unit of strain component k.
errors	ndarray or None	(6, 6) float64 standard errors of the constants in GPa, from molecular dynamics; None otherwise.

bulk_modulus

bulk_modulus(average='hill')

The bulk modulus in GPa: the "voigt", "reuss" or "hill" average.

shear_modulus

shear_modulus(average='hill')

The shear modulus in GPa: the "voigt", "reuss" or "hill" average.

SheetElasticResult dataclass

SheetElasticResult(constants)

Bases: Result

Elastic constants of a sheet, per unit of its area.

Attributes:

Name	Type	Description
constants	ndarray	(3, 3) float64 elastic constants in N/m, in the order xx, yy, xy; column k is the tension per unit of strain component k.

young_modulus

young_modulus(axis='x')

The Young's modulus in N/m along "x" or "y".

poisson_ratio

poisson_ratio(axis='x')

The contraction across a stretch along "x" or "y", over the stretch.

shear_modulus

shear_modulus()

The shear modulus in N/m.

area_modulus

area_modulus()

The area modulus in N/m: the tension per unit of relative change of the area.

thermal_elastic_constants

thermal_elastic_constants(qha, calculator, *, method='quasi-harmonic', strain=0.005, supercell=None, mesh=20, displacement=0.01, max_force=1e-06, max_steps=5000, symmetry=None)

Isothermal and adiabatic elastic constants of a crystal at the temperatures of a quasi-harmonic calculation.

Parameters:

Name	Type	Description	Default
qha	QuasiHarmonicResult	The quasi-harmonic calculation of the crystal, with its cells; the cells around the volumes of its temperatures are strained.	required
calculator	Calculator	Computes energies and forces, as in the quasi-harmonic calculation.	required
method	(quasi - harmonic, quasi - static)	Second derivatives with respect to strain of the static energy and the free energy of the vibrations, from phonons of strained cells, or of the static energy alone, at the volume of each temperature. Default "quasi-harmonic".	"quasi-harmonic"
strain	float64	Magnitude of the Lagrangian strains of the finite differences. Default 5e-3.	0.005
supercell	optional	Of the phonons of the strained cells, as in phonons and Phonons.thermal.	None
mesh	optional	Of the phonons of the strained cells, as in phonons and Phonons.thermal.	None
displacement	optional	Of the phonons of the strained cells, as in phonons and Phonons.thermal.	None
max_force	float64	Convergence of the relaxation of the positions in each strained cell in eV/Å. Default 1e-6.	1e-06
max_steps	int32	Largest number of steps of each relaxation. Default 5000.	5000
symmetry	bool	Compute one of each set of strains that the symmetry operations of the cells, found by spglib, make from each other, and use symmetry in the phonons too: True, False, or by default whenever spglib is installed.	None

Returns:

Type	Description
ThermalElasticResult	The isothermal and adiabatic elastic constants at each temperature.

Raises:

Type	Description
InvalidParameter	For an unknown method, a strain that is not positive, a result without cells, a relaxation that does not converge, imaginary frequencies in a strained cell, or symmetry True without spglib.

md_elastic_constants

md_elastic_constants(system, potential, temperature, *, pressure=0.0, strain=0.01, timestep=0.001, equilibration=10000, production=20000, every=10, blocks=5, barostat='tri', seed=1)

Isothermal elastic constants of a crystal at a temperature, from the mean stress of molecular dynamics in LAMMPS under small strains.

Parameters:

Name	Type	Description	Default
system	System	The crystal, periodic in every direction, with an element column.	required
potential	LAMMPS	The interaction, as a LAMMPS calculator.	required
temperature	float64	Temperature in K, positive.	required
pressure	float64	Pressure in GPa. Default 0.	0.0
strain	float64	Magnitude of the strains, positive and negative; shears are engineering strains. Default 0.01.	0.01
timestep	float64	Time step in ps. Default 0.001.	0.001
equilibration	int32	Steps before each average. Default 10000.	10000
production	int32	Steps of each average. Default 20000.	20000
every	int32	Steps between the stresses and boxes averaged. Default 10.	10
blocks	int32	Number of blocks of each average for its standard error. Default 5.	5
barostat	(iso, aniso, tri)	How the box changes while it finds its mean shape under pressure. Default "tri".	"iso"
seed	int32	Seed of the starting velocities. Default 1.	1

Returns:

Type	Description
ElasticResult	The (6, 6) elastic constants in GPa and their standard errors.

Raises:

Type	Description
InvalidParameter	For a box that is not periodic, a temperature, strain or numbers of steps that are not positive, fewer than two blocks, or the errors of MolecularDynamics.

ThermalElasticResult dataclass

ThermalElasticResult(temperatures, isothermal, adiabatic, method)

Bases: Result

Elastic constants of a crystal against temperature.

Attributes:

Name	Type	Description
temperatures	ndarray	(T,) float64 temperatures in K.
isothermal	ndarray	(T, 6, 6) float64 isothermal elastic constants in GPa, in Voigt order xx, yy, zz, yz, xz, xy.
adiabatic	ndarray	(T, 6, 6) float64 adiabatic elastic constants in GPa.
method	str	"quasi-harmonic" or "quasi-static".

Phonons

phonons

phonons(system, calculator, *, supercell=None, displacement=0.01, symmetry=None)

Harmonic phonons of a crystal, from the forces on atoms displaced in a supercell.

Parameters:

Name	Type	Description	Default
system	System	The cell of the crystal, periodic in every direction, or of a sheet, periodic along two vectors in the x-y plane and not along a third along z, with atoms at rest (relax it first); best its primitive cell. Each atom needs an element or a mass.	required
calculator	Calculator	Computes the forces.	required
supercell	int32 or array_like	Repeats of the cell along its vectors, one or three, or a (3, 3) integer matrix whose rows times the vectors of the cell are the vectors of the supercell; a sheet repeats along its plane only, and one integer means both of its vectors. Default the supercell nearest a cube that is at least twice the cutoff of the calculator thick in every direction, nearest a square across the plane for a sheet.	None
displacement	float64	Displacement of the atoms in Å. Default 0.01.	0.01
symmetry	bool	Move only the atoms and along the directions that the symmetry of the cell, found by spglib, does not relate to others: True, False, or by default whenever spglib is installed.	None

Returns:

Type	Description
Phonons	The force constants, which give frequencies, polarization vectors, band structures, densities of states and thermal properties.

Raises:

Type	Description
InvalidParameter	If the box is neither periodic nor that of a sheet, there are no atoms, an atom has no mass, the calculator does not compute forces, the supercell is not positive integers or a matrix of them with a positive determinant, the displacement is not positive, or symmetry is True without spglib.

Phonons

Phonons(cell, supercell, force_constants, masses, reference=None)

Harmonic phonons of a crystal from its force constants.

Made by phonons. Wave vectors are in units of the reciprocal lattice vectors of the cell: q = (h, k, l) is h b1 + k b2 + l b3 with a_i · b_j = 2π δ_ij.

Attributes:

Name	Type	Description
cell	System	The crystal whose vibrations these are.
supercell	ndarray	(3, 3) int64 matrix of the supercell in which the force constants were found: its vectors are the rows of the matrix times the vectors of the cell.
force_constants	ndarray	(n, n S, 3, 3) float64 second derivatives of the energy in eV/Ų with respect to the positions of each atom of the cell and of each atom of the supercell, which holds S cells, each with the atoms of the cell in their order, the first cell that of the cell itself.

frequencies

frequencies(q)

Phonon frequencies at wave vectors.

Parameters:

Name	Type	Description	Default
q	array_like of float64	A wave vector or (K, 3) wave vectors, in units of the reciprocal lattice vectors of the cell.	required

Returns:

Type	Description
ndarray	(3n,) or (K, 3n) float64 frequencies in THz, ascending; imaginary ones as negative.

modes

modes(q)

Phonon frequencies and polarization vectors at wave vectors.

Parameters:

Name	Type	Description	Default
q	array_like of float64	A wave vector or (K, 3) wave vectors, in units of the reciprocal lattice vectors of the cell.	required

Returns:

Name	Type	Description
frequencies	ndarray	(3n,) or (K, 3n) float64 frequencies in THz, ascending.
vectors	ndarray	(3n, n, 3) or (K, 3n, n, 3) complex128 polarization vector of each mode, normalized over the atoms of the cell; atom b of the cell in the cell at R moves along its vector divided by the square root of its mass, times exp(i q · (R + r_b)).

band_structure

band_structure(path, *, points=51, connected=False)

Phonon frequencies along a path through the Brillouin zone.

Parameters:

Name	Type	Description	Default
path	str or sequence of sequences of (str, array_like)	"auto" for the standard path of the crystal by its symmetry, from seekpath; "sc", "fcc", "bcc" or "hexagonal" for the standard path of that lattice, the cell having the axes of its conventional cell along x, y and z, or a along x and c along z; or the sections of a path, each a sequence of labeled wave vectors in units of the reciprocal lattice vectors of the cell, joined by straight lines.	required
points	int32	Number of wave vectors on each line, its ends included. Default 51.	51
connected	bool	Follow each branch along the path by its polarization vector, so that branches that cross stay apart; otherwise the frequencies are ascending at each wave vector. Default False.	False

Returns:

Type	Description
BandStructure	The wave vectors, their distances along the path, the frequencies and the labels of the special points.

Raises:

Type	Description
ImportError	For path "auto" without seekpath.

dos

dos(mesh=20, *, frequencies=None, sigma=None, projected=False)

The phonon density of states, by the tetrahedron method or with Gaussians.

Parameters:

Name	Type	Description	Default
mesh	int32 or array_like	Number of wave vectors along each reciprocal lattice vector, of a mesh through Γ. Default 20.	20
frequencies	array_like of float64	The frequencies in THz at which to give the density. Default 501 from 0, or a little below the lowest imaginary frequency, to a little above the highest.	None
sigma	float64	Width in THz of a Gaussian for each mode; by default the tetrahedron method.	None
projected	bool	Also give the part of each atom of the cell. Default False.	False

Returns:

Type	Description
PhononDOS	The frequencies and the density of states per atom.

Raises:

Type	Description
InvalidParameter	For a mesh or a sigma that is not positive.

thermal

thermal(temperatures, mesh=20)

Harmonic thermodynamic properties of the vibrations, by sums over the modes on a mesh.

Parameters:

Name	Type	Description	Default
temperatures	array_like of float64	Temperatures in K, not negative.	required
mesh	int32 or array_like	Number of wave vectors along each reciprocal lattice vector, of a mesh through Γ. Default 20.	20

Returns:

Type	Description
ThermalProperties	Free energy, energy, entropy and heat capacity per atom; modes below 1e-3 THz, the translations of the crystal, are left out.

Raises:

Type	Description
InvalidParameter	For a negative temperature, a mesh that is not positive, or imaginary frequencies on the mesh.

primitive_cell

primitive_cell(system, *, tolerance=0.0001)

The smallest periodic cell of a crystal.

Parameters:

Name	Type	Description	Default
system	System	A crystal in a box periodic in every direction, or a sheet, periodic along two vectors in the x-y plane and not along a third along z. Atoms are alike when they have the same element, type and mass, where the system has these columns.	required
tolerance	float64	How far, in Å, an atom may be from the image of another under a translation of the crystal. Default 1e-4.	0.0001

Returns:

Type	Description
System	The atoms of one primitive cell, with all the columns of system, in a box of short lattice vectors of the crystal with the same origin; system itself when its box is already primitive.

Raises:

Type	Description
InvalidParameter	If the box is neither periodic nor that of a sheet, or has no atoms.

BandStructure dataclass

BandStructure(q, distances, frequencies, labels)

Phonon frequencies along a path through the Brillouin zone.

Attributes:

Name	Type	Description
q	ndarray	(P, 3) float64 wave vectors in units of the reciprocal lattice vectors of the cell.
distances	ndarray	(P,) float64 distance of each wave vector along the path, in 1/Å.
frequencies	ndarray	(P, 3n) float64 frequencies in THz, ascending at each wave vector, or each column a branch when connected; imaginary ones as negative.
labels	tuple of (float64, str)	The distance and the label of each special point; two points that meet at a break of the path share a label such as "U|K".

write

write(path)

Writes the band structure in the format of phonopy's band.dat: the distances of the ends of the lines in 1/Å without the factor 2π, then each branch, line by line.

Parameters:

Name	Type	Description	Default
path	str or path - like	The file.	required

read_band_structure

read_band_structure(path)

A band structure from a file in the format of phonopy's band.dat.

Parameters:

Name	Type	Description	Default
path	str or path - like	The file, such as one phonopy wrote from a calculation with VASP.	required

Returns:

Type	Description
BandStructure	The distances, in 1/Å with the factor 2π, and the frequencies; the wave vectors are not in the file and are NaN, and the special points at the ends of the lines have no names.

Raises:

Type	Description
FileFormatError	If the file is not in that format.

PhononDOS dataclass

PhononDOS(frequencies, dos, projected=None)

The phonon density of states per atom.

Attributes:

Name	Type	Description
frequencies	ndarray	(F,) float64 frequencies in THz.
dos	ndarray	(F,) float64 states per THz per atom; it integrates to 3.
projected	ndarray or None	(F, n) float64, the density of states of each atom of the cell, each integrating to 3, whose mean is dos; when asked for.

ThermalProperties dataclass

ThermalProperties(temperatures, free_energy, energy, entropy, heat_capacity)

Harmonic thermodynamic properties of the vibrations, per atom.

Attributes:

Name	Type	Description
temperatures	ndarray	(T,) float64 temperatures in K.
free_energy	ndarray	(T,) float64 Helmholtz free energy of the vibrations in eV, with the zero point energy.
energy	ndarray	(T,) float64 energy of the vibrations in eV, with the zero point energy.
entropy	ndarray	(T,) float64 entropy in eV/K.
heat_capacity	ndarray	(T,) float64 heat capacity at constant volume in eV/K.

Phonons at finite temperature

thermal_phonons

thermal_phonons(cell, potential, temperature, *, supercell=None, pressure=0.0, timestep=0.001, equilibration=10.0, production=100.0, frames=200, symmetry=None, seed=1, progress=None, cancel=None)

Phonons of a crystal at a temperature, from molecular dynamics in LAMMPS: the force constants that best give the forces on the moving atoms, which change with the temperature as the vibrations feel the crystal further from its minimum.

Parameters:

Name	Type	Description	Default
cell	System	The cell of the crystal, relaxed, with an element column, periodic in every direction; best its primitive cell.	required
potential	LAMMPS	The interaction.	required
temperature	float64	Temperature in K, positive.	required
supercell	int32 or array_like	Repeats of the cell along its vectors, one or three, or a (3, 3) integer matrix. Default the supercell nearest a cube that is at least twice the cutoff of the potential thick in every direction.	None
pressure	float64 or None	Pressure in GPa at which the box takes its mean size first; None to keep the box of cell. Default 0.	0.0
timestep	float64	Time step in ps. Default 0.001.	0.001
equilibration	float64	Time in ps of each equilibration. Default 10.	10.0
production	float64	Time in ps over which the frames are taken. Default 100.	100.0
frames	int32	Number of frames. Default 200.	200
symmetry	bool	Average the force constants over the symmetry operations of the cell, found by spglib: True, False, or by default whenever spglib is installed.	None
seed	int32	Seed of the random numbers, positive. Default 1.	1
progress	callable	Called as progress(done, total) with the steps run.	None
cancel	CancelToken	Stops the calculation, which raises mdapy.errors.Cancelled.	None

Returns:

Type	Description
Phonons	The phonons, whose cell has the mean box at this temperature.

Raises:

Type	Description
InvalidParameter	For invalid options, a box not periodic in every direction, too few frames, or if LAMMPS fails.
MissingProperty	If the system has no element column.
Cancelled	If cancelled.

phonons_from_frames

phonons_from_frames(cell, frames, *, supercell, symmetry=None)

Phonons from atoms displaced in a supercell and the forces on them, from molecular dynamics of any kind: the force constants that best give the forces, which hold the temperature of the frames.

Parameters:

Name	Type	Description	Default
cell	System	The cell of the crystal, periodic in every direction, with the atoms at their places at the volume of the frames, each with an element or a mass; best its primitive cell.	required
frames	iterable of System	The atoms of the supercell, in its order, with a forces column: cells in the order of Phonons.force_constants, as phonons makes them; far enough apart in time to differ.	required
supercell	int32 or array_like	Repeats of the cell along its vectors, one or three, or a (3, 3) integer matrix whose rows times the vectors of the cell are the vectors of the supercell.	required
symmetry	bool	Average the force constants over the symmetry operations of the cell, found by spglib: True, False, or by default whenever spglib is installed.	None

Returns:

Type	Description
Phonons	The force constants, which give frequencies, polarization vectors, band structures, densities of states and thermal properties.

Raises:

Type	Description
InvalidParameter	If the box is not periodic, an atom has no mass, the supercell is not valid, a frame has another number of atoms, or there are too few frames for the force constants.
MissingProperty	If a frame has no forces column.

Quasi-harmonic approximation

quasi_harmonic

quasi_harmonic(system, calculator, temperatures, *, volumes=None, pressures=None, pressure=0.0, supercell=None, mesh=20, displacement=0.01, max_force=1e-06, max_stress=0.0001, max_steps=5000, symmetry=None)

Thermodynamic properties of a crystal in the quasi-harmonic approximation: harmonic phonons at several volumes.

Parameters:

Name	Type	Description	Default
system	System	The cell of the crystal, periodic in every direction, best relaxed and primitive. Each atom needs an element or a mass.	required
calculator	Calculator	Computes energies and forces.	required
temperatures	array_like of float64	Temperatures in K, not negative.	required
volumes	array_like of float64	The volumes at which to compute the phonons, five or more, as ratios to the volume of system; at each the box keeps its volume while its shape and the positions relax. Default 9 from 0.97 to 1.09.	None
pressures	array_like of float64	Instead of volumes, the pressures in GPa under which the box and the positions relax, five or more.	None
pressure	float64	Pressure in GPa. Default 0.	0.0
supercell	int32 or array_like	Repeats of the cell for the phonons, as in phonons.	None
mesh	int32 or array_like	Mesh of wave vectors for the thermal properties. Default 20.	20
displacement	float64	Displacement of the atoms for the force constants in Å. Default 0.01.	0.01
max_force	float64	Convergence of the relaxation at each volume in eV/Å. Default 1e-6.	1e-06
max_stress	float64	Convergence of the relaxation of the box under each pressure in GPa. Default 1e-4.	0.0001
max_steps	int32	Largest number of steps of each relaxation. Default 5000.	5000
symmetry	bool	Use the symmetry of the cells in the phonons, as in phonons. Default whenever spglib is installed.	None

Returns:

Type	Description
QuasiHarmonicResult	Per atom: the equilibrium volume, Gibbs energy, entropy, bulk modulus, thermal expansion and heat capacity at each temperature, and the static and vibrational energies at each volume.

Raises:

Type	Description
InvalidParameter	For a box not periodic in every direction, a negative temperature, both volumes and pressures, fewer than five of them, a relaxation that does not converge, imaginary frequencies at a volume, or an equilibrium volume outside the volumes.

QuasiHarmonicResult dataclass

QuasiHarmonicResult(temperatures, pressure, volume, gibbs_energy, entropy, bulk_modulus, thermal_expansion, heat_capacity, volumes, energies, free_energies, cells=())

Bases: Result

Thermodynamic properties of a crystal in the quasi-harmonic approximation, per atom.

Attributes:

Name	Type	Description
temperatures	ndarray	(T,) float64 temperatures in K.
pressure	float64	Pressure in GPa.
volume	ndarray	(T,) float64 equilibrium volume in ų.
gibbs_energy	ndarray	(T,) float64 Gibbs energy in eV: the static energy, the free energy of the vibrations and the pressure times the volume.
entropy	ndarray	(T,) float64 entropy in eV/K.
bulk_modulus	ndarray	(T,) float64 isothermal bulk modulus in GPa.
thermal_expansion	ndarray	(T,) float64 volumetric thermal expansion coefficient in 1/K.
heat_capacity	ndarray	(T,) float64 heat capacity at constant pressure in eV/K.
volumes	ndarray	(V,) float64, the volumes in ų at which the phonons were computed.
energies	ndarray	(V,) float64 static energy at each volume in eV.
free_energies	ndarray	(V, T) float64 free energy of the vibrations at each volume and temperature in eV.
cells	tuple of System	The relaxed cell at each volume.