convolution

Modules:

Name	Description
analytical_convolution
convolution
convolution_base
energy_grid
numerical_convolution
numerical_convolution_base

Classes:

Name	Description
Convolution	Convolution class that combines analytical and numerical convolution methods to efficiently

Classes

Convolution(energy, sample_components, resolution_components, energy_offset=0.0, convolution_settings=None, temperature=None, temperature_unit='K', detailed_balance_settings=None, unit='meV', display_name='MyConvolution', unique_name=None)

Convolution class that combines analytical and numerical convolution methods to efficiently perform convolutions of ComponentCollections with ResolutionComponents.

Supports analytical convolution for pairs of analytical model components (DeltaFunction, Gaussian, Lorentzian, Voigt), while using numerical convolution for other components. If temperature is provided, detailed balance correction is applied to the sample model. In this case, all convolutions are handled numerically. Includes a setting to normalize the detailed balance correction. Includes optional upsampling and extended range to improve accuracy of the numerical convolutions. Also warns about numerical instabilities if peaks are very wide or very narrow.

Parameters:

Name	Type	Description	Default
energy	np.ndarray | sc.Variable	1D array of energy values where the convolution is evaluated.	required
sample_components	ComponentCollection | ModelComponent	The sample components to be convolved.	required
resolution_components	ComponentCollection | ModelComponent	The resolution components to convolve with.	required
energy_offset	Numeric | Parameter	An energy offset to apply to the energy values before convolution.	0.0
convolution_settings	ConvolutionSettings | None	The settings for the convolution. If None, default settings will be used.	None
temperature	Parameter | Numeric | None	The temperature to use for detailed balance correction.	None
temperature_unit	str | sc.Unit	The unit of the temperature parameter.	'K'
detailed_balance_settings	DetailedBalanceSettings | None	The settings for detailed balance. If None, default settings will be used.	None
unit	str | sc.Unit	The unit of the energy.	'meV'
display_name	str | None	Display name of the model.	'MyConvolution'
unique_name	str | None	Unique name of the model. If None, a unique name will be generated.	None

Methods:

Name	Description
to_dict	Convert an EasyScience object into a full dictionary using
from_dict	Re-create an EasyScience object with DescriptorNumber
__dir__	This creates auto-completion and helps out in iPython
__copy__	Return a copy of the object.
__repr__	Return a string representation of the NumericalConvolutionBase.
get_all_variables	Get all Descriptor and Parameter objects as a list.
get_all_parameters	Get all Parameter objects as a list.
get_fittable_parameters	Get all parameters which can be fitted as a list.
get_free_parameters	Get all parameters which are currently free to be fitted as a
get_fit_parameters	This is an alias for get_free_parameters.
energy	Set the energy array and recreate the dense grid.
convert_unit	Convert the energy and energy_offset to the specified unit.
convolution	Perform convolution using analytical convolutions where possible, and numerical
__setattr__	Custom setattr to invalidate convolution plan on relevant attribute changes, and build a

Attributes:

Name	Type	Description
unique_name	str	Get the unique name of the object.
display_name	str	Get a pretty display name.
name	str	Get the name of the model.
unit	str | sc.Unit | None	Get the unit of the model.
energy_offset	Parameter	Get the energy offset.
energy_with_offset	sc.Variable	Get the energy with the offset applied.
sample_components	ComponentCollection | ModelComponent	Get the sample model.
resolution_components	ComponentCollection | ModelComponent	Get the resolution model.
temperature	Parameter | None	Get the temperature.
convolution_settings	ConvolutionSettings	Get the convolution settings.
upsample_factor	Numeric | None	Get the upsample factor.
extension_factor	float	Get the extension factor.
detailed_balance_settings	DetailedBalanceSettings	Get the DetailedBalanceSettings of the Convolution.

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

:return: The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
str	The name of the model.

unit property writable

Get the unit of the model.

Returns:

Type	Description
str | sc.Unit | None	The unit of the model.

energy_offset property writable

Get the energy offset.

Returns:

Type	Description
Parameter	The energy offset applied to the convolution.

energy_with_offset property writable

Get the energy with the offset applied.

Returns:

Type	Description
sc.Variable	The energy values with the offset applied.

sample_components property writable

Get the sample model.

Returns:

Type	Description
ComponentCollection | ModelComponent	The sample model to be convolved.

resolution_components property writable

Get the resolution model.

Returns:

Type	Description
ComponentCollection | ModelComponent	The resolution model to be convolved.

temperature property writable

Get the temperature.

Returns:

Type	Description
Parameter | None	The temperature parameter, or None if detailed balance correction is disabled.

convolution_settings property writable

Get the convolution settings.

Returns:

