Grids

There are likely myriad ways one could divide an \(N\) dimensional space but the two most basic building blocks are the parallelepiped (or its \(N\) dimensional equivalent) and the \(N\)-simplex. An \(N\)-simplex always requires \(N+1\) points where a parallelepiped requires \(2^N\).

The parallelepiped lends itself to a regular grid while arrangements of N-simplexs can be regular or irregular. In two dimensions the parallelepiped grid is a regular Cartesian grid:

Figure made with TikZ

while an irregular mesh of triangles is also possible:

Figure made with TikZ

The brille._brille module implements multiple grid types for linear interpolation within the first or irreducible Brillouin zone. In most cases the BZTrellisQdc should be used.

Since the grids are intended to be used with eigenvectors and their associated eigenvalues each must support mixed real and complex data. To allow this, each type of grid is exposed to Python three times with a suffix dd for (double, double), dc for (double, std::complex<double>) and cc for (std::complex<double>, std::complex<double>).

Regular grids

Interpolation using grids constructed of regular parallelepipeds is possible, but will lead to artefacts near the Brillouin zone boundary if the primitive lattice has any non-orthogonal basis vectors. This is such a large restriction that regular grids are no longer supported in brille._brille

Figure made with TikZ

Triangulated grids

An alternative to the regular parallelepiped grid which may still have some utility is the triangulation of a bounded space. If the triangulated space is bounded by a polyhedron then the triangulation can always represent it exactly, though possibly with sub-optimal triangulated cells.

Figure made with TikZ

There are two exposed implementations of the triangulated grid, both detailed below under the headings Simple and Hierarchy.

Simple

The BZMeshQdc and its type-siblings implement a simple triangulated grid. Locating the tetrahedron within the grid which contains a test point could require as many in-tetrahedron checks as there are tetrahedra in the grid. This class should be fine for use in applications where intra-grid-point interpolation is not required, such as Brillouin zone integrations, but should be avoided when interpolation at random points is required.

class brille._brille.BZMeshQdd(self: brille._brille.BZMeshQdd, brillouin_zone: brille._brille.BrillouinZone, max_size: float = -1.0, num_levels: int = 3, max_points: int = -1)
class brille._brille.BZMeshQcc(self: brille._brille.BZMeshQcc, brillouin_zone: brille._brille.BrillouinZone, max_size: float = -1.0, num_levels: int = 3, max_points: int = -1)
class brille._brille.BZMeshQdc(self: brille._brille.BZMeshQdc, brillouin_zone: brille._brille.BrillouinZone, max_size: float = -1.0, num_levels: int = 3, max_points: int = -1)
property bytes_per_point

Return the memory required per interpolation point result in bytes

fill(*args, **kwargs)

Overloaded function.

  1. fill(self: brille._brille.BZMeshQdc, values_data: numpy.ndarray[numpy.float64], values_elements: numpy.ndarray[numpy.int32], vectors_data: numpy.ndarray[numpy.complex128], vectors_elements: numpy.ndarray[numpy.int32], sort: bool = False) -> None

Provide data required for interpolation to the grid without cost information.

Parameters:

  • values_data (numpy.ndarray) – The eigenvalue data to be stored in the grid. The first dimension must be equal in size to the number of grid-vertices. If two dimensional the second dimension is interpreted as all information for a single mode flattened and concatenated into (scalars, vectors, matrices) – in that order. If more than two dimensional, the second dimension indexes modes and higher dimensions will be flattened as if row ordered and must flatten into a concatenated list of (scalars, vectors, matrices). If the provided array can be interpreted as a contiguous row-ordered two dimensional array it will be used in place, otherwise a copy will be made.

  • values_elements (integer vector-like) – A multi-purpose vector containing, in order:

    • the number of scalar-like eigenvalue elements,

    • the number of vector-like eigenvalue elements (must be \(3\times N\)),

    • the number of matrix-like eigenvalue elements (must be \(9\times N\)),

    • an integer RotatesLike value denoting how the vector-like and matrix-like parts transform under application of a symmetry operation (see note below).

    • an integer LengthUnit value denoting what units the vector-like and matrix-like parts are in (see note below).

  • vectors_data (numpy.ndarray) – The eigenvector data to be stored in the grid. Same shape restrictions as values_data

  • vectors_elements – Like values_elements but for the eigenvectors

  • sort (logical (default False)) – Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

Note

Mapping of integers to RotatesLike values:

value

RotatesLike

0

vector

1

pseudovector

2

Gamma

Integer values outside of the mapped range (or missing) are replaced by 0.

Mapping of integers to LengthUnit values:

value

LengthUnit

0

none

1

angstrom

2

inverse_angstrom

3

real_lattice

4

reciprocal_lattice

Integer values outside of the mapped range (or missing) are replaced by 3.

  1. fill(self: brille._brille.BZMeshQdc, values_data: numpy.ndarray[numpy.float64], values_elements: numpy.ndarray[numpy.int32], values_weights: numpy.ndarray[numpy.float64], vectors_data: numpy.ndarray[numpy.complex128], vectors_elements: numpy.ndarray[numpy.int32], vectors_weights: numpy.ndarray[numpy.float64], sort: bool = False) -> None

Provide all data required for interpolation to the grid at once

