Powder averaging

Functions for averaging spectra in spherical q bins

sample_sphere_dos(fc, mod_q, sampling='golden', npts=1000, jitter=False, energy_bins=None, rng=Generator(PCG64) at 0x7DB5D06F2340, **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.
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]
rng (Generator | RandomState) – Numpy random Generator for random sampling and jitter
**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, energy_bins=None, weighting=None, cross_sections='BlueBook', rng=Generator(PCG64) at 0x7DB5D06F2340, **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.
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 (str | dict[str, Quantity]) –
A dataset of cross-sections for each element in the structure, it can be a string specifying a dataset, or a dictionary explicitly giving the cross-sections for each element.

If cross_sections is a string, it is passed to the collection argument of euphonic.util.get_reference_data(). This collection 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')}
```
rng (Generator | RandomState) – Numpy random Generator for random sampling and jitter
**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, energy_bins=None, scattering_lengths='Sears1992', rng=Generator(PCG64) at 0x7DB5D06F2340, **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.
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 (str | dict[str, Quantity]) – Dict of neutron scattering lengths labelled by element. If a string is provided, this selects coherent scattering lengths from reference data by setting the ‘label’ argument of the euphonic.util.get_reference_data() function.
rng (Generator | RandomState) – Numpy random Generator for random sampling and jitter
**calc_modes_args – other keyword arguments (e.g. ‘use_c’) will be passed to ForceConstants.calculate_qpoint_phonon_modes()

Returns:

Spectrum1D

Return type:

Spectrum1D