Bravais

Lattices, symmetries, and interpolation.

elphmod.bravais.BZ(angle=120, angle0=0)

Draw Brillouin zone outline.

elphmod.bravais.Fourier_interpolation(data, angle=60, sign=-1, function=True)

Perform Fourier interpolation on triangular or rectangular lattice.

Parameters:

datandarray

Data on uniform triangular or rectangular lattice.

anglenumber

Angle between lattice vectors in degrees.

signnumber

Sign in exponential function in first Fourier transform.

functionbool

Return interpolation function or parameter dictionary?

Returns:

function

Interpolant for data. Fourier_interpolation(data)(i, j) yields the same value as data[i, j]. Thus the data array is “generalized” with respect to fractional indices.

See also

linear_interpolation

Alternative interpolation routine.

elphmod.bravais.GMKG(N=30, corner_indices=False, mesh=False, angle=60, straight=True, lift_degen=True)

Generate path Γ-M-K-Γ through Brillouin zone.

(This function should be replaced by a more general one to produce arbitrary paths through both triangular and rectangular Brillouin zones, where special points can be defined using labels such as 'G', 'M', or 'K'.)

Parameters:

Nint

Number of mesh points per dimension if mesh is True and N is a multiple of 6. Otherwise the number of points per \(2 \pi / a\).

corner_indicesbool

Return indices of corner/high-symmetry points?

meshbool

Return points of uniform mesh that exactly lie on the path? If True, N must be a multiple of 6.

anglenumber

Angle between reciprocal basis lattice vectors.

straightbool

Cross K in a straight line? In this case, the path does not enclose the irreducible wedge.

lift_degenbool

Lift degeneracy at K by infinitesimal shift toward Γ?

Returns:

ndarray

Points in crystal coordinates with period \(2 \pi\).

ndarray

Cumulative path distance.

list, optional

Indices of corner/high-symmetry points.

elphmod.bravais.cartesian_to_crystal(R_CARTESIAN, a1, a2, a3)

Transform a lattice structure from crystal to Cartesian coordinates.

Parameters:

R_CARTESIANndarray

Lattice structure in Cartesian coordinates.

a1, a2, a3ndarray

Lattice vectors.

Returns:

R_CRYSTAL: ndarray

Lattice structure in crystal coordinates.

elphmod.bravais.complete(data, angle=60)

Complete data on Monkhorst-Pack mesh.

Parameters:

datandarray

Incomplete data on uniform mesh. Missing values are represented by NaN.

anglefloat

Angle between mesh axes in degrees.

Returns:

ndarray

Input data with missing values determined via the symmetries found.

elphmod.bravais.complete_k(wedge, nq)

Calculate k dependence for equivalent q points.

Parameters:

wedgendarray

Data on irreducible q wedge and uniform k mesh.

nqint

Number of q points per dimension.

Returns:

ndarray

Data on uniform q and k meshes.

elphmod.bravais.crystal_to_cartesian(R_CRYSTAL, a1, a2, a3=None)

Transform a lattice structure from crystal to Cartesian coordinates.

Parameters:

R_CRYSTALndarray

Lattice structure in crystal coordinates.

a1, a2, a3ndarray

Lattice vectors.

Returns:

R_CARTESIANndarray

Lattice structure in Cartesian coordinates.

elphmod.bravais.images(k1, k2, nk, angle=60)

Generate symmetry-equivalent k points.

Parameters:

k1, k2int

Indices of point in uniform mesh.

nkint

Number of mesh points per dimension.

anglefloat

Angle between mesh axes in degrees.

Returns:

set

Mesh-point indices of all equivalent k points.

elphmod.bravais.irreducibles(nk, angle=60)

Generate set of irreducible k points.

Parameters:

nkint

Number of mesh points per dimension.

anglefloat

Angle between mesh axes in degrees.

Returns:

set

Mesh-point indices of irreducible k points.

Of all equivalent points, the first occurrence in the sequence

\[(0, 0), (0, 1), \dots, (0, n_k - 1), (1, 0), (1, 1), \dots\]

is chosen. sorted() should yield the same irreducible q points as used by Quantum ESPRESSO’s PHonon code and found in the file fildyn0.

elphmod.bravais.kpoints(nk1=None, nk2=None, nk3=None, weights=None)

Generate and print uniform k-point mesh.

Omitted arguments are read from standard input.

Parameters:

nk1, nk2, nk3int

Number of points along axis.

weightsbool

Print weights?

elphmod.bravais.linear_interpolation(data, angle=60, axes=(0, 1), period=None, polar=False)

