Utilities for `brille`

These functions help to construct lattices and grids for brillouin zone interpolation.

import numpy as np
from brille.utils import create_bz, create_grid

def dispersion(q):
  energies = np.sum(np.cos(np.pi * q), axis=1)
  eigenvectors = np.sin(np.pi * q)
  return energies, eigenvectors

bz = create_bz([4.1, 4.1, 4.1], [90, 90, 90], spacegroup='F m -3 m')
grid = create_grid(bz, node_volume_fraction=1e-6)
energies, eigenvectors = dispersion(grid.rlu)
n_energies = 1     # Only one mode
n_eigenvectors = 3 # Three values per q
rotateslike = 0    # See note below
grid.fill(energies, [n_energies, 0, 0, rotateslike],
          eigenvectors, [n_eigenvectors, 0, 0, rotateslike])

interp_en, interp_ev = grid.ir_interpolate_at(np.random.rand(1000, 3))

Note

The rotateslike enumeration is given in fill() and describes how the eigenvalues / eigenvectors should be treated on application of a symmetry operation. The gamma option (rotateslike=3) should be used for phonon eigenvectors.

brille.utils.create_bz(*args, is_reciprocal=False, use_primitive=True, search_length=1, time_reversal_symmetry=False, wedge_search=True, snap_to_symmetry=True, **kwargs)

Construct a BrillouinZone object.

Parameters:

a, b, c (float) – Lattice parameters as separate floating point values
lens ((3,) numpy.ndarray or list) – Lattice parameters as a 3-element array or list
alpha, beta, gamma (float) – Lattice angles in degrees or radians as separate floating point values Brille tries to determine if the input is in degrees or radians by looking at its magnitude. If the values are all less than PI it assumes the angles are in radians otherwise it assumes degrees
angs ((3,) numpy.ndarray or list) – Lattice angles in degrees or radians as a 3-element array or list
lattice_vectors ((3, 3) numpy.ndarray or list of list) – The lattice vectors as a 3x3 matrix, array or list of list
spacegroup (str or int) – The spacegroup in either International Tables (Hermann-Mauguin) notation or a Hall symbol or an integer Hall number.
is_reciprocal (bool, keyword-only optional (default: False)) – Whether the lattice parameters or lattice vectors refers to a reciprocal rather than direct lattice. If True, a/b/c/lens should be in reciprocal Angstrom, otherwise they should be in Angstrom
use_primitive (bool, keyword-only optional (default: True)) – Whether the primitive (or conventional) lattice should be used
search_length (int, keyword-only optional (default: 1)) – An integer to control how-far the vertex-finding algorithm should search in τ-index. The default indicates that (1̄1̄1̄), (1̄1̄0), (1̄1̄1), (1̄0̄1), …, (111) are included.
time_reversal_symmetry (bool, keyword-only optional (default: False)) – Whether to include time-reversal symmetry as an operation to determine the irreducible Brillouin zone
wedge_search (bool, keyword-only optional (default: True)) – If true, return an irreducible first Brillouin zone, otherwise just return the first Brillouin zone
snap_to_symmetry (bool, keyword-only optional (default: True)) – Enforces that provided lattice parameters / basis vectors / atom-basis positions conform to the provided symmetry operations, if present.

Note

Note that the required lattice parameters must be specified as:

EITHER create_bz(a, b, c, alpha, beta, gamma, spacegroup, ...)
OR create_bz(lens, angs, spacegroup, ...)
OR create_bz(lattice_vectors, spacegroup, ...)

E.g. you cannot mix specifing a, b, c, and angs etc.

brille.utils.create_grid(bz, complex_values=False, complex_vectors=False, mesh=False, nest=False, **kwargs)

Constructs an interpolation grid for a given BrillouinZone object

Brille provides three different grid implementations:

BZTrellisQ: A hybrid Cartesian and tetrahedral grid, with tetrahedral nodes on the BZ surface and cuboids inside. [Default]
BZMeshQ: A fully tetrahedral grid with a flat data structure
BZNestQ: A fully tetrahedral grid with a nested tree data structure.

By default, a BZTrellisQ grid will be used.

Parameters:

bz (:py:class: BrillouinZone) – A BrillouinZone object (required)
complex_values (bool, optional (default: False)) – Whether the interpolated scalar quantities are complex
complex_vectors (bool, optional (default: False)) – Whether the interpolated vector quantities are complex
mesh (bool, optional (default: False)) – Whether to construct a BZMeshQ instead of a BZTrellisQ grid
nest (bool, optional (default: False)) – Whether to construct a BZNestQ instead of a BZTrellisQ grid

Note

Note that setting both mesh and nest to True gives an error.

Additional keyword parameters will be passed to the relevant grid constructors.

For BZTrellisQ, these are:

Parameters:

node_volume_fraction (float, optional (default: 1e-5)) – The fractional volume of a tetrahedron in the mesh. Smaller numbers will result in better interpolation accuracy at the cost of greater computation time.
always_triangulate (bool, optional (default: False)) – If set to True, we calculate a bounding polyhedron for each point in the grid, and triangulate this into tetrahedrons. If False, we set internal points to be cuboid and compute tetrahedrons only for points near the surface of the Brillouin Zone.

For BZMeshQ, these additional parameters are available:

Parameters:

max_size (float, optional (default: -1.0)) – The maximum volume of a tetrahedron in cubic reciprocal Angstrom. If set to a negative value, Tetgen will generate a tetrahedral mesh without a volume constraint.
num_levels (int, optional (default: 3)) – The number of layers of triangulation to use.
max_points (int, optional (default: -1)) – The maximum number of additional mesh points to add to improve the mesh quality. Setting this to -1 will allow Tetgen to create an unlimited number of additional points.

For BZNestQ, these additional parameters are available:

Parameters:

max_volume (float) – Maximum volume of a tetrahedron in cubic reciprocal Angstrom.
number_density (float) – Number density of points in reciprocal space.
max_branchings (int, optional (default: 5)) – Maximum number of branchings in the tree structure

Note

Note that one of either the max_volume or number_density parameters must be provided to construct a BZNestQ.

Utilities for brille

Utilities for `brille`