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 usetolerance (
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 directionmin_xyz (
Tuple
[int
,int
,int
]) – The cell number to count from in each directionstep (
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
- Parameters
qpts (
ndarray
) – Shape (n_qpts, 3) float ndarray. The q-points to get labels forcell (
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 gradientscell_vectors (
Quantity
) – Shape (3, 3) float Quantity. The cell vectors
- Return type
Quantity