Perform linear interpolation in one or two dimensions.

The edges are interpolated using periodic boundary conditions.

Parameters:

datandarray

Data on uniform 1D or 2D (triangular or rectangular) lattice.

anglenumber

Angle between lattice vectors in degrees.

axesint or 2-tuple of int

Axes of data along which to interpolate (lattice vectors).

periodnumber

If the values of data are defined on a periodic axis (i.e., only with respect to the modulo operation), the period of this axis. This is used in combination with stack to always interpolate across the shortest distance of two neighboring points.

polarbool

Interpolate complex values linearly in polar coordinates? This is helpful if neighboring data points have arbitrary complex phases.

Returns:

function

Interpolant for data. linear_interpolation(data)(i, j) yields the same value as data[i, j]. Thus the data array is “generalized” with respect to fractional indices.

See also

stack

Condense point cloud on periodic axis.

resize

Compress or stretch data via linear interpolation.

Fourier_interpolation

Alternative interpolation routine.

elphmod.bravais.mesh(*n, flat=False)

Generate uniform mesh.

Parameters:

*nint

Mesh dimensions.

flatbool, default False

Flatten mesh-point indices into single dimension?

Returns:

ndarray

Mesh points with period \(2 \pi\).

elphmod.bravais.path(points, N=30, recvec=None, qe=False, moveG=0, **kwargs)

Generate arbitrary path through Brillouin zone.

Parameters:

pointsndarray

List of high-symmetry points in crystal coordinates. Some well-known labels such as G (Γ), M, or K may also be used. Mostly, the definitions follow https://lampx.tugraz.at/~hadley/ss1/bzones/.

Nfloat

Number of points per \(2 \pi / a\).

recvecndarray, optional

List of reciprocal lattice vectors.

qebool, default False

Also return path in QE input format?

moveGfloat, default 0

Move Gamma point to the closest nonzero point multiplied by this value. This is useful, e.g., to plot phonon dispersions with TO-LO splitting.

**kwargs

Arguments passed to primitives(), e.g., parameters from ‘func’read_pwi, particularly the Bravais-lattice index ibrav.

Returns:

ndarray

Points in crystal coordinates with period \(2 \pi\).

ndarray

Cumulative path distance.

list

Indices of corner/high-symmetry points.

dict, optional

Path in format suitable for write_pwi().

See also

primitives

reciprocals

elphmod.bravais.point_on_path(test_point, point_A, point_B, eps=1e-14)

Test whether a test_point is between the points A and B.

Parameters:

epsfloat

Numerical parameter, in case the cross product is not exactly 0.

Returns:

bool

Is the test_point on a straight line between point A and B?

elphmod.bravais.primitives(ibrav=8, a=1.0, b=1.0, c=1.0, cosbc=0.0, cosac=0.0, cosab=0.0, celldm=None, bohr=False, r_cell=None, cell_units=None, **ignore)

Get primitive vectors of Bravais lattice as in QE.

Adapted from Modules/latgen.f90 of Quantum ESPRESSO.

For documentation, see http://www.quantum-espresso.org/Doc/INPUT_PW.html.

Parameters:

ibravint

Bravais-lattice index.

a, b, c, cosbc, cosac, cosabfloat

Traditional crystallographic constants in angstrom.

celldmlist of float

Alternative crystallographic constants. The first element is the lattice constant in bohr; the other elements are dimensionless.

bohrbool, default False

Return lattice vectors in angstrom or bohr?

r_cell, cell_units

Cell parameters from ‘func’read_pwi used if ibrav is zero.

**ignore

Ignored keyword arguments, e.g., parameters from ‘func’read_pwi.

Returns:

ndarray

Matrix of primitive Bravais lattice vectors.

elphmod.bravais.readPOSCAR(filename)

Read crystal structure from VASP input file.

Parameters:

filenamestr

Filename.

Returns:

dict

Crystal structure.

elphmod.bravais.read_epw(filename)

Read input parameters from Quantum ESPRESSO’s epw.x input file.

Parameters:

filenamestr

Filename.

Returns:

dict

Input parameters.

elphmod.bravais.read_matdyn(filename)

Read input parameters from Quantum ESPRESSO’s matdyn.x input file.

Parameters:

filenamestr

Filename.

Returns:

dict

Input parameters.

elphmod.bravais.read_ph(filename)

Read input parameters from Quantum ESPRESSO’s ph.x input file.

Parameters:

filenamestr

Filename.

Returns:

dict

Input parameters.

elphmod.bravais.read_pwi(pwi)

Read input data and crystal structure from PWscf input file.

Parameters:

pwistr

Filename.

Returns:

dict

Input data and crystal structure.

elphmod.bravais.read_q2r(filename)

Read input parameters from Quantum ESPRESSO’s q2r.x input file.

Parameters:

filenamestr

Filename.

Returns:

dict

Input parameters.

elphmod.bravais.read_wigner_file(name, old_ws=False, nat=None)

Read binary file with Wigner-Seitz data as used by EPW.

Parameters:

namestr

Name of file with Wigner-Seitz data.

old_wsbool

Use previous definition of Wigner-Seitz cells? This is required if patches/qe-6.3-backports.patch has been used.

natint

Number of atoms per unit cell.

See also

elphmod.elph.Model

elphmod.bravais.read_win(win)

Read input data from .win file (Wannier90).

Parameters:

winstr

Filename.

Returns:

dict

Crystal structure.

elphmod.bravais.reciprocals(a1, a2, a3=None)

Generate translation vectors of reciprocal lattice.

Parameters:

a1, a2ndarray

Translation vectors of Bravais lattice.

Returns:

ndarray, ndarray

Translation vectors of reciprocal lattice (without \(2 \pi\)).

elphmod.bravais.resize(data, shape, angle=60, axes=(0, 1), period=None, polar=False, periodic=True)

Resize array via linear interpolation along one or two axes.

Parameters:

shapeint or 2-tuple of int

New lattice shape.

shape, angle, axes, period, polar

Parameters for linear_interpolation().

periodicbool, default True

Interpolate between last and first data point of each axis?

Returns:

ndarray

Resized data array.

See also

linear_interpolation

elphmod.bravais.rotate(vector, angle, two_dimensional=True)

Rotate vector anti-clockwise.

Parameters:

vectorarray_like

Two-dimensional vector.

anglefloat

Rotation angle in radians.

Returns:

ndarray

Rotated vector.

elphmod.bravais.short_range_model(data, at, tau, sgn=1, divide_ndegen=True)

Map hoppings or force constants onto Wigner-Seitz cell.

Parameters:

datandarray

Hoppings or force constants on (positive) Fourier-transform mesh. The first two dimensions correspond to the orbitals or atoms, the following three to the mesh axes, and the last two (optional, relevant for force constants only) to Cartesian directions.

atndarray

Bravais lattice vectors.

taundarray

Positions of basis orbitals or atoms.

sgnint

Do the lattice vectors shift the first (-1) or second (+1) orbital/atom?

divide_ndegenbool

Divide hoppings for force constants by lattice-vector degeneracy?

Returns:

irvecndarray

Wigner-Seitz lattice vectors.

constndarray

Corresponding hoppings or force constants.

wslenndarray

Corresponding lengths.

elphmod.bravais.squared_distance(k1, k2, angle=60)

Calculate squared distance of lattice point from origin.

If the coordinates are given as integers, the result is numerically exact. For 60 or 120 deg. (triangular lattice) this yields the Loeschian numbers. Non-equivalent lattice sites may have the same distance from the origin! (E.g., there are non-equivalent 20th neighbors in a triangular lattice.)

Parameters:

k1, k2int

Point in lattice coordinates (crystal coordinates, mesh-indices, …).

anglenumber

Angle between lattice axes.

Returns:

number

Squared distance of point from origin.

elphmod.bravais.stack(*points, **kwargs)

Minimize distance of points on periodic axis via full-period shifts.

Example:

>>> stack(3, 5, 9, 12, period=10)
[13, 15, 9, 12]

 In: ... | ox x   x| xo o   o| oo o   o| ...
Out: ... | oo o   x| xx x   o| oo o   o| ...

Parameters:

*points

Points on periodic axis.

periodfloat

Period of axis. Specified via **kwargs for Python-2 compatibility.

Returns:

ndarray

Points equivalent to input, with minimal distance on non-periodic axis.

elphmod.bravais.supercell(N1=1, N2=1, N3=1)

Set up supercell.

Parameters:

N1, N2, N3tuple of int or int, default 1

Supercell lattice vectors in units of primitive lattice vectors. Multiples of single primitive vector can be defined via a scalar integer, linear combinations via a 3-tuple of integers.

Returns:

int

Number of unit cells in supercell.

tuple of ndarray

Integer vectors spanning the supercell.

tuple of ndarray

Integer vectors spanning the reciprocal supercell.

list of tuple

Integer positions of the unit cells in the supercell.

elphmod.bravais.symmetries(data, epsilon=0.0, unity=True, angle=60)

Find symmetries of data on Monkhorst-Pack mesh.

Parameters:

datandarray

Data on uniform k mesh.

epsilonfloat

Maximum absolute difference of “equal” floats.

unitybool

Return identity as first symmetry?

anglefloat

Angle between mesh axes in degrees.

Returns:

iterator

All symmetries found are returned one after the other.

Each symmetry is described by a Boolean (“reflection?”) and a rotation angle in degrees, followed by a mapping between the k-point indices of the original and the transformed mesh.

elphmod.bravais.to_Voronoi(k1, k2, nk, angle=60, dk1=0, dk2=0, epsilon=0.0)

Map any lattice point to the Voronoi cell* around the origin.

(*) Wigner-Seitz cell/Brillouin zone for Bravais/reciprocal lattice.

Parameters:

k1, k2int

Mesh-point indices.

nkint

Number of points per dimension.

anglenumber

Angle between lattice vectors.

dk1, dk2number

Shift of Voronoi cell.

epsilonfloat

Maximum absolute difference of “equal” floats.

Returns:

set

All equivalent point within or on the edge of the Voronoi cell.

elphmod.bravais.to_supercell(R, supercell)

Map lattice vector to supercell.

Parameters:

Rtuple of int

Unit-cell lattice vector.

supercelltuple

Supercell info returned by supercell().

Returns:

tuple of int

Supercell lattice vector.

int

Index of unit cell within supercell.

elphmod.bravais.translations(angle=120, angle0=0, two_dimensional=True)

Generate translation vectors of Bravais lattice.

Parameters:

anglefloat

Angle between first and second vector in degrees:

VALUE  LATTICE
   60  hexagonal
   90  square
  120  hexagonal (ibrav = 4 in Quantum ESPRESSO)

angle0float

Angle between x axis and first vector in degrees.

Returns:

ndarray, ndarray

Translation vectors of Bravais lattice.

elphmod.bravais.volume(a1, a2=None, a3=None)

Calculate unit-cell volume/area/length.

Parameters:

a1, a2, a3ndarray

Primite lattice vectors.

Returns:

float

Unit-cell volume/area/length.

elphmod.bravais.wigner(nr1, nr2, nr3, at, tau, tau2=None, eps=1e-07, sgn=1, nsc=2)

Determine Wigner-Seitz lattice vectors with degenercies and lengths.

Parameters:

nr1, nr2, nr3ndarray

Dimensions of positive lattice-vector mesh.

atndarray

Bravais lattice vectors.

taundarray

Positions of basis orbitals or atoms in original cell.

tau2ndarray, optional

Positions of basis orbitals or atoms in shifted cell. Defaults to tau.

epsfloat

Tolerance for orbital or atomic distances to be considered equal.

sgnint

Do the lattice vectors shift the first (-1) or second (+1) orbital/atom?

nscint

Number of supercells per dimension and direction where Wigner-Seitz lattice vectors are searched for.

Returns:

irvecndarray

Wigner-Seitz lattice vectors.

ndegenndarray

Corresponding degeneracies.

wslenndarray

Corresponding lengths.

elphmod.bravais.wigner_2d(nk, angle=120, dk1=0.0, dk2=0.0, epsilon=0.0)

Find lattice points in Wigner-Seitz cell (including boundary).

Parameters:

nkint

Number of points per dimension.

anglenumber

Angle between lattice vectors.

dk1, dk2float

Shift of Wigner-Seitz cell.

epsilonfloat

Maximum absolute difference of “equal” floats.

Returns:

list of tuple of int

Mesh-point indices.

list of int

Degeneracies.

list of float

Lattice-vector lengths.

elphmod.bravais.write_epw(epw, struct)

Write input data to epw file (Quantum ESPRRESO).

Parameters:

epwstr

Filename.

structdict

Input data.

elphmod.bravais.write_matdyn(matdyn, struct)

Write input data to matdyn file (Quantum ESPRRESO).

Parameters:

matdynstr

Filename.

structdict

Input data.

elphmod.bravais.write_ph(ph, struct)

Write input data to ph file (Quantum ESPRESSO).

Parameters:

phstr

Filename.

structdict

Input data.

elphmod.bravais.write_pwi(pwi, struct)

Write crystal structure to PWscf input file.

Parameters:

pwistr

Filename.

structdict

Crystal structure.

elphmod.bravais.write_q2r(q2r, struct)

Write input data to q2r file (Quantum ESPRRESO).

Parameters:

q2rstr

Filename.

structdict

Input data.

elphmod.bravais.write_win(win, struct)

Write input data to .win file (Wannier90).

Parameters:

winstr

Filename.

structdict

Input data.