Type	Description
ConvolutionSettings	The convolution settings.

upsample_factor property writable

Get the upsample factor.

Returns:

Type	Description
Numeric | None	The upsample factor.

extension_factor property writable

Get the extension factor.

The extension factor determines how much the energy range is extended on both sides before convolution. 0.2 means extending by 20% of the original energy span on each side

Returns:

Type	Description
float	The extension factor.

detailed_balance_settings property writable

Get the DetailedBalanceSettings of the Convolution.

Returns:

Type	Description
DetailedBalanceSettings	The DetailedBalanceSettings of the Convolution.

Functions

to_dict(skip=None)

Convert an EasyScience object into a full dictionary using SerializerBases generic convert_to_dict method.

:param skip: List of field names as strings to skip when forming the dictionary :return: encoded object containing all information to reform an EasyScience object.

from_dict(obj_dict) classmethod

Re-create an EasyScience object with DescriptorNumber attributes from a full encoded dictionary.

:param obj_dict: dictionary containing the serialized contents (from SerializerDict) of an EasyScience object :return: Reformed EasyScience object

__dir__()

This creates auto-completion and helps out in iPython notebooks.

:return: list of function and parameter names for auto- completion

__copy__()

Return a copy of the object.

__repr__()

Return a string representation of the NumericalConvolutionBase.

Returns:

Type	Description
str	A string representation of the NumericalConvolutionBase.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

:return: List of Descriptor and Parameter objects.

get_all_parameters()

Get all Parameter objects as a list.

:return: List of Parameter objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

:return: List of Parameter objects.

get_free_parameters()

Get all parameters which are currently free to be fitted as a list.

:return: List of Parameter objects.

get_fit_parameters()

This is an alias for get_free_parameters.

To be removed when fully moved to new base classes and minimizer can be changed.

energy(energy)

Set the energy array and recreate the dense grid.

Parameters:

Name	Type	Description	Default
energy	np.ndarray	The new energy array.	required

convert_unit(unit)

Convert the energy and energy_offset to the specified unit.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The unit of the energy.	required

Raises:

Type	Description
TypeError	If unit is not a string or scipp unit.
Exception	If energy cannot be converted to the specified unit.

convolution()

Perform convolution using analytical convolutions where possible, and numerical convolutions for the remaining components.

Returns:

Type	Description
np.ndarray	The convolved values evaluated at energy.

__setattr__(name, value)

Custom setattr to invalidate convolution plan on relevant attribute changes, and build a new plan.

The new plan is only built after initialization (when _reactions_enabled is True) to avoid issues during init.

Parameters:

Name	Type	Description	Default
name	str	The name of the attribute to set.	required
value	any	The value to set the attribute to.	required

Modules

analytical_convolution

Classes:

Name	Description
AnalyticalConvolution	Analytical convolution of a ModelComponent or ComponentCollection with a ResolutionModel.

Classes

AnalyticalConvolution(energy, unit='meV', sample_components=None, resolution_components=None, energy_offset=0.0, display_name='MyConvolution', unique_name=None)

Analytical convolution of a ModelComponent or ComponentCollection with a ResolutionModel.

Possible analytical convolutions are any combination of delta functions, Gaussians, Lorentzians and Voigt profiles.

Parameters:

Name	Type	Description	Default
energy	np.ndarray | sc.Variable	1D array of energy values where the convolution is evaluated.	required
unit	str | sc.Unit	The unit of the energy.	'meV'
sample_components	ComponentCollection | ModelComponent | None	The sample model to be convolved.	None
resolution_components	ComponentCollection | ModelComponent | None	The resolution model to convolve with.	None
energy_offset	Numeric | Parameter	An offset to shift the energy values by.	0.0
display_name	str | None	Display name of the model.	'MyConvolution'
unique_name	str | None	Unique name of the model. If None, a unique name will be generated.	None

Methods:

Name	Description
convolution	Convolve sample with resolution analytically if possible.
to_dict	Convert an EasyScience object into a full dictionary using
from_dict	Re-create an EasyScience object with DescriptorNumber
__dir__	This creates auto-completion and helps out in iPython
__copy__	Return a copy of the object.
get_all_variables	Get all Descriptor and Parameter objects as a list.
get_all_parameters	Get all Parameter objects as a list.
get_fittable_parameters	Get all parameters which can be fitted as a list.
get_free_parameters	Get all parameters which are currently free to be fitted as a
get_fit_parameters	This is an alias for get_free_parameters.
convert_unit	Convert the energy and energy_offset to the specified unit.

Attributes:

Name	Type	Description
unique_name	str	Get the unique name of the object.
display_name	str	Get a pretty display name.
name	str	Get the name of the model.
unit	str | sc.Unit | None	Get the unit of the model.
energy_offset	Parameter	Get the energy offset.
energy_with_offset	sc.Variable	Get the energy with the offset applied.
energy	sc.Variable	Get the energy.
sample_components	ComponentCollection | ModelComponent	Get the sample model.
resolution_components	ComponentCollection | ModelComponent	Get the resolution model.

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

:return: The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
str	The name of the model.

unit property writable

Get the unit of the model.

Returns:

Type	Description
str | sc.Unit | None	The unit of the model.

energy_offset property writable

Get the energy offset.

Returns:

Type	Description
Parameter	The energy offset applied to the convolution.

energy_with_offset property writable

Get the energy with the offset applied.

Returns:

Type	Description
sc.Variable	The energy values with the offset applied.

energy property writable

Get the energy.

Returns:

Type	Description
sc.Variable	The energy values where the convolution is evaluated.

sample_components property writable

Get the sample model.

Returns:

Type	Description
ComponentCollection | ModelComponent	The sample model to be convolved.

resolution_components property writable

Get the resolution model.

Returns:

Type	Description
ComponentCollection | ModelComponent	The resolution model to be convolved.

Functions

convolution()

Convolve sample with resolution analytically if possible.

Accepts ComponentCollection or single ModelComponent for each. Possible analytical convolutions are any combination of delta functions, Gaussians, Lorentzians and Voigt profiles.

Returns:

Type	Description
np.ndarray	The convolution of the sample_components and resolution_components values evaluated at self.energy.

to_dict(skip=None)

Convert an EasyScience object into a full dictionary using SerializerBases generic convert_to_dict method.

:param skip: List of field names as strings to skip when forming the dictionary :return: encoded object containing all information to reform an EasyScience object.

from_dict(obj_dict) classmethod

Re-create an EasyScience object with DescriptorNumber attributes from a full encoded dictionary.

:param obj_dict: dictionary containing the serialized contents (from SerializerDict) of an EasyScience object :return: Reformed EasyScience object

__dir__()

This creates auto-completion and helps out in iPython notebooks.

:return: list of function and parameter names for auto- completion

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

:return: List of Descriptor and Parameter objects.

get_all_parameters()

Get all Parameter objects as a list.

:return: List of Parameter objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

:return: List of Parameter objects.

get_free_parameters()

Get all parameters which are currently free to be fitted as a list.

:return: List of Parameter objects.

get_fit_parameters()

This is an alias for get_free_parameters.

To be removed when fully moved to new base classes and minimizer can be changed.

convert_unit(unit)

Convert the energy and energy_offset to the specified unit.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The unit of the energy.	required

Raises:

Type	Description
TypeError	If unit is not a string or scipp unit.
Exception	If energy cannot be converted to the specified unit.

convolution

Classes:

Name	Description
Convolution	Convolution class that combines analytical and numerical convolution methods to efficiently

Classes

Convolution(energy, sample_components, resolution_components, energy_offset=0.0, convolution_settings=None, temperature=None, temperature_unit='K', detailed_balance_settings=None, unit='meV', display_name='MyConvolution', unique_name=None)

Convolution class that combines analytical and numerical convolution methods to efficiently perform convolutions of ComponentCollections with ResolutionComponents.

Supports analytical convolution for pairs of analytical model components (DeltaFunction, Gaussian, Lorentzian, Voigt), while using numerical convolution for other components. If temperature is provided, detailed balance correction is applied to the sample model. In this case, all convolutions are handled numerically. Includes a setting to normalize the detailed balance correction. Includes optional upsampling and extended range to improve accuracy of the numerical convolutions. Also warns about numerical instabilities if peaks are very wide or very narrow.

Parameters:

Name	Type	Description	Default
energy	np.ndarray | sc.Variable	1D array of energy values where the convolution is evaluated.	required
sample_components	ComponentCollection | ModelComponent	The sample components to be convolved.	required
resolution_components	ComponentCollection | ModelComponent	The resolution components to convolve with.	required
energy_offset	Numeric | Parameter	An energy offset to apply to the energy values before convolution.	0.0
convolution_settings	ConvolutionSettings | None	The settings for the convolution. If None, default settings will be used.	None
temperature	Parameter | Numeric | None	The temperature to use for detailed balance correction.	None
temperature_unit	str | sc.Unit	The unit of the temperature parameter.	'K'
detailed_balance_settings	DetailedBalanceSettings | None	The settings for detailed balance. If None, default settings will be used.	None
unit	str | sc.Unit	The unit of the energy.	'meV'
display_name	str | None	Display name of the model.	'MyConvolution'
unique_name	str | None	Unique name of the model. If None, a unique name will be generated.	None

