Utilities

Reference data

Reference data is stored as JSON files and accessed using euphonic.util.get_reference_data(). As well as inbuilt data sets (e.g. "Sears1992"), user files may be specified. For examples of the data format, see the documentation of that function or take a look in the Euphonic source repository. The key point is that each “collection” file should contain a dictionary with a "physical_properties" key corresponding to another dictionary of reference data. The units should be specified with the special key __units__; this will automatically be used to wrap the data to pint.Quantity when accessed.

euphonic.util module

comma_join(x, /)

Shorthand to join objects as strings with commas.

Parameters:: x (Sequence[Any]) – Entities to join.

Examples

>>> from euphonic.util import comma_join
>>> comma_join((None, "a", 1))
'None, a, 1'

dedent_and_fill(text)

Clean up indented multiline string for display to user.

Remove leading/trailing newline (So ‘’’ can be placed freely.)

Remove indentation

Preserve any paragraph breaks (i.e. \n\n)

Wrap other newlines to default textwrap line width (70 characters)

Parameters:: text (str) – Multiline string with convenient linebreaks for source code display
Returns:: text – String for display to user via print() or Exception handling
Return type:: str

format_error(summary, *, reason='', fix)

Format errors to standard form.

Parameters:

summary (str) – Summary of what went wrong, should not exceed 80 characters.
reason (str, optional) – Extended summary detailing the cause of the issue.
fix (str) – Suggested remedy for issue.

Returns:

str – Formatted error message.

Return type:

str

direction_changed(qpts, tolerance=5e-06)

Determines whether the q-direction has changed between each pair of q-points

Parameters:

qpts (ndarray) – Shape (n_qpts, 3) float ndarray. The q-points to use
tolerance (float) – The minimum difference between the dot product and magnitude of both vectors multiplied together for each pair of direction vectors required for the direction to have changed

Returns:

has_direction_changed – Shape (n_qpts - 2,) bool ndarray. Indicates whether the direction vector has changed between each pair of q-points

Return type:

ndarray

is_gamma(qpt)

Determines whether the given point(s) are gamma points

Parameters:

qpts – Shape (3,) or (N, 3) float ndarray. The q-point or q-points
qpt (ndarray)

Returns:

isgamma – bool or shape (N,) bool ndarray. Whether the input q-points(s) are gamma points. Returns a scalar if only 1 q-point is provided

Return type:

bool | ndarray

mp_grid(grid)

Returns the q-points on a MxNxL Monkhorst-Pack grid specified by grid

Parameters:: grid (tuple[int, int, int]) – The number of points in each direction
Returns:: qgrid – Shape (M*N*L, 3) float ndarray. Q-points on an MP grid
Return type:: ndarray

get_all_origins(max_xyz, min_xyz=(0, 0, 0), step=1)

Given the max/min number of cells in each direction, get a list of all possible cell origins

Parameters:

max_xyz (tuple[int, int, int]) – The number of cells to count to in each direction
min_xyz (tuple[int, int, int]) – The cell number to count from in each direction
step (int) – The step between cells

Returns:

origins – Shape (prod(max_xyz - min_xyz)/step, 3) int ndarray. The cell origins

Return type:

ndarray

get_qpoint_labels(qpts, cell=None)

Gets q-point labels (e.g. GAMMA, X, L) for the q-points at which the path through reciprocal space changes direction, or where a point appears twice in succession.

Parameters:

qpts (ndarray) – Shape (n_qpts, 3) float ndarray. The q-points to get labels for
cell (tuple[list[list[float]], list[list[float]], list[int]] | None) – The cell structure as defined by spglib. Can be obtained by Crystal.to_spglib_cell. If not provided, the labels will be generic e.g. ‘1/3 1/2 0’ rather than high-symmetry point labels

Returns:

x_tick_labels – Tick labels and the q-point indices that they apply to

Return type:

list[tuple[int, str]]

mode_gradients_to_widths(mode_gradients, cell_vectors)

Converts either scalar or vector mode gradients (units energy/(length^-1)) to an estimate of the mode widths (units energy). If vector mode gradients are supplied, they will first be converted to scalar gradients by taking the Frobenius norm (using np.linalg.norm). The conversion to mode widths uses the cell volume and number of q-points to estimate the q-spacing. Note that the number of q-points is determined by the size of mode_gradients, so is not likely to give accurate widths if the q-points have been symmetry reduced.

Parameters:

mode_gradients (Quantity) – Shape (n_qpts, n_modes) float Quantity if using scalar mode gradients, shape (n_qpts, n_modes, 3) float Quantity if using vector mode gradients
cell_vectors (Quantity) – Shape (3, 3) float Quantity. The cell vectors

Return type:

Quantity

convert_fc_phases(force_constants, atom_r, sc_atom_r, uc_to_sc_atom_idx, sc_to_uc_atom_idx, sc_matrix, cell_origins_tol=1e-05)

Convert from a force constants matrix which uses the atom coordinates as r in the e^-iq.r phase (Phonopy-like), to a matrix which uses the cell origin coordinates as r in the e^-iq.r phase (Euphonic, CASTEP-like). Also changes the shape of the matrix to be compatible with Euphonic.

Parameters:

force_constants (ndarray) – Shape (n_atoms, n_cells*n_atoms, 3, 3) or (n_cells*n_atoms, n_cells*n_atoms, 3, 3) float ndarray with phases based on the atom coordinate. n_atoms is the number of atoms in the unit cell, n_cells is the number of unit cells in the supercell
atom_r (ndarray) – Shape (n_atoms, 3) float ndarray. The coordinates of the atoms in the unit cell in fractional coordinates of the unit cell vectors
sc_atom_r (ndarray) – Shape (n_atoms_in_sc, 3) float ndarray. The coordinates of the atoms in the supercell in fractional coordinates of the unit cell vectors. n_atoms_in_sc is the number of atoms in the supercell
uc_to_sc_atom_idx (ndarray) – Shape (n_atoms,) int ndarray. For each atom in the unit cell, the index of that atom in the supercell
sc_to_uc_atom_idx (ndarray) – Shape (n_atoms_in_sc,) int ndarray. For each atom in the supercell, the index of the equivalent atom in the unit cell
sc_matrix (ndarray) – Shape (3, 3) int ndarray. The transformation matrix to convert from the unit cell vectors to the supercell vectors
cell_origins_tol (float) – The calculated cell origins for each atom should be integer values. This defines the tolerance as above which a value is considered non-integer, which may indicate an issue with the input and will raise a RuntimeError.

Returns:

fc_converted – Shape (n_cells, 3*n_atoms, 3*n_atoms) float ndarray. The force constants matrix with a phase and shape compatible with Euphonic
cell_origins – Shape (n_cells_in_sc, 3) int ndarray. The origin coordinates of each unit cell within the supercell, in units of the unit cell vectors

Return type:

tuple[ndarray, ndarray]

spglib_new_errors()

Opt-in to new spglib error system if available

This also suppresses a pesky deprecation warning, spglib 2.7 REQUIRES that OLD_ERROR_HANDLING is set one way or the other. That isn’t a very nice thing for our downstream users to deal with, so we transparently tweak it for as little time as possible.