Utilities¶
The BrCrystal class¶
-
class
brilleu.crystal.BrCrystal(eucr, irreducible=True, hall=None, symmetry=None)¶ The
BrCrystalobject holds spacegroup and symmetry functionality (intended for internal use only).- Parameters
eucr (
euphonic.crystal.Crystal) – Or any object with fields cell_vectors, atom_r, and atom_typeirreducible (logical) – If True the BrillouinZone of this Crystal will be an irreducible Brillouin zone, otherwise it will be the first Brillouin zone.
hall (int or str, optional) – A valid Hall symbol or its number as defined in, e.g., Spglib dataset. Not all valid Hall symbols are assigned numbers, so the use of Hall numbers is discouraged.
symmetry (
brille.Symmetry, optional) – The symmetry operations (or their generators) for the spacegroup of the input crystal lattice
Note
The input symmetry information must correspond to the input lattice and no error checking is performed to confirm that this is the case.
-
get_BrillouinZone()¶ Determine and return the irreducible Brillouin zone
- Returns
- Return type
brille.BrillouinZone
-
get_Direct()¶ Return a Direct lattice object including the symmetry information
- Returns
- Return type
brille.Direct
-
get_atom_index()¶ Return the unique atom index for each atom in the basis
- Returns
A \(N_{\text{atom}} \times 3\) array of unsigned integers with each \(i < N_{\text{atom}}\)
- Return type
numpy.ndarray
-
get_atom_positions()¶ Return the atom positions in units of the basis vectors
- Returns
A \(N_{\text{atom}} \times 3\) array of positions
- Return type
numpy.ndarray
-
get_basis()¶ Return the basis as row-vectors of a matrix
- Returns
The basis vectors as the rows of a \(3 \times 3\) matrix
- Return type
numpy.ndarray
-
get_inverse_basis()¶ Return the inverse of the basis matrix
- Returns
A \(3 \times 3\) matrix
- Return type
numpy.ndarray
-
orthogonal_to_basis_eigenvectors(vecs)¶ Convert a set of eigenvector from orthogonal to basis coordinates
Some quantities are expressed in an orthogonal coordinate system, e.g. eigenvectors, but brille needs them expressed in the units of the basis vectors of the lattice which it uses.
We need to convert the eigenvector components from units of \((x,y,z)\) to \((a,b,c)\) via the inverse of the basis vectors. For column vectors \(\mathbf{x}\) and \(\mathbf{a}\) and basis matrix \(A\) ≡ self.get_basis()
\[\mathbf{x}^T = \mathbf{a}^T A \]which can be inverted to find \(\mathbf{a}\) from \(\mathbf{x}\)
\[\mathbf{a} = \left(A^{-1}\right)^T \mathbf{x} \]- Parameters
vecs (
numpy.ndarray) – \(N_{\text{pt}} \times N_{\text{br}} \times N_{\text{atom}} \times 3\) eigenvectors in the orthogonal coordinate system- Returns
eigenvectors expressed in the basis coordinate system
- Return type
numpy.ndarray
-
use_irreducible()¶ Return a logical boolean value based on the stored irreducible property
Read symmetry from CASTEP binary files¶
-
brilleu.castep.read_castep_bin_symmetry(filename)¶ Reads symmetry data from a .castep_bin or .check file and returns it in a dictionary
- Parameters
filename (str) – Full filename including path to castep_bin or check file
- Returns
data_dict – A dict with the following keys: ‘symmetry_operations’, ‘symmetry_disps’
- Return type
dict
Additional useful utilities¶
-
brilleu.utilities.align_eigenvectors(q_pts, e_vals, e_vecs, primary=None)¶ Align all eigenvectors such that \(\Im(\epsilon_p \cdot \hat{x}) = 0\) at each point.
Pick a smothly-varying local coordinate system based on \(\mathbf{q}\) for each point provided and apply an arbitrary phase such that the primary atom eigenvector is purely real and positive along the local \(\mathbf{x}\) direction. If a primary atom is not specified, pick one automatically which has the smallest mean displacement along \(\hat{p}\), and therefore is most likely to have a significant \(\left|\epsilon_p \cdot \hat{x}\right|\) for all \(\mathbf{q}\).
-
brilleu.utilities.broaden_modes(energy, omega, s_i, res_par_tem)¶ Compute S(Q,E) for a number of dispersion relations and intensities.
Given any number of dispersion relations, ω(Q), and the intensities of the modes which they represent, S(Q), plus energy-broadening information in the form of a function name plus parameters (if required), calculate S(Q,E) at the provided energy positions.
- Parameters
energy (
numpy.ndarray, \(N_{\text{point}}\)) – The observation energies at which to calculate the broadened intensitiesomega (
numpy.ndarray, \(N_{\text{mode}}\)) – The characteristic energies of the modes to be broadeneds_i (
numpy.ndarray, \(N_{\text{mode}}\)) – The integrated intensities of the modes to be broadenedres_par_tem (array-like) – The broadening function choice (str) and its paramters as detailed below
Note
Selecting the energy linewidth function:
Linewidth function
res_par_tem[0]
res_par_tem[1]
res_par_tem[2]
Simple Harmonic Oscillator
‘s’
fwhm
temperature
Gaussian
‘g’
fwhm
Lorentzian
‘l’
fwhm
Voigt
‘v’
g_fwhm
l_fwhm
- Returns
\(S(\mathbf{Q},E)\) for each mode at the observation energies
- Return type
\(N\)
numpy.ndarray, \(N_{\text{point}} \times N_{\text{mode}}\)
-
brilleu.utilities.degenerate_check(q_pts, e_vals, e_vecs, primary=None)¶ Check for degenerate eigenvalues and standardise their eigenvectors.
-
brilleu.utilities.delta(x_0, x_i, y_i)¶ Compute the δ-function.
y₀ = yᵢ×δ(x₀-xᵢ)
- Parameters
x_0 (
numpy.ndarray, \(N_{\text{point}}\)) – The observations at which to calculate intensitiesx_i (
numpy.ndarray, \(N_{\text{point}} \times N_{\text{mode}}\)) – The independent values of the modes to be broadenedy_i (
numpy.ndarray, \(N_{\text{point}} \times N_{\text{mode}}\)) – The dependent values of the modes to be broadened
- Returns
\(N_{\text{point}} \times N_{\text{mode}}\)
- Return type
numpy.ndarray
-
brilleu.utilities.fetchObjType(objtype, material, **kwds)¶ Fetch remote CASTEP binary file from the
brilleurepository- Parameters
objtype (class) – The output class, must have a static class.from_castep() method
material (str) – The basename of the CASTEP file, e.g, ‘NaCl’ for NaCl.castep_bin
**kwds – All keyword arguments are passed to the class.from_castep() constructor
- Returns
The requested class object constructed from the fetched file.
- Return type
class
-
brilleu.utilities.gaussian(x_0, x_i, y_i, fwhm)¶ Compute the normal distribution
- Parameters
x_0 (
numpy.ndarray, \(N_{\text{point}}\)) – The observations at which to calculate intensitiesx_i (
numpy.ndarray, \(N_{\text{point}} \times N_{\text{mode}}\)) – The independent values of the modes to be broadenedy_i (
numpy.ndarray, \(N_{\text{point}} \times N_{\text{mode}}\)) – The dependent values of the modes to be broadenedfwhm (float) – The full-width-at-half-maximum of the broadened modes
- Returns
\(N_{\text{point}} \times N_{\text{mode}}\)
- Return type
numpy.ndarray
-
brilleu.utilities.getObjType(objtype, material, **kwds)¶ Load a CASTEP binary file
If the file is not located in the brilleu module directory this function will attempt to obtain it from the brilleu repository over any available network connection.
- Parameters
objtype (class) – The output class, must have a static class.from_castep() method
material (str) – The basename of the CASTEP file, e.g, ‘NaCl’ for NaCl.castep_bin
**kwds – All keyword arguments are passed to the class.from_castep() constructor
- Returns
The requested class object constructed from the fetched file.
- Return type
class
-
brilleu.utilities.local_xyz(vec)¶ Return a local coordinate system based on the vector provided.
-
brilleu.utilities.lorentzian(x_0, x_i, y_i, fwhm)¶ Compute the Cauchy distribution
- Parameters
x_0 (
numpy.ndarray, \(N_{\text{point}}\)) – The observations at which to calculate intensitiesx_i (
numpy.ndarray, \(N_{\text{point}} \times N_{\text{mode}}\)) – The independent values of the modes to be broadenedy_i (
numpy.ndarray, \(N_{\text{point}} \times N_{\text{mode}}\)) – The dependent values of the modes to be broadenedfwhm (float) – The full-width-at-half-maximum of the broadened modes
- Returns
\(N_{\text{point}} \times N_{\text{mode}}\)
- Return type
numpy.ndarray
-
brilleu.utilities.sho(x_0, x_i, y_i, fwhm, t_k)¶ Compute the Simple-Harmonic-Oscillator distribution.
- Parameters
x_0 (
numpy.ndarray, \(N_{\text{point}}\)) – The observations at which to calculate intensitiesx_i (
numpy.ndarray, \(N_{\text{point}} \times N_{\text{mode}}\)) – The independent values of the modes to be broadenedy_i (
numpy.ndarray, \(N_{\text{point}} \times N_{\text{mode}}\)) – The dependent values of the modes to be broadenedfwhm (float) – The full-width-at-half-maximum of the broadened modes
t_k (float) – The temperature at which to calculate the broadening
- Returns
\(N_{\text{point}} \times N_{\text{mode}}\)
- Return type
numpy.ndarray
-
brilleu.utilities.voigt(x_0, x_i, y_i, params)¶ Compute the convolution of a normal and Cauchy distribution.
The Voigt function is the exact convolution of a normal distribution (a Gaussian) with full-width-at-half-max gᶠʷʰᵐ and a Cauchy distribution (a Lorentzian) with full-with-at-half-max lᶠʷʰᵐ. Computing the Voigt function exactly is computationally expensive, but it can be approximated to (almost always nearly) machine precision quickly using the Faddeeva distribution.
The Voigt distribution is the real part of the Faddeeva distribution, given an appropriate rescaling of the parameters.
- Parameters
x_0 (
numpy.ndarray, \(N_{\text{point}}\)) – The observations at which to calculate intensitiesx_i (
numpy.ndarray, \(N_{\text{point}} \times N_{\text{mode}}\)) – The independent values of the modes to be broadenedy_i (
numpy.ndarray, \(N_{\text{point}} \times N_{\text{mode}}\)) – The dependent values of the modes to be broadenedparams (float, array-like) – The full-width-at-half-maximum of the broadened modes. If scalar it is the Gaussian width and the Lorentzian width is zero; otherwise the Guassian then Lorentzian widths.
- Returns
\(N_{\text{point}} \times N_{\text{mode}}\)
- Return type
numpy.ndarray