Methods:

Name	Description
convolution	Perform convolution using analytical convolutions where possible, and numerical
__setattr__	Custom setattr to invalidate convolution plan on relevant attribute changes, and build a
to_dict	Convert an EasyScience object into a full dictionary using
from_dict	Re-create an EasyScience object with DescriptorNumber
__dir__	This creates auto-completion and helps out in iPython
__copy__	Return a copy of the object.
__repr__	Return a string representation of the NumericalConvolutionBase.
get_all_variables	Get all Descriptor and Parameter objects as a list.
get_all_parameters	Get all Parameter objects as a list.
get_fittable_parameters	Get all parameters which can be fitted as a list.
get_free_parameters	Get all parameters which are currently free to be fitted as a
get_fit_parameters	This is an alias for get_free_parameters.
energy	Set the energy array and recreate the dense grid.
convert_unit	Convert the energy and energy_offset to the specified unit.

Attributes:

Name	Type	Description
unique_name	str	Get the unique name of the object.
display_name	str	Get a pretty display name.
name	str	Get the name of the model.
unit	str | sc.Unit | None	Get the unit of the model.
energy_offset	Parameter	Get the energy offset.
energy_with_offset	sc.Variable	Get the energy with the offset applied.
sample_components	ComponentCollection | ModelComponent	Get the sample model.
resolution_components	ComponentCollection | ModelComponent	Get the resolution model.
temperature	Parameter | None	Get the temperature.
convolution_settings	ConvolutionSettings	Get the convolution settings.
upsample_factor	Numeric | None	Get the upsample factor.
extension_factor	float	Get the extension factor.
detailed_balance_settings	DetailedBalanceSettings	Get the DetailedBalanceSettings of the Convolution.

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

:return: The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
str	The name of the model.

unit property writable

Get the unit of the model.

Returns:

Type	Description
str | sc.Unit | None	The unit of the model.

energy_offset property writable

Get the energy offset.

Returns:

Type	Description
Parameter	The energy offset applied to the convolution.

energy_with_offset property writable

Get the energy with the offset applied.

Returns:

Type	Description
sc.Variable	The energy values with the offset applied.

sample_components property writable

Get the sample model.

Returns:

Type	Description
ComponentCollection | ModelComponent	The sample model to be convolved.

resolution_components property writable

Get the resolution model.

Returns:

Type	Description
ComponentCollection | ModelComponent	The resolution model to be convolved.

temperature property writable

Get the temperature.

Returns:

Type	Description
Parameter | None	The temperature parameter, or None if detailed balance correction is disabled.

convolution_settings property writable

Get the convolution settings.

Returns:

Type	Description
ConvolutionSettings	The convolution settings.

upsample_factor property writable

Get the upsample factor.

Returns:

Type	Description
Numeric | None	The upsample factor.

extension_factor property writable

Get the extension factor.

The extension factor determines how much the energy range is extended on both sides before convolution. 0.2 means extending by 20% of the original energy span on each side

Returns:

Type	Description
float	The extension factor.

detailed_balance_settings property writable

Get the DetailedBalanceSettings of the Convolution.

Returns:

Type	Description
DetailedBalanceSettings	The DetailedBalanceSettings of the Convolution.

Functions

convolution()

Perform convolution using analytical convolutions where possible, and numerical convolutions for the remaining components.

Returns:

Type	Description
np.ndarray	The convolved values evaluated at energy.

__setattr__(name, value)

Custom setattr to invalidate convolution plan on relevant attribute changes, and build a new plan.

The new plan is only built after initialization (when _reactions_enabled is True) to avoid issues during init.

Parameters:

Name	Type	Description	Default
name	str	The name of the attribute to set.	required
value	any	The value to set the attribute to.	required

to_dict(skip=None)

Convert an EasyScience object into a full dictionary using SerializerBases generic convert_to_dict method.

:param skip: List of field names as strings to skip when forming the dictionary :return: encoded object containing all information to reform an EasyScience object.

from_dict(obj_dict) classmethod

Re-create an EasyScience object with DescriptorNumber attributes from a full encoded dictionary.

:param obj_dict: dictionary containing the serialized contents (from SerializerDict) of an EasyScience object :return: Reformed EasyScience object

__dir__()

This creates auto-completion and helps out in iPython notebooks.

:return: list of function and parameter names for auto- completion

__copy__()

Return a copy of the object.

__repr__()

Return a string representation of the NumericalConvolutionBase.

Returns:

Type	Description
str	A string representation of the NumericalConvolutionBase.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

:return: List of Descriptor and Parameter objects.

get_all_parameters()

Get all Parameter objects as a list.

:return: List of Parameter objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

:return: List of Parameter objects.

