utils

Modules:

Name	Description
detailed_balance
plotting
utils

Functions:

Name	Description
detailed_balance_factor	Compute the detailed balance factor (DBF): $$ DBF(E, T) = E(n(E)+1)=\frac{E}{(1 - e^{-E /
slicerplot_with_residuals	Create a SlicerPlot with an additional subplot for residuals.

Functions

detailed_balance_factor(energy, temperature, energy_unit='meV', temperature_unit='K', divide_by_temperature=True)

Compute the detailed balance factor (DBF): $$ DBF(E, T) = E(n(E)+1)=\frac{E}{(1 - e^{-E / (k_B*T)})}}, $$ where \(n(E)\) is the Bose-Einstein distribution, \(E\) is the energy transfer, and \(T\) is the temperature. \(k_B\) is the Boltzmann constant. If divide_by_temperature is True, the result is normalized by \(k_B*T\) to have value 1 at \(E=0\).

Parameters:

Name	Type	Description	Default
energy	float | list | np.ndarray | sc.Variable	The energy transfer. If number, assumed to be in meV unless energy_unit is set.	required
temperature	float | sc.Variable | Parameter	The temperature. If number, assumed to be in K unless temperature_unit is set.	required
energy_unit	str | sc.Unit	Unit for energy if energy is given as a number or list.	'meV'
temperature_unit	str | sc.Unit	Unit for temperature if temperature is given as a number.	'K'
divide_by_temperature	bool	If True, divide the result by \(k_B*T\) to make it dimensionless and have value 1 at E=0. By default, True.	True

Raises:

Type	Description
TypeError	If energy or temperature is not a number, list, numpy array, or scipp Variable, or if energy_unit or temperature_unit is not a string or scipp Unit, or if divide_by_temperature is not a boolean.
ValueError	If temperature is negative, or if energy is a numpy array with more than 1 dimension, or if temperature is a scipp Variable that does not have a single dimension named 'temperature', or if energy is a scipp Variable that does not have a single dimension named 'energy'.
UnitError	If the provided energy_unit or temperature_unit is invalid, or if the units of energy or temperature cannot be converted to the expected units.
ZeroDivisionError	If divide_by_temperature is True and temperature is zero.

Returns:

Type	Description
np.ndarray	Detailed balance factor evaluated at the given energy and temperature.

Examples:

Basic usage

from easydynamics.utils.detailed_balance import detailed_balance_factor

dbf = detailed_balance_factor(1.0, 300)  # 1 meV at 300 K

Specifying units and disabling temperature normalisation

dbf = detailed_balance_factor(
    energy=[1.0, 2.0],
    temperature=300,
    energy_unit='microeV',
    temperature_unit='K',
    divide_by_temperature=False,
)

slicerplot_with_residuals(dg, *, residuals_key='Residuals', keep=None, operation='sum', **kwargs)

Create a SlicerPlot with an additional subplot for residuals.

This function is called internally by Analysis.plot_data_and_model and Analysis1d.plot_data_and_model. It can also be used directly with any sc.DataGroup that contains a residuals array.

Examples:

Plotting data, model, and residuals from a DataGroup

import scipp as sc
from easydynamics.utils.plotting import slicerplot_with_residuals

dg = sc.DataGroup({
    'Data': my_data,
    'Model': my_model,
    'Residuals': my_residuals,
})
fig = slicerplot_with_residuals(dg, residuals_key='Residuals', keep='energy')

Parameters:

Name	Type	Description	Default
dg	sc.DataGroup	DataGroup containing the data to plot. Must include a key for residuals.	required
residuals_key	str	Key in the DataGroup that contains the residuals data.	'Residuals'
keep	list[str] | str | None	Dimensions to keep in the SlicerPlot. Passed to SlicerPlot.	None
operation	str	Operation to apply when reducing the residuals data. Passed to SlicerPlot.	'sum'
**kwargs	object	Additional keyword arguments passed to SlicerPlot.	{}

Returns:

Type	Description
InteractiveFigure	A figure containing the SlicerPlot and the residuals subplot.

Raises:

Type	Description
TypeError	If dg is not a sc.DataGroup or if residuals_key is not a string.
ValueError	If residuals_key is not found in the DataGroup.

Modules

detailed_balance

Functions:

Name	Description
detailed_balance_factor	Compute the detailed balance factor (DBF): $$ DBF(E, T) = E(n(E)+1)=\frac{E}{(1 - e^{-E /

Classes

Functions

detailed_balance_factor(energy, temperature, energy_unit='meV', temperature_unit='K', divide_by_temperature=True)

Compute the detailed balance factor (DBF): $$ DBF(E, T) = E(n(E)+1)=\frac{E}{(1 - e^{-E / (k_B*T)})}}, $$ where \(n(E)\) is the Bose-Einstein distribution, \(E\) is the energy transfer, and \(T\) is the temperature. \(k_B\) is the Boltzmann constant. If divide_by_temperature is True, the result is normalized by \(k_B*T\) to have value 1 at \(E=0\).

Parameters:

Name	Type	Description	Default
energy	float | list | np.ndarray | sc.Variable	The energy transfer. If number, assumed to be in meV unless energy_unit is set.	required
temperature	float | sc.Variable | Parameter	The temperature. If number, assumed to be in K unless temperature_unit is set.	required
energy_unit	str | sc.Unit	Unit for energy if energy is given as a number or list.	'meV'
temperature_unit	str | sc.Unit	Unit for temperature if temperature is given as a number.	'K'
divide_by_temperature	bool	If True, divide the result by \(k_B*T\) to make it dimensionless and have value 1 at E=0. By default, True.	True

Raises:

Type	Description
TypeError	If energy or temperature is not a number, list, numpy array, or scipp Variable, or if energy_unit or temperature_unit is not a string or scipp Unit, or if divide_by_temperature is not a boolean.
ValueError	If temperature is negative, or if energy is a numpy array with more than 1 dimension, or if temperature is a scipp Variable that does not have a single dimension named 'temperature', or if energy is a scipp Variable that does not have a single dimension named 'energy'.
UnitError	If the provided energy_unit or temperature_unit is invalid, or if the units of energy or temperature cannot be converted to the expected units.
ZeroDivisionError	If divide_by_temperature is True and temperature is zero.

Returns:

Type	Description
np.ndarray	Detailed balance factor evaluated at the given energy and temperature.

Examples:

Basic usage

from easydynamics.utils.detailed_balance import detailed_balance_factor

dbf = detailed_balance_factor(1.0, 300)  # 1 meV at 300 K

Specifying units and disabling temperature normalisation

dbf = detailed_balance_factor(
    energy=[1.0, 2.0],
    temperature=300,
    energy_unit='microeV',
    temperature_unit='K',
    divide_by_temperature=False,
)

plotting

Functions:

Name	Description
slicerplot_with_residuals	Create a SlicerPlot with an additional subplot for residuals.

Functions

slicerplot_with_residuals(dg, *, residuals_key='Residuals', keep=None, operation='sum', **kwargs)

Create a SlicerPlot with an additional subplot for residuals.

This function is called internally by Analysis.plot_data_and_model and Analysis1d.plot_data_and_model. It can also be used directly with any sc.DataGroup that contains a residuals array.

Examples:

Plotting data, model, and residuals from a DataGroup

import scipp as sc
from easydynamics.utils.plotting import slicerplot_with_residuals

dg = sc.DataGroup({
    'Data': my_data,
    'Model': my_model,
    'Residuals': my_residuals,
})
fig = slicerplot_with_residuals(dg, residuals_key='Residuals', keep='energy')

Parameters:

Name	Type	Description	Default
dg	sc.DataGroup	DataGroup containing the data to plot. Must include a key for residuals.	required
residuals_key	str	Key in the DataGroup that contains the residuals data.	'Residuals'
keep	list[str] | str | None	Dimensions to keep in the SlicerPlot. Passed to SlicerPlot.	None
operation	str	Operation to apply when reducing the residuals data. Passed to SlicerPlot.	'sum'
**kwargs	object	Additional keyword arguments passed to SlicerPlot.	{}

Returns:

Type	Description
InteractiveFigure	A figure containing the SlicerPlot and the residuals subplot.

Raises:

Type	Description
TypeError	If dg is not a sc.DataGroup or if residuals_key is not a string.
ValueError	If residuals_key is not found in the DataGroup.

utils

Classes