`utils`

Modules:

Name	Description
`detailed_balance`
`fit_target`
`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,
)

`fit_target`

Classes:

Name	Description
`FitTarget`	One fittable prediction of a model, bound to a key in a parameters Dataset.

Classes

`FitTarget(name, dataset_key, function, label, x_unit, y_unit)` `dataclass`

One fittable prediction of a model, bound to a key in a parameters Dataset.

Models declare their predictions by returning FitTargets (see DiffusionModelBase.get_fit_targets), and FitBinding maps them onto the dataset keys they should be fitted against. Instances are immutable snapshots created on demand, so the units always reflect the model state at the time the targets are built.

Attributes:

Name	Type	Description
`name`	`str`	The prediction's name (e.g. `'width'`, `'area'`, `'delta_area'`, `'value'`).
`dataset_key`	`str \| None`	The key in the parameters Dataset holding the data this prediction is fitted against. None when the prediction has no default key (component models); `FitBinding` supplies the key in that case.
`function`	`Callable`	The fit function; called as `function(x)` with raw x values expressed in x_unit and returning raw values expressed in y_unit.
`label`	`str`	Display label used for plots and results (e.g. `'DeltaLorentz width'`).
`x_unit`	`str \| None`	The unit function expects its input in, or None if no unit conversion applies.
`y_unit`	`str \| None`	The unit of function's output, or None if no unit conversion applies.

`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`

Functions:

Name	Description
`verify_Q_index`	Verify that Q_index is a valid integer index into Q.
`convert_units_with_rollback`	Apply a sequence of unit conversions, rolling all of them back if any fails.
`convert_value_unit`	Convert a numeric value from one unit to another without mutating anything.
`convert_parameter_unit`	Convert a parameter to a new unit, keeping dependent parameters consistent.
`energy_to_scipp`	Convert a numpy energy array to a scipp Variable with dimension 'energy'.

Classes

Functions:

`verify_Q_index(Q_index, Q, allow_none=False)`

Verify that Q_index is a valid integer index into Q.

When Q is None (e.g. no data has been loaded yet), only the type and sign of Q_index are checked; the upper-bound check is deferred until Q is available.

Parameters:

Name	Type	Description	Default
`Q_index`	`int`	Index to validate.	required
`Q`	`sc.Variable \| None`	The Q values (may be None if no data is loaded).	required
`allow_none`	`bool`	Whether or not to allow Q_index to be None	`False`

Raises:

Type	Description
`TypeError`	If Q_index is not an int (or not an int or None when allow_none=True).
`IndexError`	If Q_index is negative, or out of range when Q is available.

`convert_units_with_rollback(conversions)`

Apply a sequence of unit conversions, rolling all of them back if any fails.

Each item is (convert, new_unit, old_unit) where convert is a callable applying a unit (e.g. a bound convert_x_unit or a functools.partial around :func:convert_parameter_unit). The conversions are applied in order; if any raises, every item is converted back to its old unit best-effort (converting a not-yet-converted item back to its old unit is a no-op) and the original exception is re-raised.

Parameters:

Name	Type	Description	Default
`conversions`	`list[tuple[Callable[[str \| sc.Unit], None], str \| sc.Unit, str \| sc.Unit]]`	The conversions to apply, each as `(convert, new_unit, old_unit)`.	required

Raises:

Type	Description
`Exception`	Whatever the failing conversion raised, after the rollback attempt.

`convert_value_unit(value, from_unit, to_unit)`

Convert a numeric value from one unit to another without mutating anything.

Returns the value unchanged when the two units compare equal as strings (the common no-conversion case, kept cheap for hot paths).

Parameters:

Name	Type	Description	Default
`value`	`float`	The value to convert.	required
`from_unit`	`str \| sc.Unit`	The unit the value is currently expressed in.	required
`to_unit`	`str \| sc.Unit`	The unit to convert the value to.	required

Returns:

Type	Description
`float`	The value expressed in to_unit.

`convert_parameter_unit(parameter, unit)`

Convert a parameter to a new unit, keeping dependent parameters consistent.

Independent parameters are converted with convert_unit. Dependent parameters are converted with set_desired_unit, so the new unit survives later dependency-graph recomputations (a plain convert_unit would be reverted to the old desired unit the next time the dependency expression is re-evaluated).

Parameters:

Name	Type	Description	Default
`parameter`	`Parameter`	The parameter to convert.	required
`unit`	`str \| sc.Unit`	The unit to convert to.	required

`energy_to_scipp(energy, unit)`

Convert a numpy energy array to a scipp Variable with dimension 'energy'.

Parameters:

Name	Type	Description	Default
`energy`	`np.ndarray`	The energy array to be converted	required
`unit`	`str \| sc.Unit`	The unit of the energy	required

Returns:

Type	Description
`sc.Variable`	Energy as sc.Variable.

utils

Functions:

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

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

Modules

detailed_balance

Classes

Functions:

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

fit_target

Classes

FitTarget(name, dataset_key, function, label, x_unit, y_unit) dataclass

plotting

Functions:

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

utils

Classes

Functions:

verify_Q_index(Q_index, Q, allow_none=False)

convert_units_with_rollback(conversions)

convert_value_unit(value, from_unit, to_unit)

convert_parameter_unit(parameter, unit)

energy_to_scipp(energy, unit)

`utils`

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

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

`detailed_balance`

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

`fit_target`

`FitTarget(name, dataset_key, function, label, x_unit, y_unit)` `dataclass`

`plotting`

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

`utils`

`verify_Q_index(Q_index, Q, allow_none=False)`

`convert_units_with_rollback(conversions)`

`convert_value_unit(value, from_unit, to_unit)`

`convert_parameter_unit(parameter, unit)`

`energy_to_scipp(energy, unit)`