get_free_parameters()

Get all parameters which are currently free to be fitted as a list.

:return: List of Parameter objects.

get_fit_parameters()

This is an alias for get_free_parameters.

To be removed when fully moved to new base classes and minimizer can be changed.

energy(energy)

Set the energy array and recreate the dense grid.

Parameters:

Name	Type	Description	Default
energy	np.ndarray	The new energy array.	required

convert_unit(unit)

Convert the energy and energy_offset to the specified unit.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The unit of the energy.	required

Raises:

Type	Description
TypeError	If unit is not a string or scipp unit.
Exception	If energy cannot be converted to the specified unit.

convolution_base

Classes:

Name	Description
ConvolutionBase	Base class for convolutions of sample and resolution models.

Classes

ConvolutionBase(energy, sample_components=None, resolution_components=None, unit='meV', energy_offset=0.0, display_name='MyConvolution', unique_name=None)

Base class for convolutions of sample and resolution models.

This base class has no convolution functionality.

Parameters:

Name	Type	Description	Default
energy	np.ndarray | sc.Variable	1D array of energy values where the convolution is evaluated.	required
sample_components	ComponentCollection | ModelComponent | None	The sample model to be convolved.	None
resolution_components	ComponentCollection | ModelComponent | None	The resolution model to convolve with.	None
unit	str | sc.Unit	The unit of the energy.	'meV'
energy_offset	Numeric | Parameter	The energy offset applied to the convolution.	0.0
display_name	str | None	Display name of the model.	'MyConvolution'
unique_name	str | None	Unique name of the model. If None, a unique name will be generated.	None

Raises:

Type	Description
TypeError	If energy is not a numpy ndarray or a scipp Variable or if energy_unit is not a string or scipp unit, or if energy_offset is not a number or a Parameter, or if sample_components is not a ComponentCollection or ModelComponent, or if resolution_components is not a ComponentCollection or ModelComponent.

Methods:

Name	Description
convert_unit	Convert the energy and energy_offset to the specified unit.
to_dict	Convert an EasyScience object into a full dictionary using
from_dict	Re-create an EasyScience object with DescriptorNumber
__dir__	This creates auto-completion and helps out in iPython
__copy__	Return a copy of the object.
get_all_variables	Get all Descriptor and Parameter objects as a list.
get_all_parameters	Get all Parameter objects as a list.
get_fittable_parameters	Get all parameters which can be fitted as a list.
get_free_parameters	Get all parameters which are currently free to be fitted as a
get_fit_parameters	This is an alias for get_free_parameters.

Attributes:

Name	Type	Description
energy_offset	Parameter	Get the energy offset.
energy_with_offset	sc.Variable	Get the energy with the offset applied.
energy	sc.Variable	Get the energy.
sample_components	ComponentCollection | ModelComponent	Get the sample model.
resolution_components	ComponentCollection | ModelComponent	Get the resolution model.
unique_name	str	Get the unique name of the object.
display_name	str	Get a pretty display name.
name	str	Get the name of the model.
unit	str | sc.Unit | None	Get the unit of the model.

Attributes

energy_offset property writable

Get the energy offset.

Returns:

Type	Description
Parameter	The energy offset applied to the convolution.

energy_with_offset property writable

Get the energy with the offset applied.

Returns:

Type	Description
sc.Variable	The energy values with the offset applied.

energy property writable

Get the energy.

Returns:

Type	Description
sc.Variable	The energy values where the convolution is evaluated.

sample_components property writable

Get the sample model.

Returns:

Type	Description
ComponentCollection | ModelComponent	The sample model to be convolved.

resolution_components property writable

Get the resolution model.

Returns:

Type	Description
ComponentCollection | ModelComponent	The resolution model to be convolved.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

:return: The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
str	The name of the model.

unit property writable

Get the unit of the model.

Returns:

Type	Description
str | sc.Unit | None	The unit of the model.

Functions

convert_unit(unit)

Convert the energy and energy_offset to the specified unit.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The unit of the energy.	required

Raises:

Type	Description
TypeError	If unit is not a string or scipp unit.
Exception	If energy cannot be converted to the specified unit.

to_dict(skip=None)

Convert an EasyScience object into a full dictionary using SerializerBases generic convert_to_dict method.

:param skip: List of field names as strings to skip when forming the dictionary :return: encoded object containing all information to reform an EasyScience object.

from_dict(obj_dict) classmethod

Re-create an EasyScience object with DescriptorNumber attributes from a full encoded dictionary.

:param obj_dict: dictionary containing the serialized contents (from SerializerDict) of an EasyScience object :return: Reformed EasyScience object

__dir__()

This creates auto-completion and helps out in iPython notebooks.

