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

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

Return type

ndarray

Returns

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

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
Return type: Union[bool, 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

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
Return type: ndarray
Returns: qgrid – Shape (M*N*L, 3) float ndarray. Q-points on an MP grid

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

Return type

ndarray

Returns

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

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 (Optional[Tuple[List[List[float]], List[List[float]], List[int]]]) – 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

Return type

List[Tuple[int, str]]

Returns

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

get_reference_data(collection='Sears1992', physical_property='coherent_scattering_length')

Get physical data as a dict of (possibly-complex) floats from reference data.

Each “collection” refers to a JSON file which may contain any set of properties, indexed by physical_property.

Properties are stored in JSON files, encoding a single dictionary with the structure:

{"metadata1": "metadata1 text", "metadata2": ...,
 "physical_properties": {"property1": {"__units__": "unit_str",
                                       "H": H_property1_value,
                                       "He": He_property1_value,
                                       "Li": {"__complex__": true,
                                              "real": Li_property1_real,
                                              "imag": Li_property1_imag},
                                       "Nh": None,
                                       ...},
                         "property2": ...}}

Parameters

collection (str) – Identifier of data file; this may be an inbuilt data set (“Sears1992” or “BlueBook”) or a path to a JSON file (e.g. “./my_custom_data.json”).
physical_property (str) – The name of the property for which data should be extracted. This must match an entry of “physical_properties” in the data file.

Return type

Dict[str, Quantity]

Returns

Dict[str, Quantity] – Requested data as a dict with string keys and (possibly-complex) float Quantity values. String or None items of the original data file will be omitted.

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.

Return type

Tuple[ndarray, ndarray]

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