Powder averaging

Functions for averaging spectra in spherical q bins

sample_sphere_dos(fc, mod_q, *, sampling='golden', npts=1000, jitter=False, rng=Generator(PCG64) at 0x74F13DC26180, energy_bins=None, **calc_modes_args)

Calculate phonon DOS with QpointFrequencies.calculate_dos, sampling over a sphere of constant |q|

Parameters:

fc (ForceConstants) – Force constant data for system
mod_q (Quantity) – radius of sphere from which vector q samples are taken (in units of inverse length; usually 1/angstrom).
sampling (Literal['golden', 'sphere-projected-grid', 'spherical-polar-grid', 'spherical-polar-improved', 'random-sphere']) –
Sphere-sampling scheme. (Case-insensitive) options are:
- ’golden’:
  Fibonnaci-like sampling that steps regularly along one spherical coordinate while making irrational steps in the other
- ’sphere-projected-grid’:
  Regular 2-D square mesh projected onto sphere. npts will be distributed as evenly as possible (i.e. using twice as many ‘longitude’ as ‘lattitude’ lines), rounding up if necessary.
- ’spherical-polar-grid’:
  Mesh over regular subdivisions in spherical polar coordinates. npts will be rounded up as necessary in the same scheme as for sphere-projected-grid. ‘Latitude’ lines are evenly-spaced in z
- ’spherical-polar-improved’:
  npts distributed as regularly as possible using spherical polar coordinates: ‘latitude’ lines are evenly-spaced in z and points are distributed among these rings to obtain most even spacing possible.
- ’random-sphere’:
  Points are distributed randomly in unit square and projected onto sphere.
npts (int) – Number of samples. Note that some sampling methods have constraints on valid values and will round up as appropriate.
jitter (bool) – For non-random sampling schemes, apply an additional random displacement to each point.
rng (Generator | RandomState) – Numpy random Generator for random sampling and jitter
energy_bins (Quantity | None) – Preferred energy bin edges. If not provided, will setup 1000 bins (1001 bin edges) from 0 to 1.05 * [max energy]
**calc_modes_args – other keyword arguments (e.g. ‘use_c’) will be passed to ForceConstants.calculate_qpoint_phonon_modes()

Returns:

Spectrum1D

Return type:

Spectrum1D

sample_sphere_pdos(fc, mod_q, *, sampling='golden', npts=1000, jitter=False, rng=Generator(PCG64) at 0x74F13DC26180, energy_bins=None, weighting=None, cross_sections='BlueBook', **calc_modes_args)

Calculate phonon PDOS with QpointPhononModes.calculate_pdos, sampling over a sphere of constant |q|

Parameters:

fc (ForceConstants) – Force constant data for system
mod_q (Quantity) – radius of sphere from which vector q samples are taken (in units of inverse length; usually 1/angstrom).
sampling (Literal['golden', 'sphere-projected-grid', 'spherical-polar-grid', 'spherical-polar-improved', 'random-sphere']) –
Sphere-sampling scheme. (Case-insensitive) options are:
- ’golden’:
  Fibonnaci-like sampling that steps regularly along one spherical coordinate while making irrational steps in the other
- ’sphere-projected-grid’:
  Regular 2-D square mesh projected onto sphere. npts will be distributed as evenly as possible (i.e. using twice as many ‘longitude’ as ‘lattitude’ lines), rounding up if necessary.
- ’spherical-polar-grid’:
  Mesh over regular subdivisions in spherical polar coordinates. npts will be rounded up as necessary in the same scheme as for sphere-projected-grid. ‘Latitude’ lines are evenly-spaced in z
- ’spherical-polar-improved’:
  npts distributed as regularly as possible using spherical polar coordinates: ‘latitude’ lines are evenly-spaced in z and points are distributed among these rings to obtain most even spacing possible.
- ’random-sphere’:
  Points are distributed randomly in unit square and projected onto sphere.
npts (int) – Number of samples. Note that some sampling methods have constraints on valid values and will round up as appropriate.
jitter (bool) – For non-random sampling schemes, apply an additional random displacement to each point.
rng (Generator | RandomState) – Numpy random Generator for random sampling and jitter
energy_bins (Quantity | None) – Preferred energy bin edges. If not provided, will setup 1000 bins (1001 bin edges) from 0 to 1.05 * [max energy]
weighting (str | None) – One of {‘coherent’, ‘incoherent’, ‘coherent-plus-incoherent’}. If provided, produces a neutron-weighted DOS, weighted by either the coherent, incoherent, or sum of coherent and incoherent neutron scattering cross-sections.
cross_sections (IsotopeData | str | dict[str, Quantity]) –
A dataset of cross-sections for each element in the structure: this can be a string specifying a dataset, a dictionary explicitly giving the cross-sections for each element, or an IsotopeData object (which would ultimately be constructed from the other inputs.)