Parameters:

  • values_data (numpy.ndarray) – The eigenvalue data to be stored in the grid. The first dimension must be equal in size to the number of grid-vertices. If two dimensional the second dimension is interpreted as all information for a single mode flattened and concatenated into (scalars, vectors, matrices) – in that order. If more than two dimensional, the second dimension indexes modes and higher dimensions will be flattened as if row ordered and must flatten into a concatenated list of (scalars, vectors, matrices). If the provided array can be interpreted as a contiguous row-ordered two dimensional array it will be used in place, otherwise a copy will be made.

  • values_elements (integer vector-like) – A multi-purpose vector containing, in order:

    • the number of scalar-like eigenvalue elements,

    • the number of vector-like eigenvalue elements (must be \(3\times N\)),

    • the number of matrix-like eigenvalue elements (must be \(9\times N\)),

    • an integer RotatesLike value denoting how the vector-like and matrix-like parts transform under application of a symmetry operation (see note below),

    • an integer LengthUnit value denoting what units the vector-like and matrix-like parts are in (see note below)

    • which scalar cost function should be used (see below),

    • which vector cost function should be used (see below).

    See the note below for the meaning of the last three values.

  • values_weights (float, vector-like) – The relative cost weights between scalar-, vector-, and matrix- like eigenvalue elements stored in the grid

  • vectors_data (numpy.ndarray) – The eigenvector data to be stored in the grid. Same shape restrictions as values_data

  • vectors_elements – Like values_elements but for the eigenvectors

  • vectors_weights (float, vector-like) – The relative cost weights between scalar-, vector-, and matrix- like eigenvector elements stored in the grid

  • sort (logical (default False)) – Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

Note

Mapping of integers to RotatesLike values:

value

RotatesLike

0

vector

1

pseudovector

2

Gamma

Mapping of integers to LengthUnit values:

value

LengthUnit

0

none

1

angstrom

2

inverse_angstrom

3

real_lattice

4

reciprocal_lattice

Integer values outside of the mapped range (or missing) are replaced by 3.

Mapping of integers to scalar cost function:

value

function(x,y)

0

magnitude(x-y)

Mapping of integers to vector cost function:

value

function(vec_x, vec_y)

0

sin(hermitian_angle(vec_x, vec_y))

1

vector_distance(vec_x, vec_y)

2

1 - vector_product(vec_x, vec_y)

3

vector_angle(vec_x, vec_y)

4

hermitian_angle(vec_x, vec_y)

Integer values outside of the mapped range (or missing) are replaced by 0.

static from_file(filename: str, entry: str = 'BZMeshQdc') → brille._brille.BZMeshQdc

Save the object to an HDF5 file

Parameters:

  • filename (str) – The full path specification for the file to read from

  • entry (str) – The group path, e.g., “my/cool/grid”, where to read from inside the file, with a default equal to the object Class name

Return type:

clsObj

ir_interpolate_at(self: brille._brille.BZMeshQdc, Q: numpy.ndarray[numpy.float64], useparallel: bool = False, threads: int = -1, do_not_move_points: bool = False) → tuple[numpy.ndarray[numpy.float64], numpy.ndarray[numpy.complex128]]

Perform linear interpolation of the stored data at irreducible equivalent points

The irreducible first Brillouin zone is the part of reciprocal space which is invariant under application of the integer translations and the pointgroup operations of a reciprocal space lattice. This method finds points equivalent to the input within the irreducible first Brillouin zone and then interpolates pre-stored information to provide an estimate at the found positions.

Parameters:

  • Q (numpy.ndarray) – A two dimensional array with Q.shape[1] == 3 containing the positions at which an interpolated result is required, expressed in units of the reciprocal lattice.

  • useparallel (bool, optional) – Whether a serial or parallel code should be utilised

  • threads (int, optional) – How many OpenMP workers should be utilised; if this value is less than one the environment variable OMP_NUM_THREADS will be used.

  • do_not_move_points (bool, optional) – If True the provided Q points must already lie within the first Brillouin zone. No check is made to verify this requirement and if any Q lie outside of the gridded volume out-of-bounds errors may result in bad data or runtime errors.

Returns:

The interpolated eigenvalues and eigenvectors at the equivalent irreducible first Brillouin zone points. The shape of each output will depend on the shape of the data provided to the fill() method. i If the filled eigenvalues were of shape [N_grid_points, N_modes, A, ..., B], the eigenvectors were of shape [N_grid_points, N_modes, C, ..., D], and the provided points of shape [N_Q_points, 3] then the output shapes will be [N_Q_points, N_modes, A, ..., B] and [N_Q_points, N_modes, C, ..., D] for the eigenvalues and eigenvectors, respectively.

Return type:

tuple

set_flags_weights(self: brille._brille.BZMeshQdc, values_flags: numpy.ndarray[numpy.int32], values_weights: numpy.ndarray[numpy.float64], vectors_flags: numpy.ndarray[numpy.int32], vectors_weights: numpy.ndarray[numpy.float64], sort: bool = False) → None

Set RotatesLike, ~brille._brille.LengthUnit and cost functions plus relative cost weights for the values and vectors stored in the object

