StructureFactor¶
The StructureFactor object contains the structure factor at every q-point and mode, and optionally a temperature if temperature-dependent effects such as the Debye-Waller factor were used in the calculation.
Calculating Scattering Intensities¶
The structure factors can be used to create a \(S(Q, \omega)\) map
with Q on the x-axis and energy on the y-axis using
StructureFactor.calculate_sqw_map
(see docstring for algorithm details). This requires an array of energy bin
edges as a pint.Quantity
. Calculating the Bose population factor
is optional, but if calc_bose=True
the temperature stored in
StructureFactor is used. If there is no temperature in StructureFactor,
then it must be provided in the function arguments. This function returns a
generic Spectrum2D object.
from euphonic import ureg, StructureFactor
import numpy as np
sf = StructureFactor.from_json_file('sf_100K.json')
energy_bins = np.arange(-100, 101, 1)*ureg('meV')
sqw_map = sf.calculate_sqw_map(energy_bins, calc_bose=True)
Docstring¶
-
class
StructureFactor
(crystal, qpts, frequencies, structure_factors, weights=None, temperature=None)¶ Stores the structure factor calculated per q-point and per phonon mode
- Variables
crystal (Crystal) – Lattice and atom information
n_qpts (int) – Number of q-points in the object
qpts ((n_qpts, 3) float ndarray) – Q-point coordinates, in fractional coordinates of the reciprocal lattice
frequencies ((n_qpts, 3*crystal.n_atoms) float Quantity) – Phonon frequencies per q-point and mode
structure_factors ((n_qpts, 3*crystal.n_atoms) float Quantity) – Structure factor per q-point and mode
weights ((n_qpts,) float ndarray) – The weight for each q-point
temperature (float Quantity or None) – The temperature used to calculate any temperature-dependent parts of the structure factor (e.g. Debye-Waller, Bose population factor). None if no temperature-dependent effects have been applied
-
__init__
(crystal, qpts, frequencies, structure_factors, weights=None, temperature=None)¶ - Parameters
crystal (
Crystal
) – Lattice and atom informationqpts (
ndarray
) – Shape (n_qpts, 3) float ndarray. Q-point coordinates, in fractional coordinates of the reciprocal latticefrequencies (
Quantity
) – Shape (n_qpts, 3*crystal.n_atoms) float Quantity. Phonon frequencies per q-point and modestructure_factors (
Quantity
) – Shape (n_qpts, 3*crystal.n_atoms) float Quantity. Structure factor per q-point and modeweights (
Optional
[ndarray
]) – Shape (n_qpts,) float ndarray. The weight for each q-point. If None, equal weights are assumedtemperature (
Optional
[Quantity
]) – Scalar float Quantity. The temperature used to calculate any temperature-dependent parts of the structure factor (e.g. Debye-Waller, Bose population factor). None if no temperature-dependent effects have been applied
-
calculate_1d_average
(e_bins, calc_bose=True, temperature=None, weights=None)¶ Bin structure factor in energy, flattening q to produce 1D spectrum
Bose population factor may be applied. The main purpose of this function is to produce a powder-averaged spectrum.
- Parameters
e_bins (
Quantity
) – Shape (n_e_bins + 1,) float Quantity. The energy bin edgescalc_bose (
bool
) – Whether to calculate and apply the Bose population factortemperature (
Optional
[Quantity
]) – Scalar float Quantity. The temperature to use to calculate the Bose factor. Is only required if StructureFactor.temperature = None, otherwise the temperature stored in StructureFactor will be usedweights (
Optional
[ndarray
]) – Dimensionless weights to be applied in averaging, the same length as qpts. If no weights are provided the weights contained in StructureFactor are used. For details of how this argument is interpreted see docs fornumpy.average()
- Return type
- Returns
s_w – 1-D neutron scattering spectrum, averaged over all sampled q-points
-
calculate_sqw_map
(e_bins, calc_bose=True, temperature=None)¶ Bin the structure factor in energy and apply the Bose population factor to produce a a S(Q,w) map
- Parameters
e_bins (
Quantity
) – Shape (n_e_bins + 1,) float Quantity. The energy bin edgescalc_bose (
bool
) – Whether to calculate and apply the Bose population factortemperature (
Optional
[Quantity
]) – The temperature to use to calculate the Bose factor. Is only required if StructureFactor.temperature = None, otherwise the temperature stored in StructureFactor will be used
- Return type
- Returns
sqw_map – A spectrum containing the q-point bins on the x-axis, energy bins on the y-axis and scattering intensities on the z-axis
- Raises
ValueError – If a temperature is provided and isn’t consistent with the temperature in the StructureFactor object
Notes
StructureFactor.structure_factors is defined as the mode-resolved \(S(Q, \omega_{q\nu})\) per atom of sample. To create an \(S(Q,\omega)\) map, it is binned in \(\omega\) and the Bose factor is applied 1:
\[S(Q, \omega) = S(Q, \omega_{q\nu}) \ (n_\nu+\frac{1}{2}\pm\frac{1}{2}) \ \delta(\omega\mp\omega_{q\nu})\]\(n_\nu\) is the Bose-Einstein distribution:
\[n_\nu = \frac{1}{e^{\frac{\omega_{q\nu}}{k_{B}T}} - 1}\]- 1
M.T. Dove, Structure and Dynamics, Oxford University Press, Oxford, 2003, 225-226
-
to_dict
()¶ Convert to a dictionary. See StructureFactor.from_dict for details on keys/values
- Return type
Dict
[str
,Any
]
-
calculate_dos
(dos_bins, mode_widths=None, mode_widths_min=<Quantity(0.01, 'millielectron_volt')>)¶ Calculates a density of states
- Parameters
dos_bins (
Quantity
) – Shape (n_e_bins + 1,) float Quantity in energy units. The energy bin edges to use for calculating the DOSmode_widths (
Optional
[Quantity
]) – Shape (n_qpts, n_branches) float Quantity in energy units. The broadening width for each mode at each q-point, for adaptive broadeningmode_widths_min (
Quantity
) – Scalar float Quantity in energy units. Sets a lower limit on the mode widths, as mode widths of zero will result in infinitely sharp peaks
- Return type
- Returns
dos – A spectrum containing the energy bins on the x-axis and dos on the y-axis
-
calculate_dos_map
(dos_bins, mode_widths=None, mode_widths_min=<Quantity(0.01, 'millielectron_volt')>)¶ Produces a bandstructure-like plot, using the DOS at each q-point
- Parameters
dos_bins (
Quantity
) – Shape (n_e_bins + 1,) float Quantity in energy units. The energy bin edges to use for calculating the DOSmode_widths (
Optional
[Quantity
]) – Shape (n_qpts, n_branches) float Quantity in energy units. The broadening width for each mode at each q-point, for adaptive broadeningmode_widths_min (
Quantity
) – Scalar float Quantity in energy units. Sets a lower limit on the mode widths, as mode widths of zero will result in infinitely sharp peaks
- Return type
- Returns
dos_map – A 2D spectrum containing the q-point bins on the x-axis, energy bins on the y-axis and DOS on the z-axis
-
classmethod
from_json_file
(filename)¶ Read from a JSON file. See from_dict for required fields
- Parameters
filename (
str
) – The file to read from- Return type
~T
-
get_dispersion
()¶ Creates a set of 1-D bands from mode data
Bands follow the same q-point order as in the qpts array, with x-axis spacing corresponding to the absolute distances between q-points. Discontinuities will appear as large jumps on the x-axis.
- Return type
- Returns
dispersion – A sequence of mode bands with a common x-axis
-
to_json_file
(filename)¶ Write to a JSON file. JSON fields are equivalent to from_dict keys
- Parameters
filename (
str
) – Name of the JSON file to write to- Return type
None
-
to_qpoint_frequencies
()¶ Create a QpointFrequencies object
- Return type
-
classmethod
from_dict
(d)¶ Convert a dictionary to a StructureFactor object
- Parameters
d (dict) –
A dictionary with the following keys/values:
’crystal’: dict, see Crystal.from_dict
’qpts’: (n_qpts, 3) float ndarray
’frequencies’: (n_qpts, 3*crystal.n_atoms) float ndarray
’frequencies_unit’: str
’structure_factors’: (n_qpts, 3*crystal.n_atoms) float ndarray
’structure_factors_unit’: str
There are also the following optional keys:
’weights’: (n_qpts,) float ndarray
’temperature’: float
’temperature_unit’: str
- Return type
~T