If cross_sections is a string, it identifies a legacy JSON data collection. This file must contain the ‘coherent_cross_section’ or ‘incoherent_cross_section’ physical property, depending on the weighting argument. If weighting is None, this string argument is not used.

If cross sections is a dictionary, the weighting argument is ignored, and these cross-sections are used directly to calculate the neutron-weighted DOS. It must contain a key for each element in the structure, and each value must be a Quantity in the appropriate units, e.g:
```
{'La': 8.0*ureg('barn'), 'Zr': 9.5*ureg('barn')}
```
**calc_modes_args – other keyword arguments (e.g. ‘use_c’) will be passed to ForceConstants.calculate_qpoint_phonon_modes()

Returns:

Spectrum1DCollection

Return type:

Spectrum1DCollection

sample_sphere_structure_factor(fc, mod_q, *, dw=None, dw_spacing=<Quantity(0.025, '1 / angstrom')>, temperature=<Quantity(273.0, 'kelvin')>, sampling='golden', npts=1000, jitter=False, rng=Generator(PCG64) at 0x74F13DC26180, energy_bins=None, scattering_lengths='Sears1992', **calc_modes_args)

Sample structure factor, averaging over a sphere of constant |q|

(Specifically, this is the one-phonon inelastic-scattering structure factor as implemented in QpointPhononModes.calculate_structure_factor().)

Parameters:

fc (ForceConstants) – Force constant data for system
mod_q (Quantity) – scalar radius of sphere from which vector q samples are taken
dw (DebyeWaller | None) – Debye-Waller exponent used for evaluation of scattering function. If not provided, this is generated automatically over Monkhorst-Pack q-point mesh determined by dw_spacing.
dw_spacing (Quantity) – Maximum distance between q-points in automatic q-point mesh (if used) for Debye-Waller calculation.
temperature (Quantity | None) – Temperature for Debye-Waller calculation. If both temperature and dw are set to None, Debye-Waller factor will be omitted.
sampling (Literal['golden', 'sphere-projected-grid', 'spherical-polar-grid', 'spherical-polar-improved', 'random-sphere']) –
Sphere-sampling scheme. (Case-insensitive) options are:
- ’golden’:
  Fibonnaci-like sampling that steps regularly along one spherical coordinate while making irrational steps in the other
- ’sphere-projected-grid’:
  Regular 2-D square mesh projected onto sphere. npts will be distributed as evenly as possible (i.e. using twice as many ‘longitude’ as ‘lattitude’ lines), rounding up if necessary.
- ’spherical-polar-grid’:
  Mesh over regular subdivisions in spherical polar coordinates. npts will be rounded up as necessary in the same scheme as for sphere-projected-grid. ‘Latitude’ lines are evenly-spaced in z
- ’spherical-polar-improved’:
  npts distributed as regularly as possible using spherical polar coordinates: ‘latitude’ lines are evenly-spaced in z and points are distributed among these rings to obtain most even spacing possible.
- ’random-sphere’:
  Points are distributed randomly in unit square and projected onto sphere.
npts (int) – Number of samples. Note that some sampling methods have constraints on valid values and will round up as appropriate.
jitter (bool) – For non-random sampling schemes, apply an additional random displacement to each point.
rng (Generator | RandomState) – Numpy random Generator for random sampling and jitter
energy_bins (Quantity | None) – Preferred energy bin edges. If not provided, will setup 1000 bins (1001 bin edges) from 0 to 1.05 * [max energy]
scattering_lengths (IsotopeData | str | dict[str, Quantity]) – Reference data for coherent scattering length. This may be a dict of neutron scattering lengths labelled by element. If a string is provided, this selects coherent scattering lengths from legacy JSON reference data. Either of these options will construct an IsotopeData object, which can also be used directly and will be accessed with the “coherent_scattering_length” key.
**calc_modes_args – other keyword arguments (e.g. ‘use_c’) will be passed to ForceConstants.calculate_qpoint_phonon_modes()

Returns:

Spectrum1D

Return type:

Spectrum1D