Parameters:

  • values_flags (integer, vector-like) – One or more values indicating the RotatesLike value for the eigenvalues stored in the object, the ~brille._brille.LengthUnit value, plus which cost function to use when comparing stored eigenvalues at neighbouring grid points for scalar- and vector-like eigenvalues.

  • values_weights (float, vector-like) – The relative cost weights between scalar-, vector-, and matrix- like eigenvalue elements stored in the grid

  • vectors_flags (integer, vector-like) – One or more values indicating the RotatesLike value for the eigenvalues stored in the object, the ~brille._brille.LengthUnit value, plus which cost function to use when comparing stored eigenvectors at neighbouring grid points for scalar- and vector-like eigenvectors.

  • vectors_weights (float, vector-like) – The relative cost weights between scalar-, vector-, and matrix- like eigenvector elements stored in the grid

  • sort (bool, optional) – Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

Note

Mapping of integers to RotatesLike values:

value

RotatesLike

0

vector

1

pseudovector

2

Gamma

Mapping of integers to LengthUnit values:

value

LengthUnit

0

none

1

angstrom

2

inverse_angstrom

3

real_lattice

4

reciprocal_lattice

Mapping of integers to scalar cost function:

value

function(x,y)

0

magnitude(x-y)

Mapping of integers to vector cost function:

value

function(vec_x, vec_y)

0

sin(hermitian_angle(vec_x, vec_y))

1

vector_distance(vec_x, vec_y)

2

1 - vector_product(vec_x, vec_y)

3

vector_angle(vec_x, vec_y)

4

hermitian_angle(vec_x, vec_y)

Integer values outside of the mapped range (or missing) are replaced by 0.

sort(self: brille._brille.BZMeshQdc) → None
to_file(self: brille._brille.BZMeshQdc, filename: str, entry: str = 'BZMeshQdc', flags: str = 'ac') → bool

Save the object to an HDF5 file

Parameters:

  • filename (str) – The full path specification for the file to write into

  • entry (str) – The group path, e.g., “my/cool/grid”, where to write inside the file, with a default equal to the object Class name

  • flags (str) – The HDF5 permissions to use when opening the file. Default ‘a’ writes to an existing file – if entry exists in the file it is overwritten.

Note

Possible flags are:

flags

meaning

HDF equivalent

‘r’

read

H5F_ACC_RDONLY

‘x’

write, error if exists

H5F_ACC_EXCL

‘a’

write, append to file

H5F_ACC_RDWR

‘c’

write, error if exists

H5F_ACC_CREAT

‘t’

write, replace existing

H5F_ACC_TRUNC
Returns:

Indication of writing success.

Return type:

bool

property values

Return a shared view of the stored eigenvalues

property vectors

Return a shared view of the stored eigenvectors

Hierarchy

The BZNestQdc and its type-siblings implements a triangulated grid with multiple triangulations of the Brillouin Zone of increasingly finer maximum tetrahedron size; overlapping regions of these triangulations are identified and stored to simplify later finding the smallest tetrahedron containing a given point.

Starting from the coarsest ‘top’ layer of tetrahedra, a containing tetrahedron should be quick to locate. Then the list of overlapping next-finer layer tetrahedra can be used to locate the next containing tetrahedron. This process repeats until the finest layer tetrahedron containing the point is found. The total number of in-tetrahedron checks is then on the order of the sum of the average number of connected tetrahedra at each layer over the number of layers; which should be chosen to be smaller than the total number of tetrahedra at the finest layer.

Note

As implemented, the tetrahedra of two subsequent triangulations could have any overlapping relationship including one finer-tetrahedron intersecting with two (or more) coarser-tetrahedra. In practice it seems that the TetGen meshing algorithm always produces finer-tetrahedra which subdivide a coarser-tetrahedra, so that a finite-tree is formed between the layers of the nest. A class requiring this relationship should be able to extract memory and speed efficiencies which the current implementation sacrificed for greater relationsional flexibility.

If the \(i^\text{th}\) layer has tetrahedra which on average contain \(\left<m\right>_i\) overlapping number of tetrahedra in the \((i+1)^\text{th}\) layer, then the typical number of in-tetrahedra checks required to find the finest-tetrahedra containing any point is

\[N_\text{checks} \propto \sum_{i=1}^n \left< m \right>_i \]

and the finest layer contains

\[N_\text{tetrahedra}^n = \prod_{i=1}^n \left< m \right>_i \]

tetrahedra. As long as \(N_\text{checks} < N_\text{tetrahedra}^n\) this location method will be more efficient.

class brille._brille.BZNestQdd(*args, **kwargs)

Overloaded function.

  1. __init__(self: brille._brille.BZNestQdd, brillouin_zone: brille._brille.BrillouinZone, max_volume: float, max_branchings: int = 5) -> None

  2. __init__(self: brille._brille.BZNestQdd, brillouin_zone: brille._brille.BrillouinZone, number_density: int, max_branchings: int = 5) -> None

class brille._brille.BZNestQcc(*args, **kwargs)

Overloaded function.

  1. __init__(self: brille._brille.BZNestQcc, brillouin_zone: brille._brille.BrillouinZone, max_volume: float, max_branchings: int = 5) -> None

  2. __init__(self: brille._brille.BZNestQcc, brillouin_zone: brille._brille.BrillouinZone, number_density: int, max_branchings: int = 5) -> None

