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, hr_file=None, 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.

hr_filestr

Filename. If given, save _hr.dat file as produced by Wannier90.

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
Ninteger

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 R_CARTESIAN from crystal coordinates to cartesian coordinates.

Parameters
R_CARTESIAN: ndarray

Lattice structure in cartesian coordinates

a1,a2,a3: ndarray

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)

Transform a lattice structure R_CRYSTAL from crystal coordinates to cartesian coordinates.

Parameters
R_CRYSTAL: ndarray

Lattice structure in crystal coordinates

a1,a2,a3: ndarray

Lattice vectors

Returns
R_CARTESIAN: ndarray

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.linear_interpolation(data, angle=60, axes=(0, 1), period=None)

Perform linear interpolation on triangular or rectangular lattice.

The edges are interpolated using periodic boundary conditions.

Parameters
datandarray

Data on uniform triangular or rectangular lattice.

anglenumber

Angle between lattice vectors in degrees.

axes2-tuple of ints

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

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

Condese point cloud on periodic axis.

resize

Compress or strech data via linear interpolation.

Fourier_interpolation

Alternative interpolation routine.

elphmod.bravais.path(points, b, N=30)

Generate arbitrary path through Brillouin zone.

Parameters
pointsndarray

List of high-symmetry points in crystal coordinates.

bndarray

List of reciprocal lattice vectors.

Ninteger

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

Returns
ndarray

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

ndarray

Cumulative path distance.

list, optional

Indices of corner/high-symmetry points.

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

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

Parameters
eps: float
Numerical parameter, in case the the cross product is not exactly 0.
Returns
bool

True, if the test_point is on a straight line between point A and B

elphmod.bravais.readPOSCAR(filename)

Read crystal structure from VASP input file.

Parameters
filenamestr

File name.

Returns
dict

Crystal structure.

elphmod.bravais.read_pwi(pwi)

Read crystal structure from PW input file.

Parameters
pwistr

File name.

Returns
dict

Crystal structure.

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?

natint

Number of atoms per unit cell.

See also

write_wigner_file, wigner_seitz_x, elph.Model
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=None, angle=60, axes=(0, 1), period=None)

Resize array via linear interpolation along two periodic axes.

Parameters
shape2-tuple of ints

New lattice shape. Defaults to the original shape.

shape, angle, axes, period

Parameters for linear_interpolation().

Returns
ndarray

Resized data array.

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

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

Maxmium 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, k2integer

Mesh-point indices.

nkint

Number of points per dimension.

anglenumber

Angle between lattice vectors.

dk1, dk2number

Shift of Voronoi cell.

epsilonfloat

Maxmium absolute difference of “equal” floats.

Returns
set

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

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

Maxmium 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.wigner_seitz_x(x, nk, at=None, tau=None, epsilon=1e-08)

Emulate the EPW subroutine wigner_seitz{x} in wigner.f90.

Parameters
xstr

Type of Wigner-Seitz cell:

  • 'k': cell-centered

  • 'q': bond-centered

  • 'g': atom-centered

nkint

Number of points per dimension.

at, taundarray

Geometry as returned by ph.read_flfrc() and ph.model().

epsilonfloat

Maxmium 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_pwi(pwi, struct)

Write crystal structure to PW input file.

Parameters
pwistr

File name.

structdict

Crystal structure.

elphmod.bravais.write_wigner_file(name, nk, nq, at=None, tau=None, epsilon=1e-08)

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

ATTENTION: This function is compatible with read_wigner_file for old_ws=True only!

See also

read_wigner_file, wigner_seitz_x, elph.Model