:return: list of function and parameter names for auto- completion

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

:return: List of Descriptor and Parameter objects.

get_all_parameters()

Get all Parameter objects as a list.

:return: List of Parameter objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

:return: List of Parameter objects.

get_free_parameters()

Get all parameters which are currently free to be fitted as a list.

:return: List of Parameter objects.

get_fit_parameters()

This is an alias for get_free_parameters.

To be removed when fully moved to new base classes and minimizer can be changed.

energy_grid

Classes:

Name	Description
EnergyGrid	Container for the dense energy grid and related metadata.

Classes

EnergyGrid(energy_dense, energy_dense_centered, energy_dense_step, energy_span_dense, energy_even_length_offset) dataclass

Container for the dense energy grid and related metadata.

Attributes:

Name	Type	Description
energy_dense	np.ndarray	The upsampled and extended energy array.
energy_dense_centered	np.ndarray	The centered version of energy_dense (used for resolution evaluation).
energy_dense_step	float	The spacing of energy_dense (used for width checks and normalization).
energy_span_dense	float	The total span of energy_dense. (used for width checks).
energy_even_length_offset	float	The offset to apply if energy_dense has even length (used for convolution alignment).

numerical_convolution

Classes:

Name	Description
NumericalConvolution	Numerical convolution of a ComponentCollection with a ComponentCollection using FFT.

Classes

NumericalConvolution(energy, sample_components, resolution_components, energy_offset=0.0, convolution_settings=None, temperature=None, temperature_unit='K', detailed_balance_settings=None, unit='meV', display_name='MyConvolution', unique_name=None)

Numerical convolution of a ComponentCollection with a ComponentCollection using FFT.

Includes optional upsampling and extended range to improve accuracy. Warns about very wide or very narrow peaks in the models. If temperature is provided, detailed balance correction is applied to the sample model.

Parameters:

Name	Type	Description	Default
energy	np.ndarray | sc.Variable	1D array of energy values where the convolution is evaluated.	required
sample_components	ComponentCollection | ModelComponent	The sample model to be convolved.	required
resolution_components	ComponentCollection | ModelComponent	The resolution model to convolve with.	required
energy_offset	Numeric | Parameter	An energy offset to apply to the energy values before convolution.	0.0
convolution_settings	ConvolutionSettings | None	The settings for the convolution.	None
temperature	Parameter | Numeric | None	The temperature to use for detailed balance correction.	None
temperature_unit	str | sc.Unit	The unit of the temperature parameter.	'K'
detailed_balance_settings	DetailedBalanceSettings | None	The settings for detailed balance. If None, default settings will be used.	None
unit	str | sc.Unit	The unit of the energy.	'meV'
display_name	str | None	Display name of the model.	'MyConvolution'
unique_name	str | None	Unique name of the model. If None, a unique name will be generated.	None

Methods:

Name	Description
convolution	Calculate the convolution of the sample and resolution models at the values given in
to_dict	Convert an EasyScience object into a full dictionary using
from_dict	Re-create an EasyScience object with DescriptorNumber
__dir__	This creates auto-completion and helps out in iPython
__copy__	Return a copy of the object.
__repr__	Return a string representation of the NumericalConvolutionBase.
get_all_variables	Get all Descriptor and Parameter objects as a list.
get_all_parameters	Get all Parameter objects as a list.
get_fittable_parameters	Get all parameters which can be fitted as a list.
get_free_parameters	Get all parameters which are currently free to be fitted as a
get_fit_parameters	This is an alias for get_free_parameters.
energy	Set the energy array and recreate the dense grid.
convert_unit	Convert the energy and energy_offset to the specified unit.

Attributes:

Name	Type	Description
unique_name	str	Get the unique name of the object.
display_name	str	Get a pretty display name.
name	str	Get the name of the model.
unit	str | sc.Unit | None	Get the unit of the model.
energy_offset	Parameter	Get the energy offset.
energy_with_offset	sc.Variable	Get the energy with the offset applied.
sample_components	ComponentCollection | ModelComponent	Get the sample model.
resolution_components	ComponentCollection | ModelComponent	Get the resolution model.
temperature	Parameter | None	Get the temperature.
convolution_settings	ConvolutionSettings	Get the convolution settings.
upsample_factor	Numeric | None	Get the upsample factor.
extension_factor	float	Get the extension factor.
detailed_balance_settings	DetailedBalanceSettings	Get the DetailedBalanceSettings of the Convolution.

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

:return: The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
str	The name of the model.

unit property writable

Get the unit of the model.

Returns:

Type	Description
str | sc.Unit | None	The unit of the model.

energy_offset property writable

Get the energy offset.

Returns:

Type	Description
Parameter	The energy offset applied to the convolution.

energy_with_offset property writable

Get the energy with the offset applied.

Returns:

Type	Description
sc.Variable	The energy values with the offset applied.

sample_components property writable

Get the sample model.

Returns:

Type	Description
ComponentCollection | ModelComponent	The sample model to be convolved.

resolution_components property writable

Get the resolution model.

Returns:

Type	Description
ComponentCollection | ModelComponent	The resolution model to be convolved.

temperature property writable

Get the temperature.

Returns:

Type	Description
Parameter | None	The temperature parameter, or None if detailed balance correction is disabled.

convolution_settings property writable

Get the convolution settings.

Returns:

Type	Description
ConvolutionSettings	The convolution settings.

upsample_factor property writable

Get the upsample factor.

Returns:

Type	Description
Numeric | None	The upsample factor.

extension_factor property writable

Get the extension factor.

The extension factor determines how much the energy range is extended on both sides before convolution. 0.2 means extending by 20% of the original energy span on each side

Returns:

Type	Description
float	The extension factor.

detailed_balance_settings property writable

Get the DetailedBalanceSettings of the Convolution.

Returns:

Type	Description
DetailedBalanceSettings	The DetailedBalanceSettings of the Convolution.

Functions

convolution()

Calculate the convolution of the sample and resolution models at the values given in energy. Includes detailed balance correction if temperature is provided.

Returns:

Type	Description
np.ndarray	The convolved values evaluated at energy.

to_dict(skip=None)

Convert an EasyScience object into a full dictionary using SerializerBases generic convert_to_dict method.

:param skip: List of field names as strings to skip when forming the dictionary :return: encoded object containing all information to reform an EasyScience object.

from_dict(obj_dict) classmethod

Re-create an EasyScience object with DescriptorNumber attributes from a full encoded dictionary.

:param obj_dict: dictionary containing the serialized contents (from SerializerDict) of an EasyScience object :return: Reformed EasyScience object

__dir__()

This creates auto-completion and helps out in iPython notebooks.

:return: list of function and parameter names for auto- completion

__copy__()

Return a copy of the object.

__repr__()

Return a string representation of the NumericalConvolutionBase.

Returns:

Type	Description
str	A string representation of the NumericalConvolutionBase.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

:return: List of Descriptor and Parameter objects.

get_all_parameters()

Get all Parameter objects as a list.

:return: List of Parameter objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

:return: List of Parameter objects.

get_free_parameters()

Get all parameters which are currently free to be fitted as a list.

:return: List of Parameter objects.

get_fit_parameters()

This is an alias for get_free_parameters.

To be removed when fully moved to new base classes and minimizer can be changed.

energy(energy)

Set the energy array and recreate the dense grid.

Parameters:

Name	Type	Description	Default
energy	np.ndarray	The new energy array.	required

convert_unit(unit)

Convert the energy and energy_offset to the specified unit.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The unit of the energy.	required

Raises:

Type	Description
TypeError	If unit is not a string or scipp unit.
Exception	If energy cannot be converted to the specified unit.

Functions

numerical_convolution_base

Classes:

Name	Description
NumericalConvolutionBase	Base class for numerical convolutions of sample and resolution models.

Classes

NumericalConvolutionBase(energy, sample_components, resolution_components, energy_offset=0.0, convolution_settings=None, temperature=None, temperature_unit='K', detailed_balance_settings=None, unit='meV', display_name='MyConvolution', unique_name=None)

Base class for numerical convolutions of sample and resolution models.

Provides methods to handle upsampling, extension, and detailed balance correction. This base class has no convolution functionality.

Parameters:

Name	Type	Description	Default
energy	np.ndarray | sc.Variable	1D array of energy values where the convolution is evaluated.	required
sample_components	ComponentCollection | ModelComponent	The components to be convolved.	required
resolution_components	ComponentCollection | ModelComponent	The resolution components to convolve with.	required
energy_offset	Numeric | Parameter	An energy offset to apply to the energy values before convolution.	0.0
convolution_settings	ConvolutionSettings | None	The settings for the convolution. If None, default settings will be used.	None
temperature	Parameter | Numeric | None	The temperature to use for detailed balance correction.	None
temperature_unit	str | sc.Unit	The unit of the temperature parameter.	'K'
detailed_balance_settings	DetailedBalanceSettings | None	The settings for detailed balance. If None, default settings will be used.	None
unit	str | sc.Unit	The unit of the energy.	'meV'
display_name	str | None	Display name of the model.	'MyConvolution'
unique_name	str | None	Unique name of the model. If None, a unique name will be generated.	None

Raises:

Type	Description
TypeError	If temperature is not None, a number, or a Parameter, or if temperature_unit is not a string or sc.Unit.

Methods:

Name	Description
energy	Set the energy array and recreate the dense grid.
__repr__	Return a string representation of the NumericalConvolutionBase.
to_dict	Convert an EasyScience object into a full dictionary using
from_dict	Re-create an EasyScience object with DescriptorNumber
__dir__	This creates auto-completion and helps out in iPython
__copy__	Return a copy of the object.
get_all_variables	Get all Descriptor and Parameter objects as a list.
get_all_parameters	Get all Parameter objects as a list.
get_fittable_parameters	Get all parameters which can be fitted as a list.
get_free_parameters	Get all parameters which are currently free to be fitted as a
get_fit_parameters	This is an alias for get_free_parameters.
convert_unit	Convert the energy and energy_offset to the specified unit.

Attributes:

Name	Type	Description
convolution_settings	ConvolutionSettings	Get the convolution settings.
upsample_factor	Numeric | None	Get the upsample factor.
extension_factor	float	Get the extension factor.
temperature	Parameter | None	Get the temperature.
detailed_balance_settings	DetailedBalanceSettings	Get the DetailedBalanceSettings of the Convolution.
unique_name	str	Get the unique name of the object.
display_name	str	Get a pretty display name.
name	str	Get the name of the model.
unit	str | sc.Unit | None	Get the unit of the model.
energy_offset	Parameter	Get the energy offset.
energy_with_offset	sc.Variable	Get the energy with the offset applied.
sample_components	ComponentCollection | ModelComponent	Get the sample model.
resolution_components	ComponentCollection | ModelComponent	Get the resolution model.

Attributes

convolution_settings property writable

Get the convolution settings.

Returns:

Type	Description
ConvolutionSettings	The convolution settings.

upsample_factor property writable

Get the upsample factor.

Returns:

Type	Description
Numeric | None	The upsample factor.

extension_factor property writable

Get the extension factor.

The extension factor determines how much the energy range is extended on both sides before convolution. 0.2 means extending by 20% of the original energy span on each side

Returns:

Type	Description
float	The extension factor.

temperature property writable

Get the temperature.

Returns:

Type	Description
Parameter | None	The temperature parameter, or None if detailed balance correction is disabled.

detailed_balance_settings property writable

Get the DetailedBalanceSettings of the Convolution.

Returns:

Type	Description
DetailedBalanceSettings	The DetailedBalanceSettings of the Convolution.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

:return: The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
str	The name of the model.

unit property writable

Get the unit of the model.

Returns:

Type	Description
str | sc.Unit | None	The unit of the model.

energy_offset property writable

Get the energy offset.

Returns:

Type	Description
Parameter	The energy offset applied to the convolution.

energy_with_offset property writable

Get the energy with the offset applied.

Returns:

Type	Description
sc.Variable	The energy values with the offset applied.

sample_components property writable

Get the sample model.

Returns:

Type	Description
ComponentCollection | ModelComponent	The sample model to be convolved.

resolution_components property writable

Get the resolution model.

Returns:

Type	Description
ComponentCollection | ModelComponent	The resolution model to be convolved.

Functions

energy(energy)

Set the energy array and recreate the dense grid.

Parameters:

Name	Type	Description	Default
energy	np.ndarray	The new energy array.	required

__repr__()

Return a string representation of the NumericalConvolutionBase.

Returns:

Type	Description
str	A string representation of the NumericalConvolutionBase.

to_dict(skip=None)

Convert an EasyScience object into a full dictionary using SerializerBases generic convert_to_dict method.

:param skip: List of field names as strings to skip when forming the dictionary :return: encoded object containing all information to reform an EasyScience object.

from_dict(obj_dict) classmethod

Re-create an EasyScience object with DescriptorNumber attributes from a full encoded dictionary.

:param obj_dict: dictionary containing the serialized contents (from SerializerDict) of an EasyScience object :return: Reformed EasyScience object

__dir__()

This creates auto-completion and helps out in iPython notebooks.

:return: list of function and parameter names for auto- completion

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

:return: List of Descriptor and Parameter objects.

get_all_parameters()

Get all Parameter objects as a list.

:return: List of Parameter objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

:return: List of Parameter objects.

get_free_parameters()

Get all parameters which are currently free to be fitted as a list.

:return: List of Parameter objects.

get_fit_parameters()

This is an alias for get_free_parameters.

To be removed when fully moved to new base classes and minimizer can be changed.

convert_unit(unit)

Convert the energy and energy_offset to the specified unit.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The unit of the energy.	required

Raises:

Type	Description
TypeError	If unit is not a string or scipp unit.
Exception	If energy cannot be converted to the specified unit.