class brille._brille.BZNestQdc(*args, **kwargs)

Overloaded function.

  1. __init__(self: brille._brille.BZNestQdc, brillouin_zone: brille._brille.BrillouinZone, max_volume: float, max_branchings: int = 5) -> None

  2. __init__(self: brille._brille.BZNestQdc, brillouin_zone: brille._brille.BrillouinZone, number_density: int, max_branchings: int = 5) -> None

property bytes_per_point

Return the memory required per interpolation point result in bytes

fill(*args, **kwargs)

Overloaded function.

  1. fill(self: brille._brille.BZNestQdc, values_data: numpy.ndarray[numpy.float64], values_elements: numpy.ndarray[numpy.int32], vectors_data: numpy.ndarray[numpy.complex128], vectors_elements: numpy.ndarray[numpy.int32], sort: bool = False) -> None

Provide data required for interpolation to the grid without cost information.

Parameters:

  • values_data (numpy.ndarray) – The eigenvalue data to be stored in the grid. The first dimension must be equal in size to the number of grid-vertices. If two dimensional the second dimension is interpreted as all information for a single mode flattened and concatenated into (scalars, vectors, matrices) – in that order. If more than two dimensional, the second dimension indexes modes and higher dimensions will be flattened as if row ordered and must flatten into a concatenated list of (scalars, vectors, matrices). If the provided array can be interpreted as a contiguous row-ordered two dimensional array it will be used in place, otherwise a copy will be made.

  • values_elements (integer vector-like) – A multi-purpose vector containing, in order:

    • the number of scalar-like eigenvalue elements,

    • the number of vector-like eigenvalue elements (must be \(3\times N\)),

    • the number of matrix-like eigenvalue elements (must be \(9\times N\)),

    • an integer RotatesLike value denoting how the vector-like and matrix-like parts transform under application of a symmetry operation (see note below).

    • an integer LengthUnit value denoting what units the vector-like and matrix-like parts are in (see note below).

  • vectors_data (numpy.ndarray) – The eigenvector data to be stored in the grid. Same shape restrictions as values_data

  • vectors_elements – Like values_elements but for the eigenvectors

  • sort (logical (default False)) – Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

Note

Mapping of integers to RotatesLike values:

value

RotatesLike

0

vector

1

pseudovector

2

Gamma

Integer values outside of the mapped range (or missing) are replaced by 0.

Mapping of integers to LengthUnit values:

value

LengthUnit

0

none

1

angstrom

2

inverse_angstrom

3

real_lattice

4

reciprocal_lattice

Integer values outside of the mapped range (or missing) are replaced by 3.

  1. fill(self: brille._brille.BZNestQdc, values_data: numpy.ndarray[numpy.float64], values_elements: numpy.ndarray[numpy.int32], values_weights: numpy.ndarray[numpy.float64], vectors_data: numpy.ndarray[numpy.complex128], vectors_elements: numpy.ndarray[numpy.int32], vectors_weights: numpy.ndarray[numpy.float64], sort: bool = False) -> None

Provide all data required for interpolation to the grid at once

Parameters:

  • values_data (numpy.ndarray) – The eigenvalue data to be stored in the grid. The first dimension must be equal in size to the number of grid-vertices. If two dimensional the second dimension is interpreted as all information for a single mode flattened and concatenated into (scalars, vectors, matrices) – in that order. If more than two dimensional, the second dimension indexes modes and higher dimensions will be flattened as if row ordered and must flatten into a concatenated list of (scalars, vectors, matrices). If the provided array can be interpreted as a contiguous row-ordered two dimensional array it will be used in place, otherwise a copy will be made.

  • values_elements (integer vector-like) – A multi-purpose vector containing, in order:

    • the number of scalar-like eigenvalue elements,

    • the number of vector-like eigenvalue elements (must be \(3\times N\)),

    • the number of matrix-like eigenvalue elements (must be \(9\times N\)),

    • an integer RotatesLike value denoting how the vector-like and matrix-like parts transform under application of a symmetry operation (see note below),

    • an integer LengthUnit value denoting what units the vector-like and matrix-like parts are in (see note below)

    • which scalar cost function should be used (see below),

    • which vector cost function should be used (see below).

    See the note below for the meaning of the last three values.

  • values_weights (float, vector-like) – The relative cost weights between scalar-, vector-, and matrix- like eigenvalue elements stored in the grid

  • vectors_data (numpy.ndarray) – The eigenvector data to be stored in the grid. Same shape restrictions as values_data

  • vectors_elements – Like values_elements but for the eigenvectors

  • vectors_weights (float, vector-like) – The relative cost weights between scalar-, vector-, and matrix- like eigenvector elements stored in the grid

  • sort (logical (default False)) – Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

Note

Mapping of integers to RotatesLike values:

value

RotatesLike

0

vector

1

pseudovector

2

Gamma

Mapping of integers to LengthUnit values:

value

LengthUnit

0

none

1

angstrom

2

inverse_angstrom

3

real_lattice

4

reciprocal_lattice

Integer values outside of the mapped range (or missing) are replaced by 3.

Mapping of integers to scalar cost function:

value

function(x,y)

0

magnitude(x-y)

Mapping of integers to vector cost function:

value

function(vec_x, vec_y)

0

sin(hermitian_angle(vec_x, vec_y))

1

vector_distance(vec_x, vec_y)

2

1 - vector_product(vec_x, vec_y)

3

vector_angle(vec_x, vec_y)

4

hermitian_angle(vec_x, vec_y)

Integer values outside of the mapped range (or missing) are replaced by 0.

static from_file(filename: str, entry: str = 'BZNestQdc') → brille._brille.BZNestQdc

Save the object to an HDF5 file

Parameters:

  • filename (str) – The full path specification for the file to read from

  • entry (str) – The group path, e.g., “my/cool/grid”, where to read from inside the file, with a default equal to the object Class name

Return type:

clsObj

ir_interpolate_at(self: brille._brille.BZNestQdc, Q: numpy.ndarray[numpy.float64], useparallel: bool = False, threads: int = -1, do_not_move_points: bool = False) → tuple[numpy.ndarray[numpy.float64], numpy.ndarray[numpy.complex128]]

Perform linear interpolation of the stored data at irreducible equivalent points

The irreducible first Brillouin zone is the part of reciprocal space which is invariant under application of the integer translations and the pointgroup operations of a reciprocal space lattice. This method finds points equivalent to the input within the irreducible first Brillouin zone and then interpolates pre-stored information to provide an estimate at the found positions.

Parameters:

  • Q (numpy.ndarray) – A two dimensional array with Q.shape[1] == 3 containing the positions at which an interpolated result is required, expressed in units of the reciprocal lattice.

  • useparallel (bool, optional) – Whether a serial or parallel code should be utilised

  • threads (int, optional) – How many OpenMP workers should be utilised; if this value is less than one the environment variable OMP_NUM_THREADS will be used.

  • do_not_move_points (bool, optional) – If True the provided Q points must already lie within the first Brillouin zone. No check is made to verify this requirement and if any Q lie outside of the gridded volume out-of-bounds errors may result in bad data or runtime errors.

Returns:

The interpolated eigenvalues and eigenvectors at the equivalent irreducible first Brillouin zone points. The shape of each output will depend on the shape of the data provided to the fill() method. i If the filled eigenvalues were of shape [N_grid_points, N_modes, A, ..., B], the eigenvectors were of shape [N_grid_points, N_modes, C, ..., D], and the provided points of shape [N_Q_points, 3] then the output shapes will be [N_Q_points, N_modes, A, ..., B] and [N_Q_points, N_modes, C, ..., D] for the eigenvalues and eigenvectors, respectively.

Return type:

tuple

set_flags_weights(self: brille._brille.BZNestQdc, values_flags: numpy.ndarray[numpy.int32], values_weights: numpy.ndarray[numpy.float64], vectors_flags: numpy.ndarray[numpy.int32], vectors_weights: numpy.ndarray[numpy.float64], sort: bool = False) → None

Set RotatesLike, ~brille._brille.LengthUnit and cost functions plus relative cost weights for the values and vectors stored in the object

Parameters:

  • values_flags (integer, vector-like) – One or more values indicating the RotatesLike value for the eigenvalues stored in the object, the ~brille._brille.LengthUnit value, plus which cost function to use when comparing stored eigenvalues at neighbouring grid points for scalar- and vector-like eigenvalues.

  • values_weights (float, vector-like) – The relative cost weights between scalar-, vector-, and matrix- like eigenvalue elements stored in the grid

  • vectors_flags (integer, vector-like) – One or more values indicating the RotatesLike value for the eigenvalues stored in the object, the ~brille._brille.LengthUnit value, plus which cost function to use when comparing stored eigenvectors at neighbouring grid points for scalar- and vector-like eigenvectors.

  • vectors_weights (float, vector-like) – The relative cost weights between scalar-, vector-, and matrix- like eigenvector elements stored in the grid

  • sort (bool, optional) – Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

Note

Mapping of integers to RotatesLike values:

value

RotatesLike

0

vector

1

pseudovector

2

Gamma

Mapping of integers to LengthUnit values:

value

LengthUnit

0

none

1

angstrom

2

inverse_angstrom

3

real_lattice

4

reciprocal_lattice

Mapping of integers to scalar cost function:

value

function(x,y)

0

magnitude(x-y)

Mapping of integers to vector cost function:

value

function(vec_x, vec_y)

0

sin(hermitian_angle(vec_x, vec_y))

1

vector_distance(vec_x, vec_y)

2

1 - vector_product(vec_x, vec_y)

3

vector_angle(vec_x, vec_y)

4

hermitian_angle(vec_x, vec_y)

Integer values outside of the mapped range (or missing) are replaced by 0.

sort(self: brille._brille.BZNestQdc) → None
to_file(self: brille._brille.BZNestQdc, filename: str, entry: str = 'BZNestQdc', flags: str = 'ac') → bool

Save the object to an HDF5 file

Parameters:

  • filename (str) – The full path specification for the file to write into

  • entry (str) – The group path, e.g., “my/cool/grid”, where to write inside the file, with a default equal to the object Class name

  • flags (str) – The HDF5 permissions to use when opening the file. Default ‘a’ writes to an existing file – if entry exists in the file it is overwritten.

Note

Possible flags are:

