Grids¶

Load an object from an HDF5 file

Parameters:

• filename (str) –

  The full path specification for the file to read from

• entry (str, default: 'BZMeshQdc' ) –

  The group path, e.g., "my/cool/grid", where to read from inside the file, with a default equal to the object Class name

Returns:

• clsObj –

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

.. Note .. ---- .. This method should probably be followed by set_cost_info prior to .. any attempt to interpolate the data in the grid.

Parameters:

• values_data ([`numpy.ndarray`][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 (ndarray[int32]) –

  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`][numpy.ndarray]) –

  The eigenvector data to be stored in the grid. Same shape restrictions as values_data

• vectors_elements (ndarray[int32]) –

  Like values_elements but for the eigenvectors

• sort (logical (default ``False``), default: False ) –

  Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

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`][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, default: False ) –

  Whether a serial or parallel code should be utilised

• threads (int, default: -1 ) –

  How many parallel threads should be utilised; if this value is less than one, the BRILLE_NUM_THREADS environment variable sets the number, or one thread per logical core is used if it is not set.

• do_not_move_points (bool, default: False ) –

  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:

• tuple –

  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.

Refine the mesh by bisecting tetrahedra; existing vertices keep their indices and data.

Parameters:

• where (Any, default: None ) –

  As for refinement_points, which gives the points this adds.

• resolution (Any, default: None ) –

  As for refinement_points, which gives the points this adds.

• points_per_resolution (Any, default: None ) –

  As for refinement_points, which gives the points this adds.

• values (ndarray, default: None ) –

  If the mesh holds data (after fill), the data for the new vertices, laid out per point as the filled data and for exactly the points refinement_points returns, in that order. Not allowed before the mesh is filled.

• vectors (ndarray, default: None ) –

  If the mesh holds data (after fill), the data for the new vertices, laid out per point as the filled data and for exactly the points refinement_points returns, in that order. Not allowed before the mesh is filled.

Returns:

• ndarray –

  The new vertices, shape (N, 3), in relative lattice units, appended to rlu in this order.

The points that refine would add, without changing the mesh.

Evaluate your model at these points and compare with ir_interpolate_at there to decide whether refining is worth it; then pass the model's values to refine with the same arguments.

Parameters:

• where (None, bool array or int array, default: None ) –

  The tetrahedra to split: all of them (None), those where a boolean mask with one entry per tetrahedron is true, or those with the given indices. Neighbouring tetrahedra are split as needed to keep the mesh conforming, and split edges on the zone boundary are split with their symmetry equivalents, so that equivalent zone faces keep matching.

• resolution (float, default: None ) –

  The resolution limit, in inverse Angstrom. No edge is split to below resolution / points_per_resolution: a tetrahedron whose longest edge is at most twice that is left whole.

• points_per_resolution (float, optional (default: 2), default: 2.0 ) –

  How finely to resolve resolution.

Returns:

• ndarray –

  The new vertices, shape (N, 3), in relative lattice units like rlu. refine appends them to the vertices in this order.

Free the memory refinement holds between refinements.

After refine (or refinement_points) the mesh keeps the triangulation refinement works on, several times the memory of the mesh itself. This frees it. The mesh is unchanged and can still be refined: the triangulation is rebuilt when next needed, which costs a build of the mesh plus a replay of the refinements made so far.

Set RotatesLike, 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, default: False ) –

  Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

Choose when interpolated eigenvectors are scaled to unit norm

Linear interpolation between unit eigenvectors gives vectors shorter than one wherever neighbouring eigenvectors differ, so structure factors computed from them come out too small. Normalization scales each interpolated branch \(v\) to \(v/\sqrt{|\langle v|M|v\rangle|}\).

By default it is automatic: eigenvectors stored in Cartesian units (LengthUnit angstrom or inverse_angstrom, as Euphonic stores them) are normalized, and those in lattice units, whose length depends on the lattice, are not. The choice survives fill and saving to HDF5.

Parameters:

• normalize (bool or None, default: True ) –

  True always normalizes, and raises a RuntimeError for eigenvectors in lattice units; False never does; None restores the automatic default.

• metric ((float, vector - like), default: None ) –

  A diagonal metric \(M\), one weight per element of a branch (for phonons, \(3N\)). The default is the identity, the ordinary norm. For Bogoliubov (spin-wave) vectors use \(\eta=\mathrm{diag}(1,\ldots,1,-1,\ldots,-1)\); the sign of \(\langle v|\eta|v\rangle\) is kept.

Save the object to an HDF5 file

Parameters:

• filename (str) –

  The full path specification for the file to write into

• entry (str, default: 'BZMeshQdc' ) –

  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, default: 'ac' ) –

  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.

Returns:

• bool –

  Indication of writing success.

Load an object from an HDF5 file

Parameters:

• filename (str) –

  The full path specification for the file to read from

• entry (str, default: 'BZTrellisQdc' ) –

  The group path, e.g., "my/cool/grid", where to read from inside the file, with a default equal to the object Class name

Returns:

• clsObj –

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

.. Note .. ---- .. This method should probably be followed by set_cost_info prior to .. any attempt to interpolate the data in the grid.