flags

meaning

HDF equivalent

‘r’

read

H5F_ACC_RDONLY

‘x’

write, error if exists

H5F_ACC_EXCL

‘a’

write, append to file

H5F_ACC_RDWR

‘c’

write, error if exists

H5F_ACC_CREAT

‘t’

write, replace existing

H5F_ACC_TRUNC
Returns:

Indication of writing success.

Return type:

bool

property values

Return a shared view of the stored eigenvalues

property vectors

Return a shared view of the stored eigenvectors

Hybrid grids

A hybrid grid employs both a regular grid of parallelepipeds and, where the regular grid passes the Brillouin zone boundary, individually triangulated cells. This enables fast location of the cell containing any interpolation point and, if it is triangulated, subsequent fast location of the containing tetrahedron.

Figure made with TikZ

The three exposed hybrid grid implementations have the same set of methods and are:

class brille._brille.BZTrellisQdd(*args, **kwargs)

Overloaded function.

  1. __init__(self: brille._brille.BZTrellisQdd, brillouin_zone: brille._brille.BrillouinZone, node_volume_fraction: float = 0.1, always_triangulate: bool = False) -> None

  2. __init__(self: brille._brille.BZTrellisQdd, brillouin_zone: brille._brille.BrillouinZone, node_volume_fraction: float, always_triangulate: bool, approx_config: brille::approx_float::Config) -> None

class brille._brille.BZTrellisQcc(*args, **kwargs)

Overloaded function.

  1. __init__(self: brille._brille.BZTrellisQcc, brillouin_zone: brille._brille.BrillouinZone, node_volume_fraction: float = 0.1, always_triangulate: bool = False) -> None

  2. __init__(self: brille._brille.BZTrellisQcc, brillouin_zone: brille._brille.BrillouinZone, node_volume_fraction: float, always_triangulate: bool, approx_config: brille::approx_float::Config) -> None

class brille._brille.BZTrellisQdc(*args, **kwargs)

Overloaded function.

  1. __init__(self: brille._brille.BZTrellisQdc, brillouin_zone: brille._brille.BrillouinZone, node_volume_fraction: float = 0.1, always_triangulate: bool = False) -> None

  2. __init__(self: brille._brille.BZTrellisQdc, brillouin_zone: brille._brille.BrillouinZone, node_volume_fraction: float, always_triangulate: bool, approx_config: brille::approx_float::Config) -> None

all_node_types(self: brille._brille.BZTrellisQdc) → list[brille::NodeType]
property bytes_per_point

Return the memory required per interpolation point result in bytes

fill(*args, **kwargs)

Overloaded function.

  1. fill(self: brille._brille.BZTrellisQdc, values_data: numpy.ndarray[numpy.float64], values_elements: numpy.ndarray[numpy.int32], vectors_data: numpy.ndarray[numpy.complex128], vectors_elements: numpy.ndarray[numpy.int32], sort: bool = False) -> None

Provide data required for interpolation to the grid without cost information.

Parameters:

  • values_data (numpy.ndarray) – The eigenvalue data to be stored in the grid. The first dimension must be equal in size to the number of grid-vertices. If two dimensional the second dimension is interpreted as all information for a single mode flattened and concatenated into (scalars, vectors, matrices) – in that order. If more than two dimensional, the second dimension indexes modes and higher dimensions will be flattened as if row ordered and must flatten into a concatenated list of (scalars, vectors, matrices). If the provided array can be interpreted as a contiguous row-ordered two dimensional array it will be used in place, otherwise a copy will be made.

  • values_elements (integer vector-like) – A multi-purpose vector containing, in order:

    • the number of scalar-like eigenvalue elements,

    • the number of vector-like eigenvalue elements (must be \(3\times N\)),

    • the number of matrix-like eigenvalue elements (must be \(9\times N\)),

    • an integer RotatesLike value denoting how the vector-like and matrix-like parts transform under application of a symmetry operation (see note below).

    • an integer LengthUnit value denoting what units the vector-like and matrix-like parts are in (see note below).

  • vectors_data (numpy.ndarray) – The eigenvector data to be stored in the grid. Same shape restrictions as values_data

  • vectors_elements – Like values_elements but for the eigenvectors

  • sort (logical (default False)) – Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

Note

Mapping of integers to RotatesLike values:

value

RotatesLike

0

vector

1

pseudovector

2

Gamma

Integer values outside of the mapped range (or missing) are replaced by 0.

Mapping of integers to LengthUnit values:

value

LengthUnit

0

none

1

angstrom

2

inverse_angstrom

3

real_lattice

4

reciprocal_lattice

Integer values outside of the mapped range (or missing) are replaced by 3.

  1. fill(self: brille._brille.BZTrellisQdc, values_data: numpy.ndarray[numpy.float64], values_elements: numpy.ndarray[numpy.int32], values_weights: numpy.ndarray[numpy.float64], vectors_data: numpy.ndarray[numpy.complex128], vectors_elements: numpy.ndarray[numpy.int32], vectors_weights: numpy.ndarray[numpy.float64], sort: bool = False) -> None

Provide all data required for interpolation to the grid at once

Parameters:

  • values_data (numpy.ndarray) – The eigenvalue data to be stored in the grid. The first dimension must be equal in size to the number of grid-vertices. If two dimensional the second dimension is interpreted as all information for a single mode flattened and concatenated into (scalars, vectors, matrices) – in that order. If more than two dimensional, the second dimension indexes modes and higher dimensions will be flattened as if row ordered and must flatten into a concatenated list of (scalars, vectors, matrices). If the provided array can be interpreted as a contiguous row-ordered two dimensional array it will be used in place, otherwise a copy will be made.

  • values_elements (integer vector-like) – A multi-purpose vector containing, in order:

    • the number of scalar-like eigenvalue elements,

    • the number of vector-like eigenvalue elements (must be \(3\times N\)),

    • the number of matrix-like eigenvalue elements (must be \(9\times N\)),

    • an integer RotatesLike value denoting how the vector-like and matrix-like parts transform under application of a symmetry operation (see note below),

    • an integer LengthUnit value denoting what units the vector-like and matrix-like parts are in (see note below)

    • which scalar cost function should be used (see below),

    • which vector cost function should be used (see below).

    See the note below for the meaning of the last three values.

  • values_weights (float, vector-like) – The relative cost weights between scalar-, vector-, and matrix- like eigenvalue elements stored in the grid

  • vectors_data (numpy.ndarray) – The eigenvector data to be stored in the grid. Same shape restrictions as values_data

  • vectors_elements – Like values_elements but for the eigenvectors

  • vectors_weights (float, vector-like) – The relative cost weights between scalar-, vector-, and matrix- like eigenvector elements stored in the grid

  • sort (logical (default False)) – Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

Note

Mapping of integers to RotatesLike values:

value

RotatesLike

0

vector

1

pseudovector

2

Gamma

Mapping of integers to LengthUnit values:

value

LengthUnit

0

none

1

angstrom

2

inverse_angstrom

3

real_lattice

4

reciprocal_lattice

Integer values outside of the mapped range (or missing) are replaced by 3.

Mapping of integers to scalar cost function:

value

function(x,y)

0

magnitude(x-y)

Mapping of integers to vector cost function:

value

function(vec_x, vec_y)

0

sin(hermitian_angle(vec_x, vec_y))

1

vector_distance(vec_x, vec_y)

2

1 - vector_product(vec_x, vec_y)

3

vector_angle(vec_x, vec_y)

4

hermitian_angle(vec_x, vec_y)

Integer values outside of the mapped range (or missing) are replaced by 0.

static from_file(filename: str, entry: str = 'BZTrellisQdc') → brille._brille.BZTrellisQdc

Save the object to an HDF5 file

Parameters:

  • filename (str) – The full path specification for the file to read from

  • entry (str) – The group path, e.g., “my/cool/grid”, where to read from inside the file, with a default equal to the object Class name

Return type:

clsObj

interpolate_at(self: brille._brille.BZTrellisQdc, Q: numpy.ndarray[numpy.float64], useparallel: bool = False, threads: int = -1, do_not_move_points: bool = False) → tuple[numpy.ndarray[numpy.float64], numpy.ndarray[numpy.complex128]]

Perform linear interpolation of the stored data at equivalent points

The first Brillouin zone is the part of reciprocal space which is invariant under application of the integer translations of a reciprocal space lattice. This method finds points equivalent to the input within the first Brillouin zone and then interpolates pre-stored information to provide an estimate at the found positions.

Parameters:

  • Q (numpy.ndarray) – A two dimensional array with Q.shape[1] == 3 containing the positions at which an interpolated result is required, expressed in units of the reciprocal lattice.

  • useparallel (bool, optional) – Whether a serial or parallel code should be utilised

  • threads (int, optional) – How many OpenMP workers should be utilised; if this value is less than one the environment variable OMP_NUM_THREADS will be used.

  • do_not_move_points (bool, optional) – If True the provided Q points must already lie within the first Brillouin zone. No check is made to verify this requirement and if any Q lie outside of the gridded volume out-of-bounds errors may result in bad data or runtime errors.

Returns:

The interpolated eigenvalues and eigenvectors at the equivalent first Brillouin zone points. The shape of each output will depend on the shape of the data provided to the fill() method. If the filled eigenvalues were of shape [N_grid_points, N_modes, A, ..., B], the eigenvectors were of shape [N_grid_points, N_modes, C, ..., D], and the provided points of shape [N_Q_points, 3] then the output shapes will be [N_Q_points, N_modes, A, ..., B] and [N_Q_points, N_modes, C, ..., D] for the eigenvalues and eigenvectors, respectively.

Return type:

tuple

ir_interpolate_at(self: brille._brille.BZTrellisQdc, Q: numpy.ndarray[numpy.float64], useparallel: bool = False, threads: int = -1, do_not_move_points: bool = False) → tuple[numpy.ndarray[numpy.float64], numpy.ndarray[numpy.complex128]]

Perform linear interpolation of the stored data at irreducible equivalent points

The irreducible first Brillouin zone is the part of reciprocal space which is invariant under application of the integer translations and the pointgroup operations of a reciprocal space lattice. This method finds points equivalent to the input within the irreducible first Brillouin zone and then interpolates pre-stored information to provide an estimate at the found positions.