Parameters:

• values_data ([`numpy.ndarray`][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 (ndarray[int32]) –

  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`][numpy.ndarray]) –

  The eigenvector data to be stored in the grid. Same shape restrictions as values_data

• vectors_elements (ndarray[int32]) –

  Like values_elements but for the eigenvectors

• sort (logical (default ``False``), default: False ) –

  Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

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`][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, default: False ) –

  Whether a serial or parallel code should be utilised

• threads (int, default: -1 ) –

  How many parallel threads should be utilised; if this value is less than one, the BRILLE_NUM_THREADS environment variable sets the number, or one thread per logical core is used if it is not set.

• do_not_move_points (bool, default: False ) –

  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:

• tuple –

  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.

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`][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, default: False ) –

  Whether a serial or parallel code should be utilised

• threads (int, default: -1 ) –

  How many parallel threads should be utilised; if this value is less than one, the BRILLE_NUM_THREADS environment variable sets the number, or one thread per logical core is used if it is not set.

• do_not_move_points (bool, default: False ) –

  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:

• tuple –

  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.

Set RotatesLike, 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, default: False ) –

  Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

Choose when interpolated eigenvectors are scaled to unit norm

Linear interpolation between unit eigenvectors gives vectors shorter than one wherever neighbouring eigenvectors differ, so structure factors computed from them come out too small. Normalization scales each interpolated branch \(v\) to \(v/\sqrt{|\langle v|M|v\rangle|}\).

By default it is automatic: eigenvectors stored in Cartesian units (LengthUnit angstrom or inverse_angstrom, as Euphonic stores them) are normalized, and those in lattice units, whose length depends on the lattice, are not. The choice survives fill and saving to HDF5.

Parameters:

• normalize (bool or None, default: True ) –

  True always normalizes, and raises a RuntimeError for eigenvectors in lattice units; False never does; None restores the automatic default.

• metric ((float, vector - like), default: None ) –

  A diagonal metric \(M\), one weight per element of a branch (for phonons, \(3N\)). The default is the identity, the ordinary norm. For Bogoliubov (spin-wave) vectors use \(\eta=\mathrm{diag}(1,\ldots,1,-1,\ldots,-1)\); the sign of \(\langle v|\eta|v\rangle\) is kept.

Save the object to an HDF5 file

Parameters:

• filename (str) –

  The full path specification for the file to write into

• entry (str, default: 'BZTrellisQdc' ) –

  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, default: 'ac' ) –

  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.

Returns:

• bool –

  Indication of writing success.

Load an object from an HDF5 file

Parameters:

• filename (str) –

  The full path specification for the file to read from

• entry (str, default: 'BZNestQdc' ) –

  The group path, e.g., "my/cool/grid", where to read from inside the file, with a default equal to the object Class name

Returns:

• clsObj –

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

.. Note .. ---- .. This method should probably be followed by set_cost_info prior to .. any attempt to interpolate the data in the grid.

Parameters:

• values_data ([`numpy.ndarray`][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 (ndarray[int32]) –

  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`][numpy.ndarray]) –

  The eigenvector data to be stored in the grid. Same shape restrictions as values_data

• vectors_elements (ndarray[int32]) –

  Like values_elements but for the eigenvectors

• sort (logical (default ``False``), default: False ) –

  Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

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`][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, default: False ) –

  Whether a serial or parallel code should be utilised

• threads (int, default: -1 ) –

  How many parallel threads should be utilised; if this value is less than one, the BRILLE_NUM_THREADS environment variable sets the number, or one thread per logical core is used if it is not set.

• do_not_move_points (bool, default: False ) –

  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:

• tuple –

  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.

Set RotatesLike, 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, default: False ) –

  Whether the equivalent-mode permutations should be (re)determined following the update to the flags and weights.

Choose when interpolated eigenvectors are scaled to unit norm

Linear interpolation between unit eigenvectors gives vectors shorter than one wherever neighbouring eigenvectors differ, so structure factors computed from them come out too small. Normalization scales each interpolated branch \(v\) to \(v/\sqrt{|\langle v|M|v\rangle|}\).

By default it is automatic: eigenvectors stored in Cartesian units (LengthUnit angstrom or inverse_angstrom, as Euphonic stores them) are normalized, and those in lattice units, whose length depends on the lattice, are not. The choice survives fill and saving to HDF5.

Parameters:

• normalize (bool or None, default: True ) –

  True always normalizes, and raises a RuntimeError for eigenvectors in lattice units; False never does; None restores the automatic default.

• metric ((float, vector - like), default: None ) –

  A diagonal metric \(M\), one weight per element of a branch (for phonons, \(3N\)). The default is the identity, the ordinary norm. For Bogoliubov (spin-wave) vectors use \(\eta=\mathrm{diag}(1,\ldots,1,-1,\ldots,-1)\); the sign of \(\langle v|\eta|v\rangle\) is kept.

Save the object to an HDF5 file

Parameters:

• filename (str) –

  The full path specification for the file to write into

• entry (str, default: 'BZNestQdc' ) –

  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, default: 'ac' ) –

  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.

Returns:

• bool –

  Indication of writing success.