Parameters:

  • Q (numpy.ndarray) – A two dimensional array with Q.shape[1] == 3 containing the positions at which an interpolated result is required, expressed in units of the reciprocal lattice.

  • useparallel (bool, optional) – Whether a serial or parallel code should be utilised

  • threads (int, optional) – How many OpenMP workers should be utilised; if this value is less than one the environment variable OMP_NUM_THREADS will be used.

  • do_not_move_points (bool, optional) – If True the provided Q points must already lie within the first Brillouin zone. No check is made to verify this requirement and if any Q lie outside of the gridded volume out-of-bounds errors may result in bad data or runtime errors.

Returns:

The interpolated eigenvalues and eigenvectors at the equivalent irreducible first Brillouin zone points. The shape of each output will depend on the shape of the data provided to the fill() method. i If the filled eigenvalues were of shape [N_grid_points, N_modes, A, ..., B], the eigenvectors were of shape [N_grid_points, N_modes, C, ..., D], and the provided points of shape [N_Q_points, 3] then the output shapes will be [N_Q_points, N_modes, A, ..., B] and [N_Q_points, N_modes, C, ..., D] for the eigenvalues and eigenvectors, respectively.

Return type:

tuple

node_at(self: brille._brille.BZTrellisQdc, subscript: Annotated[list[int], FixedSize(3)]) → brille::polyhedron::Poly<double, brille::Array2>
node_at_type(self: brille._brille.BZTrellisQdc, subscript: Annotated[list[int], FixedSize(3)]) → brille::NodeType
node_containing(self: brille._brille.BZTrellisQdc, Q: numpy.ndarray[numpy.float64]) → brille::polyhedron::Poly<double, brille::Array2>
node_containing_type(self: brille._brille.BZTrellisQdc, Q: numpy.ndarray[numpy.float64]) → brille::NodeType
set_flags_weights(self: brille._brille.BZTrellisQdc, values_flags: numpy.ndarray[numpy.int32], values_weights: numpy.ndarray[numpy.float64], vectors_flags: numpy.ndarray[numpy.int32], vectors_weights: numpy.ndarray[numpy.float64], sort: bool = False) → None

Set RotatesLike, ~brille._brille.LengthUnit and cost functions plus relative cost weights for the values and vectors stored in the object

Parameters:

  • values_flags (integer, vector-like) – One or more values indicating the RotatesLike value for the eigenvalues stored in the object, the ~brille._brille.LengthUnit value, plus which cost function to use when comparing stored eigenvalues at neighbouring grid points for scalar- and vector-like eigenvalues.

  • values_weights (float, vector-like) – The relative cost weights between scalar-, vector-, and matrix- like eigenvalue elements stored in the grid

  • vectors_flags (integer, vector-like) – One or more values indicating the RotatesLike value for the eigenvalues stored in the object, the ~brille._brille.LengthUnit value, plus which cost function to use when comparing stored eigenvectors at neighbouring grid points for scalar- and vector-like eigenvectors.

  • vectors_weights (float, vector-like) – The relative cost weights between scalar-, vector-, and matrix- like eigenvector elements stored in the grid

  • sort (bool, optional) – Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

Note

Mapping of integers to RotatesLike values:

value

RotatesLike

0

vector

1

pseudovector

2

Gamma

Mapping of integers to LengthUnit values:

value

LengthUnit

0

none

1

angstrom

2

inverse_angstrom

3

real_lattice

4

reciprocal_lattice

Mapping of integers to scalar cost function:

value

function(x,y)

0

magnitude(x-y)

Mapping of integers to vector cost function:

value

function(vec_x, vec_y)

0

sin(hermitian_angle(vec_x, vec_y))

1

vector_distance(vec_x, vec_y)

2

1 - vector_product(vec_x, vec_y)

3

vector_angle(vec_x, vec_y)

4

hermitian_angle(vec_x, vec_y)

Integer values outside of the mapped range (or missing) are replaced by 0.

sort(self: brille._brille.BZTrellisQdc) → None
to_file(self: brille._brille.BZTrellisQdc, filename: str, entry: str = 'BZTrellisQdc', flags: str = 'ac') → bool

Save the object to an HDF5 file

Parameters:

  • filename (str) – The full path specification for the file to write into

  • entry (str) – The group path, e.g., “my/cool/grid”, where to write inside the file, with a default equal to the object Class name

  • flags (str) – The HDF5 permissions to use when opening the file. Default ‘a’ writes to an existing file – if entry exists in the file it is overwritten.

Note

Possible flags are:

flags

meaning

HDF equivalent

‘r’

read

H5F_ACC_RDONLY

‘x’

write, error if exists

H5F_ACC_EXCL

‘a’

write, append to file

H5F_ACC_RDWR

‘c’

write, error if exists

H5F_ACC_CREAT

‘t’

write, replace existing

H5F_ACC_TRUNC
Returns:

Indication of writing success.

Return type:

bool

property values

Return a shared view of the stored eigenvalues

property vectors

Return a shared view of the stored eigenvectors

Helper classes

class brille._brille.RotatesLike(self: brille._brille.RotatesLike, value: int)

Enumeration indicating how vector and matrix values transform

Members:

vector : Rotates like a vector

pseudovector : Rotates like a pseudovector

Gamma : Rotates like a (real space) phonon eigenvector