`sample_model`

Modules:

Name	Description
`background_model`
`component_collection`
`components`
`diffusion_model`
`instrument_model`
`model_base`
`resolution_model`
`sample_model`

Classes:

Name	Description
`BackgroundModel`	BackgroundModel represents a model of the background in an experiment at various Q.
`ComponentCollection`	Collection of model components.
`DampedHarmonicOscillator`	Model of a Damped Harmonic Oscillator (DHO).
`DeltaFunction`	Delta function.
`Exponential`	Model of an exponential function.
`ExpressionComponent`	Model component defined by a symbolic expression.
`Gaussian`	Model of a Gaussian function.
`Lorentzian`	Model of a Lorentzian function.
`Polynomial`	Polynomial function component.
`Voigt`	Voigt profile — convolution of Gaussian and Lorentzian.
`BrownianTranslationalDiffusion`	Model of Brownian translational diffusion, consisting of a Lorentzian function for each
`DeltaLorentz`	Model of Delta function and Lorentzian with intensities given by the Debye-Waller factor. $$ I
`JumpTranslationalDiffusion`	Model of Jump translational diffusion.
`InstrumentModel`	InstrumentModel represents a model of the instrument in an experiment at various Q.
`ResolutionModel`	ResolutionModel represents a model of the instrument resolution in an experiment at various Q.
`SampleModel`	SampleModel represents a model of a sample with components and diffusion models, parameterized

Classes

`BackgroundModel(display_name='MyBackgroundModel', unique_name=None, x_unit='meV', y_unit='dimensionless', components=None, Q=None)`

BackgroundModel represents a model of the background in an experiment at various Q.

Examples:

Creating a flat background

A constant background independent of Q:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
background_model = sm.BackgroundModel(
    components=sm.Polynomial(coefficients=[0.001]),
    Q=Q,
)
energy = np.linspace(-2, 2, 100)
background = background_model.evaluate(energy)

Creating a quadratic background

Higher-order polynomials can model a sloping or curved baseline:

import easydynamics.sample_model as sm

background_model = sm.BackgroundModel(
    components=sm.Polynomial(coefficients=[1.0, 0.1, 0.01]),
)

Parameters:

Name	Type	Description	Default
`display_name`	`str \| None`	Display name of the model.	`'MyBackgroundModel'`
`unique_name`	`str \| None`	Unique name of the model. If None, a unique name will be generated.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis (energy, Q, etc.).	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity).	`'dimensionless'`
`components`	`ModelComponent \| ComponentCollection \| None`	Template components of the model. If None, no components are added. These components are copied into ComponentCollections for each Q value.	`None`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`get_all_variables`	Get all Parameters and Descriptors from all ComponentCollections in the ModelBase.
`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`.
`evaluate`	Evaluate the sample model at all Q for the given x values.
`append_component`	Append a ModelComponent or ComponentCollection to the SampleModel.
`remove_component`	Remove a ModelComponent from the SampleModel by its name.
`clear_components`	Clear all ModelComponents from the SampleModel.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of all components in the model.
`convert_y_unit`	Convert the y-axis unit of all components in the model.
`fix_all_parameters`	Fix all Parameters in all ComponentCollections.
`free_all_parameters`	Free all Parameters in all ComponentCollections.
`get_component_collection`	Get the ComponentCollection at the given Q index.
`normalize_area`	Normalize the area of the model across all Q values.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`components`	`list[ModelComponent]`	Get the components of the SampleModel.
`component_collections_is_dirty`	`bool`	Return whether component collections need to be rebuilt before use.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`components` `property` `writable`

Get the components of the SampleModel.

Returns:

Type	Description
`list[ModelComponent]`	The components of the SampleModel.

`component_collections_is_dirty` `property`

Return whether component collections need to be rebuilt before use.

Returns:

Type	Description
`bool`	`True` if component collections have not been built yet or are stale.

`Q` `property` `writable`

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_variables(Q_index=None)`

Get all Parameters and Descriptors from all ComponentCollections in the ModelBase.

Ignores the Parameters and Descriptors in self._components as these are just templates.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	If None, get variables for all ComponentCollections. If int, get variables for the ComponentCollection at this index.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters and Descriptors from the ComponentCollections in the ModelBase.

`get_all_parameters()`

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_fittable_parameters()`

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_free_parameters()`

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

Returns:

Type	Description
`List[Parameter]`	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.

`evaluate(x, output='numpy')`

Evaluate the sample model at all Q for the given x values.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Energy axis values to evaluate the model at.	required
`output`	`str`	'numpy' returns np.ndarray per Q; 'scipp' returns sc.Variable per Q.	`'numpy'`

Raises:

Type	Description
`ValueError`	If there are no components in the model to evaluate.

Returns:

Type	Description
`list[np.ndarray] \| list[sc.Variable]`	A list of arrays containing the evaluated model values for each Q. The length of the list will match the number of Q values in the model.

`append_component(component)`

Append a ModelComponent or ComponentCollection to the SampleModel.

Parameters:

Name	Type	Description	Default
`component`	`ModelComponent \| ComponentCollection`	The ModelComponent or ComponentCollection to append.	required

`remove_component(name)`

Remove a ModelComponent from the SampleModel by its name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the ModelComponent to remove.	required

`clear_components()`

Clear all ModelComponents from the SampleModel.

`clear_Q(confirm=False)`

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

`convert_x_unit(unit)`

Convert the x-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit to convert to.	required

`convert_y_unit(unit)`

Convert the y-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit to convert to.	required

`fix_all_parameters()`

Fix all Parameters in all ComponentCollections.

`free_all_parameters()`

Free all Parameters in all ComponentCollections.

`get_component_collection(Q_index)`

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int`	The index of the desired ComponentCollection.	required

Returns:

Type	Description
`ComponentCollection`	The ComponentCollection at the given Q index.

`normalize_area()`

Normalize the area of the model across all Q values.

`ComponentCollection(components=None, x_unit='meV', y_unit='dimensionless', name='ComponentCollection', display_name=None, unique_name=None)`

Collection of model components.

Examples:

Creating a ComponentCollection with multiple components

import numpy as np
import easydynamics.sample_model as sm

component1 = sm.Gaussian(name='Gaussian1', area=1.0, width=1.0)
component2 = sm.Lorentzian(name='Lorentzian1', area=2.0, width=0.5)
collection = sm.ComponentCollection(components=[component1, component2])

Evaluating, appending, and removing components

x = np.linspace(-5, 5, 100)
values = collection.evaluate(x)

component3 = sm.Gaussian(name='Gaussian2', area=0.5, width=0.8)
collection.append(component3)

collection.remove('Gaussian1')
collection.list_component_names()  # ['Lorentzian1', 'Gaussian2']

Parameters:

Name	Type	Description	Default
`components`	`ModelComponent \| list[ModelComponent] \| None`	Initial model components to add to the ComponentCollection.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis (energy, Q, etc.).	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity).	`'dimensionless'`
`name`	`str`	Name of the collection.	`'ComponentCollection'`
`display_name`	`str \| None`	Display name of the collection.	`None`
`unique_name`	`str \| None`	Unique name of the collection.	`None`

Raises:

Type	Description
`TypeError`	If components is not a list of ModelComponent.

Methods:

Name	Description
`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`.
`__getitem__`	Get an item by index, slice, or unique_name.
`__setitem__`	Set an item at an index.
`__delitem__`	Delete an item by index, slice, or name.
`__len__`	Return the number of items in the collection.
`insert`	Insert an item into the list at a specific index.
`sort`	Sort the collection according to the given key function.
`pop`	Remove and return an item at a specific index or name.
`append`	Append an item to the end of the list.
`get_names`	Get a list of the names of all items in the list.
`get_duplicate_names`	Get a list of duplicate names in the list.
`convert_x_unit`	Convert the x-axis unit of the ComponentCollection and all its components.
`convert_y_unit`	Convert the y-axis unit of the ComponentCollection and all its components.
`append_component`	Append a model component or the components from another ComponentCollection to this
`list_component_names`	List the names of all components in the model.
`get_fit_targets`	Get the fittable predictions of this collection as FitTargets.
`normalize_area`	Normalize the areas of all components so they sum to 1.
`get_all_variables`	Get all parameters from all model components.
`evaluate`	Evaluate the sum of all components.
`evaluate_component`	Evaluate a single component by name.
`fix_all_parameters`	Fix all free parameters in the model.
`free_all_parameters`	Free all fixed parameters in the model.
`to_dict`	Serialise the ComponentCollection to a dictionary.
`from_dict`	Deserialise a ComponentCollection from its dictionary representation.
`__copy__`	Create a deep copy of the ComponentCollection.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`is_empty`	`bool`	Check if the ComponentCollection has no components.

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`is_empty` `property` `writable`

Check if the ComponentCollection has no components.

Returns:

Type	Description
`bool`	True if the collection has no components, False otherwise.

Methods:

`get_all_parameters()`

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_fittable_parameters()`

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_free_parameters()`

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

Returns:

Type	Description
`List[Parameter]`	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.

`getitem(idx)`

Get an item by index, slice, or unique_name.

Parameters:

Name	Type	Description	Default
`idx`	`int \| slice \| str`	`Index, slice, or name of the item to get.`	required

Returns:

Type	Description
`ProtectedType_ \| EasyDynamicsList[ProtectedType_]`	The item at the specified index or name, or a new EasyDynamicsList if a slice is provided.

Raises:

Type	Description
`TypeError`	If idx is not an int, slice, or str.
`KeyError`	If idx is a str and no item with that name is found.
`AmbiguousNameError`	If idx is a str and multiple items with that name are found.

`setitem(idx, value)`

__setitem__(idx: int, value: ProtectedType_) -> None

__setitem__(
    idx: slice, value: Iterable[ProtectedType_]
) -> None

Set an item at an index.

Parameters:

Name	Type	Description	Default
`idx`	`int \| slice`	Index to set.	required
`value`	`ProtectedType_ \| Iterable[ProtectedType_]`	New value.	required

Raises:

Type	Description
`TypeError`	If `idx` or `value` has an invalid type.
`ValueError`	If slice assignment changes the slice length.

`delitem(idx)`

Delete an item by index, slice, or name.

Parameters:

Name	Type	Description	Default
`idx`	`int \| slice \| str`	Index, slice, or name of item to delete.	required

Raises:

Type	Description
`KeyError`	If `idx` is a string that does not match any item.
`TypeError`	If `idx` is not an int, slice, or string.

`len()`

Return the number of items in the collection.

`insert(index, value)`

Insert an item into the list at a specific index.

Parameters:

Name	Type	Description	Default
`index`	`int`	The index at which to insert the item.	required
`value`	`ProtectedType_`	The item to insert. Must be an instance of one of the protected types.	required

`sort(key=None, reverse=False)`

Sort the collection according to the given key function.

Parameters:

Name	Type	Description	Default
`key`	`Callable[[ProtectedType_], Any]`	Mapping function to sort by. By default, None.	`None`
`reverse`	`bool`	Whether to reverse the sort. By default, False.	`False`

`pop(index=-1)`

Remove and return an item at a specific index or name.

Parameters:

Name	Type	Description	Default
`index`	`int \| str`	The index or name at which to pop the item.	`-1`

Returns:

Type	Description
`ProtectedType_`	The item that was popped.

Raises:

Type	Description
`TypeError`	If index is not an int or str.
`KeyError`	If index is a str and no item with that name is found.

`append(value)`

Append an item to the end of the list.

Parameters:

Name	Type	Description	Default
`value`	`ProtectedType_`	The item to append. Must be an instance of one of the protected types.	required

`get_names()`

Get a list of the names of all items in the list.

Returns:

Type	Description
`list[str]`	A list of the names of all items in the list.

`get_duplicate_names()`

Get a list of duplicate names in the list.

Returns:

Type	Description
`list[str]`	A list of duplicate names in the list.

`convert_x_unit(new_x_unit)`

Convert the x-axis unit of the ComponentCollection and all its components.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	The target x-axis unit to convert to.	required

`convert_y_unit(new_y_unit)`

Convert the y-axis unit of the ComponentCollection and all its components.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	The target y-axis unit to convert to.	required

`append_component(component)`

Append a model component or the components from another ComponentCollection to this ComponentCollection.

Parameters:

Name	Type	Description	Default
`component`	`ModelComponent \| ComponentCollection`	The component to append. If a ComponentCollection is provided, all of its components will be appended.	required

`list_component_names()`

List the names of all components in the model.

Returns:

Type	Description
`list[str]`	List of names of the components in the collection.

`get_fit_targets()`

Get the fittable predictions of this collection as FitTargets.

Collections have a single prediction — their summed evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the collection's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this collection's evaluate.

`normalize_area()`

Normalize the areas of all components so they sum to 1.

This is useful for convolutions.

Raises:

Type	Description
`ValueError`	If there are no components in the model or if the total area is zero or not finite, which would prevent normalization.

`get_all_variables()`

Get all parameters from all model components.

Returns:

Type	Description
`list[DescriptorBase]`	List of parameters in the collection.

`evaluate(x, output='numpy')`

Evaluate the sum of all components.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Energy axis.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values.

`evaluate_component(x, name, output='numpy')`

Evaluate a single component by name.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Energy axis.	required
`name`	`str`	Component name.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If there are no components in the model.
`TypeError`	If name is not a string.
`KeyError`	If no component with the given name exists in the collection.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated values for the specified component.

`fix_all_parameters()`

Fix all free parameters in the model.

`free_all_parameters()`

Free all fixed parameters in the model.

`to_dict()`

Serialise the ComponentCollection to a dictionary.

Returns:

Type	Description
`dict`	Dictionary representation of the ComponentCollection.

`from_dict(obj_dict)` `classmethod`

Deserialise a ComponentCollection from its dictionary representation.

Parameters:

Name	Type	Description	Default
`obj_dict`	`dict`	Dictionary representation of the ComponentCollection, as produced by to_dict().	required

Returns:

Type	Description
`ComponentCollection`	The deserialised ComponentCollection.

`copy()`

Create a deep copy of the ComponentCollection.

Returns:

Type	Description
`ComponentCollection`	A deep copy of the ComponentCollection.

`DampedHarmonicOscillator(area=1.0, center=1.0, width=1.0, x_unit='meV', y_unit='dimensionless', name='DampedHarmonicOscillator', display_name=None, unique_name=None)`

Model of a Damped Harmonic Oscillator (DHO).

\[ I(x) = \frac{2 A x_0^2 \gamma}{\pi \left( (x^2 - x_0^2)^2 + (2\gamma x)^2 \right)} \]

where $A$ is the area (area), $x_0$ is the center (center), and $\gamma$ is the half width at half max (width). area has unit = x_unit * y_unit; center and width have unit = x_unit.

Examples:

Creating a Damped Harmonic Oscillator

The center parameter is the resonance frequency, which must be positive. Both phonon peaks (at ±center) are captured by the model:

import numpy as np
import easydynamics.sample_model as sm

dho = sm.DampedHarmonicOscillator(area=1.0, center=10.0, width=1.0)
x = np.linspace(-20, 20, 200)
values = dho.evaluate(x)

Modifying parameters after construction

import easydynamics.sample_model as sm

dho = sm.DampedHarmonicOscillator(area=2.0, center=5.0, width=0.5, name='Phonon')
dho.area = 3.0
dho.center = 8.0
dho.width = 0.3

Parameters:

Name	Type	Description	Default
`area`	`Numeric`	Integrated area under the DHO profile. Unit is `x_unit * y_unit`.	`1.0`
`center`	`Numeric`	Resonance frequency (x_0) in x_unit; approximately the peak position. Must be strictly positive; a minimum of `DHO_MINIMUM_CENTER` (1e-10) is enforced.	`1.0`
`width`	`Numeric`	Damping coefficient (gamma) in x_unit. Must be strictly positive. Approximately equal to the HWHM of each peak.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center and width are stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'DampedHarmonicOscillator'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`convert_x_unit`	Convert x-axis parameters (center, width) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis unit by rescaling the area parameter.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter (resonance frequency).
`width`	`Parameter`	Get the width parameter (damping coefficient).

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`area` `property` `writable`

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

`center` `property` `writable`

Get the center parameter (resonance frequency).

Returns:

Type	Description
`Parameter`	The resonance frequency (x_0) Parameter with unit `x_unit`.

`width` `property` `writable`

Get the width parameter (damping coefficient).

Returns:

Type	Description
`Parameter`	The damping coefficient (gamma) Parameter with unit `x_unit`.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_variables()`

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

`get_all_parameters()`

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_fittable_parameters()`

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_free_parameters()`

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

Returns:

Type	Description
`List[Parameter]`	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.

`get_fit_targets()`

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

`fix_all_parameters()`

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

`free_all_parameters()`

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

`evaluate(x, output='numpy')`

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`convert_x_unit(new_x_unit)`

Convert x-axis parameters (center, width) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

`convert_y_unit(new_y_unit)`

Convert the y-axis unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

`DeltaFunction(center=None, area=1.0, x_unit='meV', y_unit='dimensionless', name='DeltaFunction', display_name=None, unique_name=None)`

Delta function.

When called directly, returns zero everywhere except at the bin nearest to center, where it returns area / bin_width. In convolutions it acts as an identity element (handled by the Convolution class). area has unit = x_unit * y_unit; center has unit = x_unit.

If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Examples:

Creating a DeltaFunction (elastic line)

The DeltaFunction evaluates to zero everywhere when called directly. It acts as an identity in convolutions, making it useful for modelling the elastic line in QENS:

import numpy as np
import easydynamics.sample_model as sm

delta = sm.DeltaFunction(area=1.0)
x = np.linspace(-2, 2, 100)
values = delta.evaluate(x)  # all zeros except at the bin nearest to center

Creating a DeltaFunction with a free center

Pass a numeric value for center to place the elastic line at a specific energy transfer:

import easydynamics.sample_model as sm

delta = sm.DeltaFunction(area=0.7, center=0.5)
delta.area = 0.5

Parameters:

Name	Type	Description	Default
`center`	`Numeric \| None`	Position of the delta function in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`area`	`Numeric`	Integrated area (weight) of the delta function. Unit is `x_unit * y_unit`.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center is stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'DeltaFunction'`
`display_name`	`str \| None`	Display name of the component, shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`convert_x_unit`	Convert x-axis parameters (center) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis unit by rescaling the area parameter.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter.

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`area` `property` `writable`

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

`center` `property` `writable`

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center Parameter with unit `x_unit`.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_variables()`

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

`get_all_parameters()`

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_fittable_parameters()`

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_free_parameters()`

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

Returns:

Type	Description
`List[Parameter]`	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.

`get_fit_targets()`

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

`fix_all_parameters()`

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

`free_all_parameters()`

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

`evaluate(x, output='numpy')`

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`convert_x_unit(new_x_unit)`

Convert x-axis parameters (center) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

`convert_y_unit(new_y_unit)`

Convert the y-axis unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

`Exponential(amplitude=1.0, center=None, rate=1.0, x_unit='meV', y_unit='dimensionless', name='Exponential', display_name=None, unique_name=None)`

Model of an exponential function.

\[ I(x) = A e^{B (x-x_0)} \]

where $A$ is the amplitude, $x_0$ is the center, and $B$ is the rate. amplitude has unit = y_unit; center has unit = x_unit; rate has unit = 1/x_unit.

Examples:

Creating an Exponential with a fixed center

By default the center is fixed at 0. A negative rate gives a decaying exponential:

import numpy as np
import easydynamics.sample_model as sm

exp = sm.Exponential(amplitude=1.0, rate=-0.5)
x = np.linspace(0, 5, 100)
values = exp.evaluate(x)

Creating an Exponential with a free center and modifying parameters

Pass a numeric value for center to leave it free during fitting:

import easydynamics.sample_model as sm

exp = sm.Exponential(amplitude=2.0, center=1.0, rate=-1.0, name='Background')
exp.amplitude = 3.0
exp.rate = -0.5

Parameters:

Name	Type	Description	Default
`amplitude`	`Numeric`	Pre-exponential factor A. Unit is `y_unit`.	`1.0`
`center`	`Numeric \| None`	Reference point x_0 in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`rate`	`Numeric`	Exponential rate B in units of `1/x_unit`.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center is stored in this unit; rate is stored in `1/x_unit`.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output). amplitude is stored in this unit.	`'dimensionless'`
`name`	`str`	Name of the component.	`'Exponential'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Raises:

Type	Description
`TypeError`	If amplitude or rate is not numeric.
`ValueError`	If amplitude or rate is not finite.

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`convert_x_unit`	Convert center to new_x_unit and rate to 1/new_x_unit.
`convert_y_unit`	Convert the y-axis unit by rescaling the amplitude parameter.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`amplitude`	`Parameter`	Get the amplitude parameter.
`center`	`Parameter`	Get the center parameter.
`rate`	`Parameter`	Get the rate parameter.

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`amplitude` `property` `writable`

Get the amplitude parameter.

Returns:

Type	Description
`Parameter`	The amplitude Parameter with unit `y_unit`.

`center` `property` `writable`

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center (x_0) Parameter with unit `x_unit`.

`rate` `property` `writable`

Get the rate parameter.

Returns:

Type	Description
`Parameter`	The exponential rate (B) Parameter with unit `1/x_unit`.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_variables()`

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

`get_all_parameters()`

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_fittable_parameters()`

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_free_parameters()`

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

Returns:

Type	Description
`List[Parameter]`	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.

`get_fit_targets()`

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

`fix_all_parameters()`

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

`free_all_parameters()`

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

`evaluate(x, output='numpy')`

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`convert_x_unit(new_x_unit)`

Convert center to new_x_unit and rate to 1/new_x_unit.

The amplitude carries y_unit only and is unaffected.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit. The rate unit is set to `1/new_x_unit`.	required

`convert_y_unit(new_y_unit)`

Convert the y-axis unit by rescaling the amplitude parameter.

The amplitude is rescaled from old_y_unit to new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

`ExpressionComponent(expression, parameters=None, parameter_units=None, x_unit='meV', y_unit='dimensionless', name='Expression', display_name=None, unique_name=None)`

Model component defined by a symbolic expression.

The expression must contain x as the independent variable. All other symbols are treated as free parameters, which can be accessed and set as attributes after construction. Supported functions include exp, sin, cos, sqrt, erf, and others — see the _ALLOWED_FUNCS class variable for the full list.

Examples:

Defining a custom Gaussian expression

Parameters are given as a dictionary of initial values and can be accessed as attributes after construction:

import numpy as np
import easydynamics.sample_model as sm

expr = sm.ExpressionComponent(
    'A * exp(-(x - x0)**2 / (2*sigma**2))',
    parameters={'A': 10, 'x0': 0, 'sigma': 1},
    x_unit='meV',
    display_name='Gaussian Peak',
)
x = np.linspace(-3, 3, 100)
values = expr.evaluate(x)

Modifying parameter values after construction

Parameters can be set directly as attributes:

expr.A = 5
expr.sigma = 0.5

Giving parameters units

Parameters are dimensionless by default. Units can be given per parameter at construction, or relabelled later with set_unit (the numeric value is kept as-is). When units are in use, the unit of the evaluated expression is derived from the parameter units and x_unit (see output_unit), and a warning is issued if it does not match y_unit:

expr = sm.ExpressionComponent(
    'A * exp(-(x - x0)**2 / (2*sigma**2))',
    parameters={'A': 10, 'x0': 0, 'sigma': 1},
    parameter_units={'A': '1/meV', 'x0': 'meV', 'sigma': 'meV'},
    y_unit='1/meV',
)
expr.set_unit('A', '1/meV')

Physical constants

The symbols hbar (in meV*s) and kb (in meV/K) are provided automatically as read-only constants (DescriptorNumbers) when they appear in the expression:

boltzmann = sm.ExpressionComponent(
    'exp(-x / (kb * T))',
    parameters={'T': 300.0},
    parameter_units={'T': 'K'},
)

Use e.g. boltzmann.kb.convert_unit('eV/K') to work in another unit (this rescales the value, unlike set_unit).

Parameters:

Name	Type	Description	Default
`expression`	`str`	The symbolic expression as a string. Must contain 'x' as the independent variable. The symbols `hbar` and `kb` are provided automatically as read-only physical constants (in meVs and meV/K respectively) unless overridden via parameters*.	required
`parameters`	`dict[str, Numeric] \| None`	Dictionary of parameter names and their initial values. Parameters that are not given a unit are dimensionless.	`None`
`parameter_units`	`dict[str, str \| sc.Unit] \| None`	Optional units per parameter name. Each entry sets the unit of the named parameter without rescaling its value (see :meth:`set_unit`), and takes precedence over the unit of a Parameter instance given in parameters. When units are in use, a warning is issued if the expression's output unit does not match y_unit.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'Expression'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Unique name for the component.	`None`

Raises:

Type	Description
`ValueError`	If the expression is invalid or does not contain 'x', or if parameter_units names a parameter that is not in the expression.
`TypeError`	If any parameter value is not numeric, or if parameter_units is not a dictionary.

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`get_all_variables`	Return all parameters.
`set_unit`	Set the unit of a parameter without rescaling its value.
`convert_x_unit`	Convert the x-axis unit of the expression.
`convert_y_unit`	Convert the y-axis unit of the expression.
`__getattr__`	Allow access to parameters and physical constants as attributes.
`__setattr__`	Allow setting parameter values as attributes.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`expression`	`str`	Return the original expression string.
`constants`	`dict[str, DescriptorNumber]`	Get the physical constants used by the expression.
`output_unit`	`str`	Get the unit of the evaluated expression, derived from x_unit and the parameter units.

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`expression` `property` `writable`

Return the original expression string.

Returns:

Type	Description
`str`	The original expression string provided at initialization.

`constants` `property`

Get the physical constants used by the expression.

Returns:

Type	Description
`dict[str, DescriptorNumber]`	The automatically provided constants (e.g. `hbar`, `kb`) keyed by symbol name.

`output_unit` `property`

Get the unit of the evaluated expression, derived from x_unit and the parameter units.

The unit is propagated through the expression tree: addition requires compatible units, multiplication and powers combine units, and functions like exp or sin require a dimensionless argument. Propagation raises sc.UnitError if the expression is not unit-consistent (e.g. adding meV to a dimensionless quantity, or taking exp of a quantity with a unit).

Returns:

Type	Description
`str`	The unit of the evaluated expression.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_parameters()`

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_fittable_parameters()`

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_free_parameters()`

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

Returns:

Type	Description
`List[Parameter]`	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.

`get_fit_targets()`

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

`fix_all_parameters()`

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

`free_all_parameters()`

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

`evaluate(x, output='numpy')`

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`get_all_variables()`

Return all parameters.

Returns:

Type	Description
`list[Parameter]`	List of all parameters in the expression.

`set_unit(name, unit)`

Set the unit of a parameter without rescaling its value.

This relabels the unit: the numeric value, bounds, and variance are kept as-is. Use Parameter.convert_unit instead to rescale a value into a compatible unit. Issues a warning if the resulting output unit of the expression no longer matches y_unit. Raises the same exceptions as :meth:_relabel_parameter_unit on invalid input.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the parameter whose unit to set.	required
`unit`	`str \| sc.Unit`	The new unit.	required

`convert_x_unit(_new_unit)`

Convert the x-axis unit of the expression.

Unit conversion is not implemented for ExpressionComponent. Should it ever be needed, the viable path is dimensional analysis on the parameter units: for each parameter, determine the power n of the x-dimension in its unit and rescale its value by the x-unit conversion factor to the power n (the generalization of Polynomial's power-law rescaling). This only works when x_unit has a single unambiguous dimension.

Parameters:

Name	Type	Description	Default
`_new_unit`	`str \| sc.Unit`	The new unit to convert to (ignored).	required

Raises:

Type	Description
`NotImplementedError`	Always raised to indicate unit conversion is not supported.

`convert_y_unit(_new_unit)`

Convert the y-axis unit of the expression.

Unit conversion is not implemented for ExpressionComponent. See convert_x_unit for the approach that would make it possible.

Parameters:

Name	Type	Description	Default
`_new_unit`	`str \| sc.Unit`	The new unit to convert to (ignored).	required

Raises:

Type	Description
`NotImplementedError`	Always raised to indicate unit conversion is not supported.

`getattr(name)`

Allow access to parameters and physical constants as attributes.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the parameter or constant to access.	required

Raises:

Type	Description
`AttributeError`	If the parameter does not exist.

Returns:

Type	Description
`Parameter \| DescriptorNumber`	The parameter or constant with the given name.

`setattr(name, value)`

Allow setting parameter values as attributes.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the parameter to set.	required
`value`	`Numeric`	New value for the parameter.	required

Raises:

Type	Description
`AttributeError`	If the name refers to a physical constant.
`TypeError`	If the value is not numeric.

`Gaussian(area=1.0, center=None, width=1.0, x_unit='meV', y_unit='dimensionless', name='Gaussian', display_name=None, unique_name=None)`

Model of a Gaussian function.

\[ I(x) = \frac{A}{\sigma \sqrt{2\pi}} \exp\left( -\frac{1}{2} \left(\frac{x - x_0}{\sigma}\right)^2 \right) \]

where $A$ is the area, $x_0$ is the center, and $\sigma$ is the width. area has unit = x_unit * y_unit; center and width have unit = x_unit.

If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Examples:

Creating a Gaussian with a fixed center (typical QENS use)

By default the center is fixed at 0, which is the typical setup for a QENS elastic line:

import numpy as np
import easydynamics.sample_model as sm

g = sm.Gaussian(area=1.0, width=0.5)
x = np.linspace(-2, 2, 100)
values = g.evaluate(x)

Creating a Gaussian with a free center and modifying parameters

Pass a numeric value for center to leave it free during fitting, and use the property setters to update parameter values after construction:

import easydynamics.sample_model as sm

g = sm.Gaussian(area=2.0, center=0.5, width=0.3, name='Peak')
g.area = 3.0
g.width = 0.2

Parameters:

Name	Type	Description	Default
`area`	`Numeric`	Integrated area under the Gaussian. Unit is `x_unit * y_unit`.	`1.0`
`center`	`Numeric \| None`	Peak position in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`width`	`Numeric`	Standard deviation (sigma) in x_unit. Must be strictly positive.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center and width are stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'Gaussian'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`convert_x_unit`	Convert x-axis parameters (center, width) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis (output) unit by rescaling the area parameter.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter.
`width`	`Parameter`	Get the width parameter (sigma).

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`area` `property` `writable`

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

`center` `property` `writable`

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center Parameter with unit `x_unit`.

`width` `property` `writable`

Get the width parameter (sigma).

Returns:

Type	Description
`Parameter`	The width (sigma) Parameter with unit `x_unit`.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_variables()`

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

`get_all_parameters()`

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_fittable_parameters()`

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_free_parameters()`

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

Returns:

Type	Description
`List[Parameter]`	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.

`get_fit_targets()`

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

`fix_all_parameters()`

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

`free_all_parameters()`

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

`evaluate(x, output='numpy')`

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`convert_x_unit(new_x_unit)`

Convert x-axis parameters (center, width) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

`convert_y_unit(new_y_unit)`

Convert the y-axis (output) unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

`Lorentzian(area=1.0, center=None, width=1.0, x_unit='meV', y_unit='dimensionless', name='Lorentzian', display_name=None, unique_name=None)`

Model of a Lorentzian function.

\[ I(x) = \frac{A}{\pi} \frac{\Gamma}{(x - x_0)^2 + \Gamma^2} \]

where $A$ is the area, $x_0$ is the center, and $\Gamma$ is the hald width at half max (HWHM). area has unit = x_unit * y_unit; center and width have unit = x_unit.

If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Examples:

Creating a Lorentzian with a fixed center (typical QENS use)

By default the center is fixed at 0, which is the typical setup for a QENS quasi-elastic line:

import numpy as np
import easydynamics.sample_model as sm

l = sm.Lorentzian(area=1.0, width=0.3)
x = np.linspace(-2, 2, 100)
values = l.evaluate(x)

Creating a Lorentzian with a free center and modifying parameters

Pass a numeric value for center to leave it free during fitting:

import easydynamics.sample_model as sm

l = sm.Lorentzian(area=2.0, center=0.5, width=0.3, name='QE peak')
l.area = 3.0
l.width = 0.2

Parameters:

Name	Type	Description	Default
`area`	`Numeric`	Integrated area under the Lorentzian. Unit is `x_unit * y_unit`.	`1.0`
`center`	`Numeric \| None`	Peak position in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`width`	`Numeric`	Half-width at half-maximum (HWHM, gamma) in x_unit. Must be strictly positive.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center and width are stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'Lorentzian'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`convert_x_unit`	Convert x-axis parameters (center, width) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis (output) unit by rescaling the area parameter.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter.
`width`	`Parameter`	Get the width parameter (HWHM).

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`area` `property` `writable`

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

`center` `property` `writable`

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center Parameter with unit `x_unit`.

`width` `property` `writable`

Get the width parameter (HWHM).

Returns:

Type	Description
`Parameter`	The HWHM (gamma) Parameter with unit `x_unit`.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_variables()`

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

`get_all_parameters()`

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_fittable_parameters()`

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_free_parameters()`

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

Returns:

Type	Description
`List[Parameter]`	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.

`get_fit_targets()`

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

`fix_all_parameters()`

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

`free_all_parameters()`

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

`evaluate(x, output='numpy')`

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`convert_x_unit(new_x_unit)`

Convert x-axis parameters (center, width) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

`convert_y_unit(new_y_unit)`

Convert the y-axis (output) unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

`Polynomial(coefficients=(0.0,), x_unit='meV', y_unit='dimensionless', name='Polynomial', display_name=None, unique_name=None, suppress_warnings=False)`

Polynomial function component.

\[ I(x) = c_0 + c_1 x + c_2 x^2 + ... + c_N x^N \]

Coefficients are stored as dimensionless Parameters. When x_unit changes, the coefficient values are rescaled so the evaluated result stays the same. The output unit is y_unit.

Examples:

Creating a constant background (degree 0)

import numpy as np
import easydynamics.sample_model as sm

poly = sm.Polynomial(coefficients=[1.5])
x = np.linspace(-5, 5, 100)
values = poly.evaluate(x)

Creating a linear background (degree 1)

Coefficients are ordered as [c0, c1, ...], where c0 is the constant term:

import easydynamics.sample_model as sm

poly = sm.Polynomial(coefficients=[2.0, 0.1], name='Background')
poly.coefficients = [1.5, 0.05]

Creating a sparse polynomial from a dict

Powers that are not listed are filled with coefficients fixed to zero:

import easydynamics.sample_model as sm

poly = sm.Polynomial(coefficients={2: 1.5})  # 1.5*x^2, with c0 and c1 fixed at 0

Changing the degree after construction

import easydynamics.sample_model as sm

poly = sm.Polynomial(coefficients=[2.0, 0.1])
poly.add_coefficient(0.05)  # now 2.0 + 0.1*x + 0.05*x^2
removed = poly.remove_coefficient()  # returns 0.05, back to 2.0 + 0.1*x

coefficients : _CoefficientsInput, default=(0.0,) Either an ordered sequence of polynomial coefficients [c0, c1, ..., cN] where the polynomial is c0 + c1*x + c2*x^2 + ... + cN*x^N, or a sparse dict mapping integer powers to numeric values (e.g. {2: 1.5} for 1.5*x^2).

For a sequence, each element may be a plain numeric value (wrapped into a dimensionless
:class:`Parameter`) or an existing :class:`Parameter` instance.  For a dict, powers not
present are filled with fixed-to-zero Parameters, and the degree is taken from the
largest key.  Must contain at least one element.

x_unit : str | sc.Unit, default='meV' Unit of the x-axis. When the x_unit is changed via :meth:convert_x_unit, coefficient values are rescaled by power-law factors so the evaluated output remains unchanged. y_unit : str | sc.Unit, default='dimensionless' Unit of the y-axis (output). name : str, default='Polynomial' Name of the component. display_name : str | None, default=None Display name shown when plotting. Falls back to name if None. unique_name : str | None, default=None Globally unique identifier. Auto-generated if None. suppress_warnings : bool, default=False Whether to suppress warnings

Raises:

Type	Description
`TypeError`	If coefficients is not a list, tuple, ndarray, or dict, if any sequence element is neither numeric nor a :class:`Parameter`, or if any dict key is not an integer or dict value is not numeric.
`ValueError`	If coefficients is empty, or if any dict key is negative.

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`coefficient_values`	Get the coefficients of the polynomial as a list.
`add_coefficient`	Add a new coefficient at the next highest power, increasing the degree by one.
`remove_coefficient`	Remove the highest-power coefficient, decreasing the degree by one.
`get_all_variables`	Returns
`convert_x_unit`	Convert the x-axis unit by rescaling coefficients with power-law factors.
`convert_y_unit`	Rescale all coefficients so the evaluated output remains the same physical value.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`suppress_warnings`	`bool`	Get whether or not to suppress warnings.
`coefficients`	`list[Parameter]`	Get the coefficients of the polynomial as a list of Parameters.
`degree`	`int`	Returns

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`suppress_warnings` `property` `writable`

Get whether or not to suppress warnings.

`coefficients` `property` `writable`

Get the coefficients of the polynomial as a list of Parameters.

Returns:

Type	Description
`list[Parameter]`	A shallow copy of the internal coefficient list `[c0, c1, ..., cN]`. Modifying the returned list does not affect the model; use the setter to replace values.

`degree` `property` `writable`

Returns:

Type	Description
`int`	Polynomial degree, equal to `len(coefficients) - 1`.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_parameters()`

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_fittable_parameters()`

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_free_parameters()`

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

Returns:

Type	Description
`List[Parameter]`	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.

`get_fit_targets()`

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

`fix_all_parameters()`

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

`free_all_parameters()`

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

`evaluate(x, output='numpy')`

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`coefficient_values()`

Get the coefficients of the polynomial as a list.

Returns:

Type	Description
`list[float]`	Current numeric values of all coefficients `[c0.value, c1.value, ..., cN.value]`.

`add_coefficient(value=0.0, fixed=False)`

Add a new coefficient at the next highest power, increasing the degree by one.

Parameters:

Name	Type	Description	Default
`value`	`Numeric`	The numeric value of the new coefficient.	`0.0`
`fixed`	`bool`	If True, the new coefficient is fixed (not free for fitting).	`False`

Raises:

Type	Description
`TypeError`	If value is not a numeric value.

`remove_coefficient()`

Remove the highest-power coefficient, decreasing the degree by one.

Returns:

Type	Description
`float`	The value of the removed coefficient.

Raises:

Type	Description
`ValueError`	If only one coefficient remains; a Polynomial must always keep at least one.

`get_all_variables()`

Returns:

Type	Description
`list[DescriptorBase]`	The coefficient Parameters that constitute the fittable variables of this polynomial component.

`convert_x_unit(new_x_unit)`

Convert the x-axis unit by rescaling coefficients with power-law factors.

Each coefficient c_i is rescaled by (old_scale / new_scale) ** i so the evaluated polynomial output is unchanged after the conversion.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

Raises:

Type	Description
`UnitError`	If new_x_unit is not a valid unit string or `sc.Unit`, or if the conversion between the current unit and new_x_unit fails.

`convert_y_unit(new_y_unit)`

Rescale all coefficients so the evaluated output remains the same physical value.

All coefficients are multiplied by the conversion factor from old_y_unit to new_y_unit so that I(x) [new_y_unit] represents the same physical quantity as I(x) [old_y_unit].

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit. Must be dimensionally compatible with the current y_unit.	required

Raises:

Type	Description
`UnitError`	If new_y_unit is not a valid unit string or `sc.Unit`, or if the conversion between the current y_unit and new_y_unit fails.

`Voigt(area=1.0, center=None, gaussian_width=1.0, lorentzian_width=1.0, x_unit='meV', y_unit='dimensionless', name='Voigt', display_name=None, unique_name=None)`

Voigt profile — convolution of Gaussian and Lorentzian.

Uses scipy.special.voigt_profile to evaluate the profile. area has unit = x_unit * y_unit; center, gaussian_width, and lorentzian_width have unit = x_unit.

If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Examples:

Creating a Voigt profile with a fixed center (typical QENS use)

The Voigt profile is a convolution of a Gaussian and a Lorentzian. By default the center is fixed at 0:

import numpy as np
import easydynamics.sample_model as sm

v = sm.Voigt(area=1.0, gaussian_width=0.1, lorentzian_width=0.3)
x = np.linspace(-2, 2, 100)
values = v.evaluate(x)

Setting the Gaussian and Lorentzian widths independently

Pass a numeric value for center to leave it free during fitting, and use the property setters to adjust the two width components after construction:

import easydynamics.sample_model as sm

v = sm.Voigt(area=2.0, center=0.5, gaussian_width=0.2, lorentzian_width=0.4, name='Peak')
v.gaussian_width = 0.1
v.lorentzian_width = 0.2

Parameters:

Name	Type	Description	Default
`area`	`Numeric \| Parameter`	Integrated area under the Voigt profile. Unit is `x_unit * y_unit`.	`1.0`
`center`	`Numeric \| Parameter \| None`	Peak position in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`gaussian_width`	`Numeric \| Parameter`	Gaussian component standard deviation (sigma) in x_unit. Must be strictly positive.	`1.0`
`lorentzian_width`	`Numeric \| Parameter`	Lorentzian component HWHM (gamma) in x_unit. Must be strictly positive.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center, gaussian_width, and lorentzian_width are stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'Voigt'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`convert_x_unit`	Convert x-axis parameters (center, widths) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis unit by rescaling the area parameter.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter.
`gaussian_width`	`Parameter`	Get the Gaussian width parameter (sigma).
`lorentzian_width`	`Parameter`	Get the Lorentzian width parameter (HWHM).

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`area` `property` `writable`

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

`center` `property` `writable`

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center Parameter with unit `x_unit`.

`gaussian_width` `property` `writable`

Get the Gaussian width parameter (sigma).

Returns:

Type	Description
`Parameter`	The Gaussian component width (sigma) Parameter with unit `x_unit`.

`lorentzian_width` `property` `writable`

Get the Lorentzian width parameter (HWHM).

Returns:

Type	Description
`Parameter`	The Lorentzian component HWHM (gamma) Parameter with unit `x_unit`.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_variables()`

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

`get_all_parameters()`

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_fittable_parameters()`

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_free_parameters()`

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

Returns:

Type	Description
`List[Parameter]`	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.

`get_fit_targets()`

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

`fix_all_parameters()`

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

`free_all_parameters()`

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

`evaluate(x, output='numpy')`

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`convert_x_unit(new_x_unit)`

Convert x-axis parameters (center, widths) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

`convert_y_unit(new_y_unit)`

Convert the y-axis unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

`BrownianTranslationalDiffusion(scale=1.0, diffusion_coefficient=1.0, Q=None, x_unit='meV', y_unit='dimensionless', name='BrownianTranslationalDiffusion', display_name='BrownianTranslationalDiffusion', lorentzian_name=None, lorentzian_display_name=None, unique_name=None)`

Model of Brownian translational diffusion, consisting of a Lorentzian function for each Q-value, where the width is given by $D Q^2$, where $D$ is the diffusion coefficient. The area of the Lorentzians is given by the scale parameter multiplied by the QISF, which is 1 for this model. The EISF is 0 for this model, so there is no delta function component. Q is assumed to have units of 1/angstrom. Creates ComponentCollections with Lorentzian components for given Q-values.

Examples:

Creating a BrownianTranslationalDiffusion model

The model creates one Lorentzian per Q-value, with width $D Q^2$. Pass Q values at construction or later via create_component_collections:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
diffusion_model = sm.BrownianTranslationalDiffusion(
    scale=1.0,
    diffusion_coefficient=2.4e-9,
    Q=Q,
)
component_collections = diffusion_model.create_component_collections()

See also the tutorials.

Parameters:

Name	Type	Description	Default
`scale`	`Numeric`	Scale factor for the diffusion model. Must be a non-negative number.	`1.0`
`diffusion_coefficient`	`Numeric`	Diffusion coefficient D in m^2/s.	`1.0`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis (energy/frequency). Must be convertible to meV.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity). Determines scale.unit = x_unit * y_unit.	`'dimensionless'`
`name`	`str`	Name of the diffusion model.	`'BrownianTranslationalDiffusion'`
`display_name`	`str \| None`	Display name of the diffusion model.	`'BrownianTranslationalDiffusion'`
`lorentzian_name`	`str \| None`	Name of the Lorentzian component. If None, it will be set to the name of the diffusion model.	`None`
`lorentzian_display_name`	`str \| None`	Display name of the Lorentzian component. If None, it will be set to the lorentzian_name.	`None`
`unique_name`	`str \| None`	Unique name of the diffusion model. If None, a unique name will be generated. By default, None.	`None`

Raises:

Type	Description
`TypeError`	If scale or diffusion_coefficient is not a number.
`ValueError`	If scale or diffusion_coefficient is negative.

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`get_all_variables`	Get all variables from the diffusion model.
`get_all_parameters`	Get all Parameters from the diffusion model.
`get_fittable_parameters`	Get all fittable Parameters from the diffusion model.
`get_free_parameters`	Get all free Parameters from the diffusion model.
`get_fit_parameters`	Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of the diffusion model.
`convert_y_unit`	Convert the y-axis unit of the diffusion model.
`get_fit_targets`	Get the fittable predictions of the diffusion model as FitTargets.
`get_global_variables`	Get all global variables from the diffusion model.
`get_independent_variables`	Get the independent variables from the diffusion model. If Q_index is provided, only the
`get_component_collections`	Get the ComponentCollection at the given Q index.
`calculate_width`	Calculate the half-width at half-maximum (HWHM) for the diffusion model.
`calculate_EISF`	Calculate the Elastic Incoherent Structure Factor (EISF) for the Brownian translational
`calculate_QISF`	Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).
`create_component_collections`	Create ComponentCollection components for the Brownian translational diffusion model at

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`scale`	`Parameter`	Get the scale parameter of the diffusion model.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.
`lorentzian_name`	`str`	Get the name of the Lorentzian component.
`lorentzian_display_name`	`str \| None`	Get the display name of the Lorentzian component.
`diffusion_coefficient`	`Parameter`	Get the diffusion coefficient parameter D.

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`scale` `property` `writable`

Get the scale parameter of the diffusion model.

Returns:

Type	Description
`Parameter`	Scale parameter of the diffusion model.

`Q` `property` `writable`

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

`lorentzian_name` `property` `writable`

Get the name of the Lorentzian component.

Returns:

Type	Description
`str`	Name of the Lorentzian component.

`lorentzian_display_name` `property` `writable`

Get the display name of the Lorentzian component.

Returns:

Type	Description
`str \| None`	Display name of the Lorentzian component, or None if not set.

`diffusion_coefficient` `property` `writable`

Get the diffusion coefficient parameter D.

Returns:

Type	Description
`Parameter`	Diffusion coefficient D in m^2/s.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_variables(Q_index=None)`

Get all variables from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get variables from. If None, all variables from all ComponentCollections are returned, in addition to the global variables.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

`get_all_parameters(Q_index=None)`

Get all Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get parameters from. If None, all parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

`get_fittable_parameters(Q_index=None)`

Get all fittable Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fittable parameters from. If None, all fittable parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fittable Parameters from the diffusion model.

`get_free_parameters(Q_index=None)`

Get all free Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get free parameters from. If None, all free parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all free Parameters from the diffusion model.

`get_fit_parameters(Q_index=None)`

Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fit parameters from. If None, all fit parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fit Parameters from the diffusion model.

`clear_Q(confirm=False)`

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

`convert_x_unit(unit)`

Convert the x-axis unit of the diffusion model.

Converts the scale parameter (unit x_unit * y_unit), any subclass-specific x-unit parameters, and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. Only energy units are supported (the unit must be convertible to meV).

Unit validation raises UnitError when the unit is not convertible to meV. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

`convert_y_unit(unit)`

Convert the y-axis unit of the diffusion model.

Converts the scale parameter from x_unit * old_y_unit to x_unit * new_y_unit and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. The new y-unit must be dimensionally compatible with the current one; the scale conversion raises UnitError otherwise. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

`get_fit_targets()`

Get the fittable predictions of the diffusion model as FitTargets.

The base implementation declares 'area' (scale * QISF(Q)) and 'width' (the HWHM Gamma(Q)), with default dataset keys derived from the Lorentzian component's name. Subclasses with additional predictions (e.g. a delta-function weight) extend this list. The targets are snapshots: units and default keys reflect the model state at call time.

Returns:

Type	Description
`list[FitTarget]`	The fittable predictions of this model.

`get_global_variables()`

Get all global variables from the diffusion model.

Returns:

Type	Description
`list[Parameter]`	A list of all global variables from the diffusion model.

`get_independent_variables(Q_index=None)`

Get the independent variables from the diffusion model. If Q_index is provided, only the independent variables for the specified Q value will be returned. If Q_index is None, independent variables for all Q values will be returned. These are variables that are not global but also not part of the component collections.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value for which to get the independent variables. If None, independent variables for all Q values will be included.	`None`

Returns:

Type	Description
`list[Parameter]`	List of independent variables in the model.

`get_component_collections(Q_index=None)`

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the desired ComponentCollection. If None, all ComponentCollections are returned.	`None`

Returns:

Type	Description
`ComponentCollection \| list[ComponentCollection]`	The ComponentCollection at the specified Q index. If Q_index is None, a list of all ComponentCollections is returned.

`calculate_width(Q=None)`

Calculate the half-width at half-maximum (HWHM) for the diffusion model.

Parameters:

Name	Type	Description	Default
`Q`	`Q_type \| None`	Scattering vector in 1/angstrom.	`None`

Returns:

Type	Description
`np.ndarray`	HWHM values in the unit of the model (e.g., meV).

`calculate_EISF(Q=None)`

Calculate the Elastic Incoherent Structure Factor (EISF) for the Brownian translational diffusion model.

Parameters:

Name	Type	Description	Default
`Q`	`Q_type \| None`	Scattering vector in 1/angstrom.	`None`

Returns:

Type	Description
`np.ndarray`	EISF values (dimensionless).

`calculate_QISF(Q=None)`

Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

Parameters:

Name	Type	Description	Default
`Q`	`Q_type \| None`	Scattering vector in 1/angstrom.	`None`

Returns:

Type	Description
`np.ndarray`	QISF values (dimensionless).

`create_component_collections()`

Create ComponentCollection components for the Brownian translational diffusion model at given Q values.

Returns:

Type	Description
`list[ComponentCollection]`	List of ComponentCollections with Lorentzian components for each Q value. Each Lorentzian has a width given by $D*Q^2$ and an area given by the scale parameter multiplied by the QISF (which is 1 for this model).

`DeltaLorentz(scale=1.0, mean_u_squared=0.0, A_0=1.0, lorentzian_width=1.0, allow_Q_variation=None, Q=None, x_unit='meV', y_unit='dimensionless', name='DeltaLorentz', display_name=None, lorentzian_name='Lorentzian', lorentzian_display_name=None, delta_name='Delta function', delta_display_name=None, unique_name=None)`

Model of Delta function and Lorentzian with intensities given by the Debye-Waller factor. $$ I = K \exp \left( \frac{-\langle u^2 \rangle Q^2}{3} \right)[A_0 \delta(E) + (A_1) L(E, \Gamma)] $$,

where $K$ is the scale factor, $\langle u^2 \rangle$ is the mean square displacement, $Q$ is the scattering vector, $A_0$ and $A_1$ are the relative amplitudes of the delta function and Lorentzian, respectively, with the constraint that $A_0+A_1=1$, and $L(E, \Gamma)$ is the Lorentzian function with width $\Gamma$. $A_0$, $A_1$ and the width of the Lorentzian can be the same at all $Q$ or be allowed to vary with $Q$.

Examples:

Creating a DeltaLorentz model with Q-dependent parameters

Set allow_Q_variation to allow individual parameters to vary with Q:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
model = sm.DeltaLorentz(
    display_name='DiffusionModel',
    scale=1.0,
    mean_u_squared=0.02,
    A_0=0.7,
    lorentzian_width=1.0,
    allow_Q_variation={'A_0': True, 'lorentzian_width': True},
    Q=Q,
)
component_collections = model.create_component_collections()

See also the tutorials.

Parameters:

Name	Type	Description	Default
`scale`	`Numeric`	Scale factor for the diffusion model. Must be a non-negative number.	`1.0`
`mean_u_squared`	`Numeric`	Mean square displacement in angstrom^2.	`0.0`
`A_0`	`Numeric`	Amplitude of the delta function.	`1.0`
`lorentzian_width`	`Numeric`	Width of the Lorentzian function.	`1.0`
`allow_Q_variation`	`dict \| None`	Dict describing whether to allow Q variation of A_0 and the Lorentzian width. The dict can have the keys "A_0" and/or "lorentzian_width", with boolean values indicating whether to allow Q-dependence for each parameter. If None, no Q-dependence will be allowed.	`None`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis (energy/frequency). Must be convertible to meV.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity). Determines scale.unit = x_unit * y_unit.	`'dimensionless'`
`name`	`str`	Name of the diffusion model.	`'DeltaLorentz'`
`display_name`	`str \| None`	Display name of the diffusion model.	`None`
`lorentzian_name`	`str`	Name of the Lorentzian component. If None, it will be set to the name of the diffusion model.	`'Lorentzian'`
`lorentzian_display_name`	`str \| None`	Display name of the Lorentzian component. If None, it will be set to the display name of the diffusion model.	`None`
`delta_name`	`str`	Name of the delta function component.	`'Delta function'`
`delta_display_name`	`str \| None`	Display name of the delta function component. If None, it will be set to the display name of the delta function component.	`None`
`unique_name`	`str \| None`	Unique name of the diffusion model. If None, a unique name will be generated. By default, None.	`None`

Raises:

Type	Description
`TypeError`	If delta_name is not a string or if delta_display_name is not a string or None.

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`get_all_parameters`	Get all Parameters from the diffusion model.
`get_fittable_parameters`	Get all fittable Parameters from the diffusion model.
`get_free_parameters`	Get all free Parameters from the diffusion model.
`get_fit_parameters`	Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of the diffusion model.
`convert_y_unit`	Convert the y-axis unit of the diffusion model.
`get_component_collections`	Get the ComponentCollection at the given Q index.
`calculate_width`	Calculate the half-width at half-maximum (HWHM) for the diffusion model. If the width is
`calculate_EISF`	Calculate the Elastic Incoherent Structure Factor (EISF) for the diffusion model.
`calculate_QISF`	Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).
`create_component_collections`	Create ComponentCollections for the DeltaLorentz model at given Q values.
`get_fit_targets`	Get the fittable predictions of the DeltaLorentz model as FitTargets.
`get_global_variables`	Get all global variables from the diffusion model.
`get_independent_variables`	Get the independent variables from the diffusion model. If Q_index is provided, only the
`get_all_variables`	Get a list of all variables (Parameters and Descriptors) in the model.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`scale`	`Parameter`	Get the scale parameter of the diffusion model.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.
`lorentzian_name`	`str`	Get the name of the Lorentzian component.
`lorentzian_display_name`	`str \| None`	Get the display name of the Lorentzian component.
`mean_u_squared`	`Parameter`	Get the mean square displacement parameter.
`A_0`	`Parameter`	Get the amplitude of the delta function.
`A_1`	`Parameter`	Get the amplitude of the Lorentzian function.
`lorentzian_width`	`Parameter`	Get the width of the Lorentzian function.
`delta_name`	`str`	Get the name of the delta function component.
`delta_display_name`	`str`	Get the display name of the delta function component.

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`scale` `property` `writable`

Get the scale parameter of the diffusion model.

Returns:

Type	Description
`Parameter`	Scale parameter of the diffusion model.

`Q` `property` `writable`

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

`lorentzian_name` `property` `writable`

Get the name of the Lorentzian component.

Returns:

Type	Description
`str`	Name of the Lorentzian component.

`lorentzian_display_name` `property` `writable`

Get the display name of the Lorentzian component.

Returns:

Type	Description
`str \| None`	Display name of the Lorentzian component, or None if not set.

`mean_u_squared` `property` `writable`

Get the mean square displacement parameter.

Returns:

Type	Description
`Parameter`	Mean square displacement in angstrom^2.

`A_0` `property` `writable`

Get the amplitude of the delta function.

Returns:

Type	Description
`Parameter`	Amplitude of the delta function.

`A_1` `property` `writable`

Get the amplitude of the Lorentzian function.

Returns:

Type	Description
`Parameter`	Amplitude of the Lorentzian function.

`lorentzian_width` `property` `writable`

Get the width of the Lorentzian function.

Returns:

Type	Description
`Parameter`	Width of the Lorentzian function.

`delta_name` `property` `writable`

Get the name of the delta function component.

Returns:

Type	Description
`str`	Name of the delta function component.

`delta_display_name` `property` `writable`

Get the display name of the delta function component.

Returns:

Type	Description
`str`	Display name of the delta function component.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_parameters(Q_index=None)`

Get all Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get parameters from. If None, all parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

`get_fittable_parameters(Q_index=None)`

Get all fittable Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fittable parameters from. If None, all fittable parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fittable Parameters from the diffusion model.

`get_free_parameters(Q_index=None)`

Get all free Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get free parameters from. If None, all free parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all free Parameters from the diffusion model.

`get_fit_parameters(Q_index=None)`

Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fit parameters from. If None, all fit parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fit Parameters from the diffusion model.

`clear_Q(confirm=False)`

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

`convert_x_unit(unit)`

Convert the x-axis unit of the diffusion model.

Converts the scale parameter (unit x_unit * y_unit), any subclass-specific x-unit parameters, and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. Only energy units are supported (the unit must be convertible to meV).

Unit validation raises UnitError when the unit is not convertible to meV. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

`convert_y_unit(unit)`

Convert the y-axis unit of the diffusion model.

Converts the scale parameter from x_unit * old_y_unit to x_unit * new_y_unit and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. The new y-unit must be dimensionally compatible with the current one; the scale conversion raises UnitError otherwise. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

`get_component_collections(Q_index=None)`

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the desired ComponentCollection. If None, all ComponentCollections are returned.	`None`

Returns:

Type	Description
`ComponentCollection \| list[ComponentCollection]`	The ComponentCollection at the specified Q index. If Q_index is None, a list of all ComponentCollections is returned.

`calculate_width(Q=None)`

Calculate the half-width at half-maximum (HWHM) for the diffusion model. If the width is allowed to vary with Q then the requested Q values are matched against the Q stored in the model and the corresponding per-Q widths are returned. If the width is not allowed to vary then the same width is returned for all Q values.

Parameters:

Name	Type	Description	Default
`Q`	`Q_type`	Scattering vector in 1/angstrom. If None, the Q stored in the model is used.	`None`

Returns:

Type	Description
`np.ndarray`	HWHM values in the unit of the model (e.g., meV).

Raises:

Type	Description
`ValueError`	If Q-variation is enabled but Q has not been set on the model yet, or if the requested Q values do not match the stored ones.

`calculate_EISF(Q=None)`

Calculate the Elastic Incoherent Structure Factor (EISF) for the diffusion model.

Parameters:

Name	Type	Description	Default
`Q`	`Q_type`	Scattering vector in 1/angstrom.	`None`

Returns:

Type	Description
`np.ndarray`	EISF values (dimensionless).

`calculate_QISF(Q=None)`

Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

Parameters:

Name	Type	Description	Default
`Q`	`Q_type`	Scattering vector in 1/angstrom.	`None`

Returns:

Type	Description
`np.ndarray`	QISF values (dimensionless).

`create_component_collections()`

Create ComponentCollections for the DeltaLorentz model at given Q values.

Returns:

Type	Description
`list[ComponentCollection]`	List of ComponentCollections with Lorentzian and delta function components for each Q value.

`get_fit_targets()`

Get the fittable predictions of the DeltaLorentz model as FitTargets.

Extends the base 'area' and 'width' predictions with 'delta_area' (scale * EISF(Q), the delta function's weight), whose default dataset key is derived from the delta component's name.

Returns:

Type	Description
`list[FitTarget]`	The fittable predictions of this model.

`get_global_variables()`

Get all global variables from the diffusion model.

Returns:

Type	Description
`list[Parameter]`	A list of all global variables from the diffusion model.

`get_independent_variables(Q_index=None)`

Get the independent variables from the diffusion model. If Q_index is provided, only the independent variables for the specified Q value will be returned. If Q_index is None, independent variables for all Q values will be returned.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value for which to get the independent variables. If None, independent variables for all Q values will be included.	`None`

Returns:

Type	Description
`list[Parameter]`	List of independent variables in the model.

`get_all_variables(Q_index=None)`

Get a list of all variables (Parameters and Descriptors) in the model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value for which to get the variables. If None, variables for all Q values will be included.	`None`

Returns:

Type	Description
`list[DescriptorNumber]`	List of all variables in the model.

`JumpTranslationalDiffusion(scale=1.0, diffusion_coefficient=1.0, relaxation_time=1.0, Q=None, x_unit='meV', y_unit='dimensionless', name='JumpTranslationalDiffusion', display_name='JumpTranslationalDiffusion', lorentzian_name=None, lorentzian_display_name=None, unique_name=None)`

Model of Jump translational diffusion.

The model consists of a Lorentzian function for each Q-value, where the width is given by

\[ \Gamma(Q) = \frac{Q^2}{1+D t Q^2}. \]

where $D$ is the diffusion coefficient and $t$ is the relaxation time. Q is assumed to have units of 1/angstrom. Creates ComponentCollections with Lorentzian components for given Q-values.

Examples:

Creating a JumpTranslationalDiffusion model

Pass the diffusion coefficient (in m²/s) and relaxation time (in ps) along with Q values:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
diffusion_model = sm.JumpTranslationalDiffusion(
    scale=1.0,
    diffusion_coefficient=2.4e-9,
    relaxation_time=1.0,
    Q=Q,
)
component_collections = diffusion_model.create_component_collections()

See also the tutorials.

Parameters:

Name	Type	Description	Default
`scale`	`Numeric`	Scale factor for the diffusion model. Must be a non-negative number.	`1.0`
`diffusion_coefficient`	`Numeric`	Diffusion coefficient D in m^2/s.	`1.0`
`relaxation_time`	`Numeric`	Relaxation time t in ps.	`1.0`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis (energy/frequency). Must be convertible to meV.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity). Determines scale.unit = x_unit * y_unit.	`'dimensionless'`
`name`	`str`	Name of the diffusion model.	`'JumpTranslationalDiffusion'`
`display_name`	`str \| None`	Display name of the diffusion model.	`'JumpTranslationalDiffusion'`
`lorentzian_name`	`str \| None`	Name of the Lorentzian component. If None, it will be set to the name of the diffusion model with '_Lorentzian' appended. By default, None.	`None`
`lorentzian_display_name`	`str \| None`	Display name of the Lorentzian component. If None, it will be set to the display name of the diffusion model with '_Lorentzian' appended. By default, None	`None`
`unique_name`	`str \| None`	Unique name of the diffusion model. If None, a unique name will be generated. By default, None.	`None`

Raises:

Type	Description
`TypeError`	If scale, diffusion_coefficient, or relaxation_time are not numbers.
`ValueError`	If scale, diffusion_coefficient, or relaxation_time are negative.

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`get_all_variables`	Get all variables from the diffusion model.
`get_all_parameters`	Get all Parameters from the diffusion model.
`get_fittable_parameters`	Get all fittable Parameters from the diffusion model.
`get_free_parameters`	Get all free Parameters from the diffusion model.
`get_fit_parameters`	Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of the diffusion model.
`convert_y_unit`	Convert the y-axis unit of the diffusion model.
`get_fit_targets`	Get the fittable predictions of the diffusion model as FitTargets.
`get_global_variables`	Get all global variables from the diffusion model.
`get_independent_variables`	Get the independent variables from the diffusion model. If Q_index is provided, only the
`get_component_collections`	Get the ComponentCollection at the given Q index.
`calculate_width`	Calculate the half-width at half-maximum (HWHM) for the diffusion model. $\Gamma(Q) =
`calculate_EISF`	Calculate the Elastic Incoherent Structure Factor (EISF).
`calculate_QISF`	Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).
`create_component_collections`	Create ComponentCollection components for the diffusion model at given Q values.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`scale`	`Parameter`	Get the scale parameter of the diffusion model.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.
`lorentzian_name`	`str`	Get the name of the Lorentzian component.
`lorentzian_display_name`	`str \| None`	Get the display name of the Lorentzian component.
`diffusion_coefficient`	`Parameter`	Get the diffusion coefficient parameter D.
`relaxation_time`	`Parameter`	Get the relaxation time parameter t.

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`scale` `property` `writable`

Get the scale parameter of the diffusion model.

Returns:

Type	Description
`Parameter`	Scale parameter of the diffusion model.

`Q` `property` `writable`

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

`lorentzian_name` `property` `writable`

Get the name of the Lorentzian component.

Returns:

Type	Description
`str`	Name of the Lorentzian component.

`lorentzian_display_name` `property` `writable`

Get the display name of the Lorentzian component.

Returns:

Type	Description
`str \| None`	Display name of the Lorentzian component, or None if not set.

`diffusion_coefficient` `property` `writable`

Get the diffusion coefficient parameter D.

Returns:

Type	Description
`Parameter`	Diffusion coefficient D.

`relaxation_time` `property` `writable`

Get the relaxation time parameter t.

Returns:

Type	Description
`Parameter`	Relaxation time t in ps.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_variables(Q_index=None)`

Get all variables from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get variables from. If None, all variables from all ComponentCollections are returned, in addition to the global variables.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

`get_all_parameters(Q_index=None)`

Get all Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get parameters from. If None, all parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

`get_fittable_parameters(Q_index=None)`

Get all fittable Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fittable parameters from. If None, all fittable parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fittable Parameters from the diffusion model.

`get_free_parameters(Q_index=None)`

Get all free Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get free parameters from. If None, all free parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all free Parameters from the diffusion model.

`get_fit_parameters(Q_index=None)`

Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fit parameters from. If None, all fit parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fit Parameters from the diffusion model.

`clear_Q(confirm=False)`

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

`convert_x_unit(unit)`

Convert the x-axis unit of the diffusion model.

Converts the scale parameter (unit x_unit * y_unit), any subclass-specific x-unit parameters, and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. Only energy units are supported (the unit must be convertible to meV).

Unit validation raises UnitError when the unit is not convertible to meV. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

`convert_y_unit(unit)`

Convert the y-axis unit of the diffusion model.

Converts the scale parameter from x_unit * old_y_unit to x_unit * new_y_unit and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. The new y-unit must be dimensionally compatible with the current one; the scale conversion raises UnitError otherwise. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

`get_fit_targets()`

Get the fittable predictions of the diffusion model as FitTargets.

The base implementation declares 'area' (scale * QISF(Q)) and 'width' (the HWHM Gamma(Q)), with default dataset keys derived from the Lorentzian component's name. Subclasses with additional predictions (e.g. a delta-function weight) extend this list. The targets are snapshots: units and default keys reflect the model state at call time.

Returns:

Type	Description
`list[FitTarget]`	The fittable predictions of this model.

`get_global_variables()`

Get all global variables from the diffusion model.

Returns:

Type	Description
`list[Parameter]`	A list of all global variables from the diffusion model.

`get_independent_variables(Q_index=None)`

Get the independent variables from the diffusion model. If Q_index is provided, only the independent variables for the specified Q value will be returned. If Q_index is None, independent variables for all Q values will be returned. These are variables that are not global but also not part of the component collections.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value for which to get the independent variables. If None, independent variables for all Q values will be included.	`None`

Returns:

Type	Description
`list[Parameter]`	List of independent variables in the model.

`get_component_collections(Q_index=None)`

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the desired ComponentCollection. If None, all ComponentCollections are returned.	`None`

Returns:

Type	Description
`ComponentCollection \| list[ComponentCollection]`	The ComponentCollection at the specified Q index. If Q_index is None, a list of all ComponentCollections is returned.

`calculate_width(Q=None)`

Calculate the half-width at half-maximum (HWHM) for the diffusion model. $\Gamma(Q) = Q^2/(1+D t Q^2)$, where $D$ is the diffusion coefficient and $t$ is the relaxation time.

Parameters:

Name	Type	Description	Default
`Q`	`Q_type \| None`	Scattering vector in 1/angstrom. Can be a single value or an array of values. If None, Q values stored in the model are used.	`None`

Returns:

Type	Description
`np.ndarray`	HWHM values in the unit of the model (e.g., meV).

`calculate_EISF(Q)`

Calculate the Elastic Incoherent Structure Factor (EISF).

Parameters:

Name	Type	Description	Default
`Q`	`Q_type`	Scattering vector in 1/angstrom. Can be a single value or an array of values.	required

Returns:

Type	Description
`np.ndarray`	EISF values (dimensionless).

`calculate_QISF(Q)`

Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

Parameters:

Name	Type	Description	Default
`Q`	`Q_type`	Scattering vector in 1/angstrom. Can be a single value or an array of values.	required

Returns:

Type	Description
`np.ndarray`	QISF values (dimensionless).

`create_component_collections()`

Create ComponentCollection components for the diffusion model at given Q values.

Returns:

Type	Description
`list[ComponentCollection]`	List of ComponentCollections with Jump Diffusion Lorentzian components.

`InstrumentModel(display_name='MyInstrumentModel', unique_name=None, Q=None, resolution_model=None, background_model=None, energy_offset=None, x_unit='meV')`

InstrumentModel represents a model of the instrument in an experiment at various Q.

It can contain a model of the resolution function for convolutions, of the background and an offset in the energy axis.

Examples:

Creating an InstrumentModel with resolution and background

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
resolution_model = sm.ResolutionModel(components=sm.Gaussian(width=0.05))
background_model = sm.BackgroundModel(components=sm.Polynomial(coefficients=[0.001]))

instrument_model = sm.InstrumentModel(
    Q=Q,
    resolution_model=resolution_model,
    background_model=background_model,
)

Fixing resolution parameters after calibration

After fitting a vanadium run, fix the resolution parameters before fitting the sample:

instrument_model.fix_resolution_parameters()
instrument_model.get_all_variables(Q_index=0)

Parameters:

Name	Type	Description	Default
`display_name`	`str`	The display name of the InstrumentModel.	`'MyInstrumentModel'`
`unique_name`	`str \| None`	The unique name of the InstrumentModel.	`None`
`Q`	`Q_type \| None`	The Q values where the instrument is modelled.	`None`
`resolution_model`	`ResolutionModel \| SampleModel \| None`	The resolution model of the instrument. If a SampleModel it will be converted to a ResolutionModel. If None, an empty resolution model is created and no resolution convolution is carried out.	`None`
`background_model`	`BackgroundModel \| None`	The background model of the instrument. If None, an empty background model is created, and the background evaluates to 0.	`None`
`energy_offset`	`Numeric \| None`	Template energy offset of the instrument. Will be copied to each Q value. If None, the energy offset will be 0.	`None`
`x_unit`	`str \| sc.Unit`	The unit of the energy axis.	`'meV'`

Raises:

Type	Description
`TypeError`	If resolution_model is not a ResolutionModel or None, or if background_model is not a BackgroundModel or None, or if energy_offset is not a number or None.

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object from a full encoded dictionary.
`__copy__`	Return a copy of the object.
`clear_Q`	Clear the Q values of the InstrumentModel and any associated ResolutionModel and
`convert_x_unit`	Convert the unit of the InstrumentModel.
`get_all_variables`	Get all variables in the InstrumentModel.
`fix_resolution_parameters`	Fix all parameters in the resolution model.
`free_resolution_parameters`	Free all parameters in the resolution model.
`normalize_resolution`	Normalize the resolution model to have area 1.
`get_energy_offset`	Get the energy offset Parameter at a specific Q index.
`fix_energy_offset`	Fix energy offset parameters.
`free_energy_offset`	Free energy offset parameters.

Attributes:

Name	Type	Description
`unique_name`	`str`	Get the unique name of the object.
`display_name`	`str`	Get a pretty display name.
`resolution_model`	`ResolutionModel`	Get the resolution model of the instrument.
`background_model`	`BackgroundModel`	Get the background model of the instrument.
`Q`	`sc.Variable \| None`	Get the Q values of the InstrumentModel.
`x_unit`	`str \| sc.Unit \| None`	Get the x-axis unit of the InstrumentModel.
`energy_offset`	`Parameter`	Get the template energy offset of the instrument.

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`resolution_model` `property` `writable`

Get the resolution model of the instrument.

Returns:

Type	Description
`ResolutionModel`	The resolution model of the instrument.

`background_model` `property` `writable`

Get the background model of the instrument.

Returns:

Type	Description
`BackgroundModel`	The background model of the instrument.

`Q` `property` `writable`

Get the Q values of the InstrumentModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the InstrumentModel in 1/angstrom, or None if not set.

`x_unit` `property` `writable`

Get the x-axis unit of the InstrumentModel.

Returns:

Type	Description
`str \| sc.Unit \| None`	The x-axis unit of the InstrumentModel.

`energy_offset` `property` `writable`

Get the template energy offset of the instrument.

Returns:

Type	Description
`Parameter`	The energy offset Parameter. Each Q value gets its own copy via get_energy_offset().

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	Encoded object containing all information to reform an EasyScience object.

`from_dict(obj_dict)` `classmethod`

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

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`NewBase`	Reformed EasyScience object.

Raises:

Type	Description
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`clear_Q(confirm=False)`

Clear the Q values of the InstrumentModel and any associated ResolutionModel and BackgroundModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

`convert_x_unit(x_unit)`

Convert the unit of the InstrumentModel.

Parameters:

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

Raises:

Type	Description
`ValueError`	If x_unit is not a valid unit string or scipp Unit.

`get_all_variables(Q_index=None)`

Get all variables in the InstrumentModel.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value to get variables for. If None, get variables for all Q values.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all variables in the InstrumentModel. If Q_index is specified, only variables from the ComponentCollection at the given Q index are included. Otherwise, all variables in the InstrumentModel are included.

`fix_resolution_parameters()`

Fix all parameters in the resolution model.

`free_resolution_parameters()`

Free all parameters in the resolution model.

`normalize_resolution()`

Normalize the resolution model to have area 1.

`get_energy_offset(Q_index=None)`

Get the energy offset Parameter at a specific Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value to get the energy offset for. If None, get the energy offset for all Q values.	`None`

Raises:

Type	Description
`ValueError`	If no Q values are set in the InstrumentModel.

Returns:

Type	Description
`Parameter \| list[Parameter]`	The energy offset Parameter at the specified Q index, or a list of Parameters if Q_index is None.

`fix_energy_offset(Q_index=None)`

Fix energy offset parameters.

If Q_index is specified, only fix the energy offset for that Q value. If Q_index is None, fix energy offsets for all Q values.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value to fix the energy offset for. If None, fix energy offsets for all Q values.	`None`

`free_energy_offset(Q_index=None)`

Free energy offset parameters.

If Q_index is specified, only free the energy offset for that Q value. If Q_index is None, free energy offsets for all Q values.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value to free the energy offset for. If None, free energy offsets for all Q values.	`None`

`ResolutionModel(display_name='MyResolutionModel', unique_name=None, x_unit='meV', y_unit='dimensionless', components=None, Q=None)`

ResolutionModel represents a model of the instrument resolution in an experiment at various Q.

Examples:

Creating a Gaussian resolution model

A single Gaussian is the most common resolution model. Note that DeltaFunction, Polynomial, and Exponential components are not allowed in a ResolutionModel:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
resolution_model = sm.ResolutionModel(
    components=sm.Gaussian(width=0.05, area=1.0),
    Q=Q,
)
energy = np.linspace(-2, 2, 100)
resolution = resolution_model.evaluate(energy)

Building a resolution model from a fitted SampleModel

After fitting vanadium data with a SampleModel, use from_sample_model to convert it directly into a ResolutionModel:

resolution_model = sm.ResolutionModel.from_sample_model(fitted_sample_model)

Parameters:

Name	Type	Description	Default
`display_name`	`str`	Display name of the model.	`'MyResolutionModel'`
`unique_name`	`str \| None`	Unique name of the model. If None, a unique name will be generated.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`components`	`ModelComponent \| ComponentCollection \| None`	Template components. DeltaFunction, Polynomial, and Exponential are not allowed.	`None`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`get_all_variables`	Get all Parameters and Descriptors from all ComponentCollections in the ModelBase.
`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`.
`evaluate`	Evaluate the sample model at all Q for the given x values.
`remove_component`	Remove a ModelComponent from the SampleModel by its name.
`clear_components`	Clear all ModelComponents from the SampleModel.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of all components in the model.
`convert_y_unit`	Convert the y-axis unit of all components in the model.
`fix_all_parameters`	Fix all Parameters in all ComponentCollections.
`free_all_parameters`	Free all Parameters in all ComponentCollections.
`get_component_collection`	Get the ComponentCollection at the given Q index.
`normalize_area`	Normalize the area of the model across all Q values.
`append_component`	Append a component to the ResolutionModel.
`from_sample_model`	Create a ResolutionModel from a SampleModel.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`components`	`list[ModelComponent]`	Get the components of the SampleModel.
`component_collections_is_dirty`	`bool`	Return whether component collections need to be rebuilt before use.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`components` `property` `writable`

Get the components of the SampleModel.

Returns:

Type	Description
`list[ModelComponent]`	The components of the SampleModel.

`component_collections_is_dirty` `property`

Return whether component collections need to be rebuilt before use.

Returns:

Type	Description
`bool`	`True` if component collections have not been built yet or are stale.

`Q` `property` `writable`

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_variables(Q_index=None)`

Get all Parameters and Descriptors from all ComponentCollections in the ModelBase.

Ignores the Parameters and Descriptors in self._components as these are just templates.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	If None, get variables for all ComponentCollections. If int, get variables for the ComponentCollection at this index.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters and Descriptors from the ComponentCollections in the ModelBase.

`get_all_parameters()`

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_fittable_parameters()`

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_free_parameters()`

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

Returns:

Type	Description
`List[Parameter]`	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.

`evaluate(x, output='numpy')`

Evaluate the sample model at all Q for the given x values.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Energy axis values to evaluate the model at.	required
`output`	`str`	'numpy' returns np.ndarray per Q; 'scipp' returns sc.Variable per Q.	`'numpy'`

Raises:

Type	Description
`ValueError`	If there are no components in the model to evaluate.

Returns:

Type	Description
`list[np.ndarray] \| list[sc.Variable]`	A list of arrays containing the evaluated model values for each Q. The length of the list will match the number of Q values in the model.

`remove_component(name)`

Remove a ModelComponent from the SampleModel by its name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the ModelComponent to remove.	required

`clear_components()`

Clear all ModelComponents from the SampleModel.

`clear_Q(confirm=False)`

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

`convert_x_unit(unit)`

Convert the x-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit to convert to.	required

`convert_y_unit(unit)`

Convert the y-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit to convert to.	required

`fix_all_parameters()`

Fix all Parameters in all ComponentCollections.

`free_all_parameters()`

Free all Parameters in all ComponentCollections.

`get_component_collection(Q_index)`

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int`	The index of the desired ComponentCollection.	required

Returns:

Type	Description
`ComponentCollection`	The ComponentCollection at the given Q index.

`normalize_area()`

Normalize the area of the model across all Q values.

`append_component(component)`

Append a component to the ResolutionModel.

Does not allow DeltaFunction, Polynomial, or Exponential components, as these are not physical resolution components.

Parameters:

Name	Type	Description	Default
`component`	`ModelComponent \| ComponentCollection`	Component(s) to append.	required

Raises:

Type	Description
`TypeError`	If the component is a DeltaFunction, Polynomial, or Exponential.

`from_sample_model(sample_model, normalize_area=True, fix_parameters=True)` `classmethod`

Create a ResolutionModel from a SampleModel.

Parameters:

Name	Type	Description	Default
`sample_model`	`SampleModel`	SampleModel to create the ResolutionModel from.	required
`normalize_area`	`bool`	Whether to normalize the components in the ResolutionModel to have area 1.	`True`
`fix_parameters`	`bool`	Whether to fix the parameters in the ResolutionModel.	`True`

Returns:

Type	Description
`ResolutionModel`	ResolutionModel created from the SampleModel.

Raises:

Type	Description
`TypeError`	If sample_model is not a SampleModel, or if normalize_area or fix_parameters are not bool.

`SampleModel(display_name='MySampleModel', unique_name=None, x_unit='meV', y_unit='dimensionless', components=None, Q=None, diffusion_models=None, temperature=None, temperature_unit='K', detailed_balance_settings=None)`

SampleModel represents a model of a sample with components and diffusion models, parameterized by Q and optionally temperature. Generates ComponentCollections for each Q value, combining components from the base model and diffusion models.

Applies detailed balancing based on temperature if provided.

Examples:

Creating a SampleModel with a static component

A single component is copied to each Q value automatically:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
energy = np.linspace(-2, 2, 100)

sample_model = sm.SampleModel(
    components=[
        sm.DeltaFunction(display_name='Elastic', area=0.5),
        sm.Lorentzian(display_name='QE', area=0.5, width=0.3),
    ],
    Q=Q,
)
intensity = sample_model.evaluate(energy)

Adding a diffusion model and enabling detailed balance

Pass temperature to apply the detailed balance factor automatically:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
btd = sm.BrownianTranslationalDiffusion(diffusion_coefficient=2.4e-9, scale=0.5)
sample_model = sm.SampleModel(diffusion_models=btd, Q=Q, temperature=10)
intensity = sample_model.evaluate(np.linspace(-2, 2, 100))

Parameters:

Name	Type	Description	Default
`display_name`	`str`	Display name of the model.	`'MySampleModel'`
`unique_name`	`str \| None`	Unique name of the model. If None, a unique name will be generated.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`components`	`ModelComponent \| ComponentCollection \| None`	Template components copied into each Q's ComponentCollection.	`None`
`Q`	`Q_type \| None`	Q values. If None, Q is not set.	`None`
`diffusion_models`	`DiffusionModelBase \| list[DiffusionModelBase] \| None`	Diffusion models to include. Each must be a DiffusionModelBase.	`None`
`temperature`	`float \| None`	Sample temperature in temperature_unit. If provided, detailed balance is applied.	`None`
`temperature_unit`	`str \| sc.Unit`	Unit for the temperature parameter.	`'K'`
`detailed_balance_settings`	`DetailedBalanceSettings \| None`	Detailed balance settings. If None, default settings are used.	`None`

Raises:

Type	Description
`TypeError`	If diffusion_models contains non-DiffusionModelBase items, temperature is not numeric, or detailed_balance_settings is not a DetailedBalanceSettings instance.
`ValueError`	If temperature is negative.

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`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`.
`append_component`	Append a ModelComponent or ComponentCollection to the SampleModel.
`remove_component`	Remove a ModelComponent from the SampleModel by its name.
`clear_components`	Clear all ModelComponents from the SampleModel.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of all components in the model.
`convert_y_unit`	Convert the y-axis unit of all components in the model.
`fix_all_parameters`	Fix all Parameters in all ComponentCollections.
`free_all_parameters`	Free all Parameters in all ComponentCollections.
`get_component_collection`	Get the ComponentCollection at the given Q index.
`normalize_area`	Normalize the area of the model across all Q values.
`append_diffusion_model`	Append a DiffusionModel to the SampleModel.
`remove_diffusion_model`	Remove a DiffusionModel from the SampleModel by name.
`clear_diffusion_models`	Clear all DiffusionModels from the SampleModel.
`convert_temperature_unit`	Convert the unit of the temperature Parameter.
`evaluate`	Evaluate the sample model at all Q for the given x values.
`get_all_variables`	Get all Parameters and Descriptors from all ComponentCollections in the SampleModel.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`components`	`list[ModelComponent]`	Get the components of the SampleModel.
`component_collections_is_dirty`	`bool`	Return whether component collections need to be rebuilt before use.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.
`diffusion_models`	`list[DiffusionModelBase]`	Get the diffusion models of the SampleModel.
`temperature`	`Parameter \| None`	Get the temperature of the SampleModel.
`temperature_unit`	`str \| sc.Unit`	Get the temperature unit.
`normalize_detailed_balance`	`bool`	Get whether to divide the detailed balance factor by temperature.
`use_detailed_balance`	`bool`	Get whether detailed balance correction is applied.
`detailed_balance_settings`	`DetailedBalanceSettings`	Get the detailed balance settings.

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

`name` `property` `writable`

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

`x_unit` `property` `writable`

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

`y_unit` `property` `writable`

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

`components` `property` `writable`

Get the components of the SampleModel.

Returns:

Type	Description
`list[ModelComponent]`	The components of the SampleModel.

`component_collections_is_dirty` `property`

Return whether component collections need to be rebuilt before use.

Returns:

Type	Description
`bool`	`True` if component collections have not been built yet or are stale.

`Q` `property` `writable`

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

`diffusion_models` `property` `writable`

Get the diffusion models of the SampleModel.

Returns:

Type	Description
`list[DiffusionModelBase]`	The diffusion models of the SampleModel.

`temperature` `property` `writable`

Get the temperature of the SampleModel.

Returns:

Type	Description
`Parameter \| None`	The temperature Parameter of the SampleModel, or None if not set.

`temperature_unit` `property` `writable`

Get the temperature unit.

Returns:

Type	Description
`str \| sc.Unit`	The unit of the temperature parameter.

`normalize_detailed_balance` `property` `writable`

Get whether to divide the detailed balance factor by temperature.

Returns:

Type	Description
`bool`	True if the detailed balance factor is divided by temperature, False otherwise.

`use_detailed_balance` `property` `writable`

Get whether detailed balance correction is applied.

Returns:

Type	Description
`bool`	True if detailed balance is applied during evaluation, False otherwise

`detailed_balance_settings` `property` `writable`

Get the detailed balance settings.

Returns:

Type	Description
`DetailedBalanceSettings`	The detailed balance settings object.

Methods:

`to_dict(skip=None)`

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

`copy()`

Return a copy of the object.

`get_all_parameters()`

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_fittable_parameters()`

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

`get_free_parameters()`

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

Returns:

Type	Description
`List[Parameter]`	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.

`append_component(component)`

Append a ModelComponent or ComponentCollection to the SampleModel.

Parameters:

Name	Type	Description	Default
`component`	`ModelComponent \| ComponentCollection`	The ModelComponent or ComponentCollection to append.	required

`remove_component(name)`

Remove a ModelComponent from the SampleModel by its name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the ModelComponent to remove.	required

`clear_components()`

Clear all ModelComponents from the SampleModel.

`clear_Q(confirm=False)`

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

`convert_x_unit(unit)`

Convert the x-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit to convert to.	required

`convert_y_unit(unit)`

Convert the y-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit to convert to.	required

`fix_all_parameters()`

Fix all Parameters in all ComponentCollections.

`free_all_parameters()`

Free all Parameters in all ComponentCollections.

`get_component_collection(Q_index)`

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int`	The index of the desired ComponentCollection.	required

Returns:

Type	Description
`ComponentCollection`	The ComponentCollection at the given Q index.

`normalize_area()`

Normalize the area of the model across all Q values.

`append_diffusion_model(diffusion_model)`

Append a DiffusionModel to the SampleModel.

Parameters:

Name	Type	Description	Default
`diffusion_model`	`DiffusionModelBase`	The DiffusionModel to append.	required

Raises:

Type	Description
`TypeError`	If the diffusion_model is not a DiffusionModelBase.

`remove_diffusion_model(name)`

Remove a DiffusionModel from the SampleModel by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the DiffusionModel to remove.	required

Raises:

Type	Description
`ValueError`	If no DiffusionModel with the given name is found.

`clear_diffusion_models()`

Clear all DiffusionModels from the SampleModel.

`convert_temperature_unit(unit)`

Convert the unit of the temperature Parameter.

Parameters:

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

Raises:

Type	Description
`ValueError`	If temperature is not set or conversion fails.
`Exception`	If the provided unit is invalid or cannot be converted.

`evaluate(x, output='numpy')`

Evaluate the sample model at all Q for the given x values.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	The x values to evaluate the model at.	required
`output`	`str`	'numpy' returns list of np.ndarray; 'scipp' returns list of sc.Variable.	`'numpy'`

Returns:

Type	Description
`list[np.ndarray] \| list[sc.Variable]`	List of evaluated model values for each Q.

`get_all_variables(Q_index=None)`

Get all Parameters and Descriptors from all ComponentCollections in the SampleModel.

Also includes temperature if set and all variables from diffusion models. Ignores the Parameters and Descriptors in self._components as these are just templates.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	If specified, only get variables from the ComponentCollection at the given Q index. If None, get variables from all ComponentCollections.	`None`

Returns:

Type	Description
`list[Parameter]`	All Parameters and Descriptors in the SampleModel.

Modules

`background_model`

Classes:

Name	Description
`BackgroundModel`	BackgroundModel represents a model of the background in an experiment at various Q.

Classes

`BackgroundModel(display_name='MyBackgroundModel', unique_name=None, x_unit='meV', y_unit='dimensionless', components=None, Q=None)`

BackgroundModel represents a model of the background in an experiment at various Q.

Examples:

Creating a flat background

A constant background independent of Q:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
background_model = sm.BackgroundModel(
    components=sm.Polynomial(coefficients=[0.001]),
    Q=Q,
)
energy = np.linspace(-2, 2, 100)
background = background_model.evaluate(energy)

Creating a quadratic background

Higher-order polynomials can model a sloping or curved baseline:

import easydynamics.sample_model as sm

background_model = sm.BackgroundModel(
    components=sm.Polynomial(coefficients=[1.0, 0.1, 0.01]),
)

Parameters:

Name	Type	Description	Default
`display_name`	`str \| None`	Display name of the model.	`'MyBackgroundModel'`
`unique_name`	`str \| None`	Unique name of the model. If None, a unique name will be generated.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis (energy, Q, etc.).	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity).	`'dimensionless'`
`components`	`ModelComponent \| ComponentCollection \| None`	Template components of the model. If None, no components are added. These components are copied into ComponentCollections for each Q value.	`None`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`get_all_variables`	Get all Parameters and Descriptors from all ComponentCollections in the ModelBase.
`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`.
`evaluate`	Evaluate the sample model at all Q for the given x values.
`append_component`	Append a ModelComponent or ComponentCollection to the SampleModel.
`remove_component`	Remove a ModelComponent from the SampleModel by its name.
`clear_components`	Clear all ModelComponents from the SampleModel.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of all components in the model.
`convert_y_unit`	Convert the y-axis unit of all components in the model.
`fix_all_parameters`	Fix all Parameters in all ComponentCollections.
`free_all_parameters`	Free all Parameters in all ComponentCollections.
`get_component_collection`	Get the ComponentCollection at the given Q index.
`normalize_area`	Normalize the area of the model across all Q values.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`components`	`list[ModelComponent]`	Get the components of the SampleModel.
`component_collections_is_dirty`	`bool`	Return whether component collections need to be rebuilt before use.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

components property writable

Get the components of the SampleModel.

Returns:

Type	Description
`list[ModelComponent]`	The components of the SampleModel.

component_collections_is_dirty property

Return whether component collections need to be rebuilt before use.

Returns:

Type	Description
`bool`	`True` if component collections have not been built yet or are stale.

Q property writable

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

Methods:

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables(Q_index=None)

Get all Parameters and Descriptors from all ComponentCollections in the ModelBase.

Ignores the Parameters and Descriptors in self._components as these are just templates.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	If None, get variables for all ComponentCollections. If int, get variables for the ComponentCollection at this index.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters and Descriptors from the ComponentCollections in the ModelBase.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

evaluate(x, output='numpy')

Evaluate the sample model at all Q for the given x values.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Energy axis values to evaluate the model at.	required
`output`	`str`	'numpy' returns np.ndarray per Q; 'scipp' returns sc.Variable per Q.	`'numpy'`

Raises:

Type	Description
`ValueError`	If there are no components in the model to evaluate.

Returns:

Type	Description
`list[np.ndarray] \| list[sc.Variable]`	A list of arrays containing the evaluated model values for each Q. The length of the list will match the number of Q values in the model.

append_component(component)

Append a ModelComponent or ComponentCollection to the SampleModel.

Parameters:

Name	Type	Description	Default
`component`	`ModelComponent \| ComponentCollection`	The ModelComponent or ComponentCollection to append.	required

remove_component(name)

Remove a ModelComponent from the SampleModel by its name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the ModelComponent to remove.	required

clear_components()

Clear all ModelComponents from the SampleModel.

clear_Q(confirm=False)

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

convert_x_unit(unit)

Convert the x-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit to convert to.	required

convert_y_unit(unit)

Convert the y-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit to convert to.	required

fix_all_parameters()

Fix all Parameters in all ComponentCollections.

free_all_parameters()

Free all Parameters in all ComponentCollections.

get_component_collection(Q_index)

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int`	The index of the desired ComponentCollection.	required

Returns:

Type	Description
`ComponentCollection`	The ComponentCollection at the given Q index.

normalize_area()

Normalize the area of the model across all Q values.

`component_collection`

Classes:

Name	Description
`ComponentCollection`	Collection of model components.

Classes

`ComponentCollection(components=None, x_unit='meV', y_unit='dimensionless', name='ComponentCollection', display_name=None, unique_name=None)`

Collection of model components.

Examples:

Creating a ComponentCollection with multiple components

import numpy as np
import easydynamics.sample_model as sm

component1 = sm.Gaussian(name='Gaussian1', area=1.0, width=1.0)
component2 = sm.Lorentzian(name='Lorentzian1', area=2.0, width=0.5)
collection = sm.ComponentCollection(components=[component1, component2])

Evaluating, appending, and removing components

x = np.linspace(-5, 5, 100)
values = collection.evaluate(x)

component3 = sm.Gaussian(name='Gaussian2', area=0.5, width=0.8)
collection.append(component3)

collection.remove('Gaussian1')
collection.list_component_names()  # ['Lorentzian1', 'Gaussian2']

Parameters:

Name	Type	Description	Default
`components`	`ModelComponent \| list[ModelComponent] \| None`	Initial model components to add to the ComponentCollection.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis (energy, Q, etc.).	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity).	`'dimensionless'`
`name`	`str`	Name of the collection.	`'ComponentCollection'`
`display_name`	`str \| None`	Display name of the collection.	`None`
`unique_name`	`str \| None`	Unique name of the collection.	`None`

Raises:

Type	Description
`TypeError`	If components is not a list of ModelComponent.

Methods:

Name	Description
`convert_x_unit`	Convert the x-axis unit of the ComponentCollection and all its components.
`convert_y_unit`	Convert the y-axis unit of the ComponentCollection and all its components.
`append_component`	Append a model component or the components from another ComponentCollection to this
`list_component_names`	List the names of all components in the model.
`get_fit_targets`	Get the fittable predictions of this collection as FitTargets.
`normalize_area`	Normalize the areas of all components so they sum to 1.
`get_all_variables`	Get all parameters from all model components.
`evaluate`	Evaluate the sum of all components.
`evaluate_component`	Evaluate a single component by name.
`fix_all_parameters`	Fix all free parameters in the model.
`free_all_parameters`	Free all fixed parameters in the model.
`to_dict`	Serialise the ComponentCollection to a dictionary.
`from_dict`	Deserialise a ComponentCollection from its dictionary representation.
`__copy__`	Create a deep copy of the ComponentCollection.
`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`.
`__getitem__`	Get an item by index, slice, or unique_name.
`__setitem__`	Set an item at an index.
`__delitem__`	Delete an item by index, slice, or name.
`__len__`	Return the number of items in the collection.
`insert`	Insert an item into the list at a specific index.
`sort`	Sort the collection according to the given key function.
`pop`	Remove and return an item at a specific index or name.
`append`	Append an item to the end of the list.
`get_names`	Get a list of the names of all items in the list.
`get_duplicate_names`	Get a list of duplicate names in the list.

Attributes:

Name	Type	Description
`is_empty`	`bool`	Check if the ComponentCollection has no components.
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.

Attributes

is_empty property writable

Check if the ComponentCollection has no components.

Returns:

Type	Description
`bool`	True if the collection has no components, False otherwise.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

Methods:

convert_x_unit(new_x_unit)

Convert the x-axis unit of the ComponentCollection and all its components.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	The target x-axis unit to convert to.	required

convert_y_unit(new_y_unit)

Convert the y-axis unit of the ComponentCollection and all its components.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	The target y-axis unit to convert to.	required

append_component(component)

Append a model component or the components from another ComponentCollection to this ComponentCollection.

Parameters:

Name	Type	Description	Default
`component`	`ModelComponent \| ComponentCollection`	The component to append. If a ComponentCollection is provided, all of its components will be appended.	required

list_component_names()

List the names of all components in the model.

Returns:

Type	Description
`list[str]`	List of names of the components in the collection.

get_fit_targets()

Get the fittable predictions of this collection as FitTargets.

Collections have a single prediction — their summed evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the collection's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this collection's evaluate.

normalize_area()

Normalize the areas of all components so they sum to 1.

This is useful for convolutions.

Raises:

Type	Description
`ValueError`	If there are no components in the model or if the total area is zero or not finite, which would prevent normalization.

get_all_variables()

Get all parameters from all model components.

Returns:

Type	Description
`list[DescriptorBase]`	List of parameters in the collection.

evaluate(x, output='numpy')

Evaluate the sum of all components.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Energy axis.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values.

evaluate_component(x, name, output='numpy')

Evaluate a single component by name.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Energy axis.	required
`name`	`str`	Component name.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If there are no components in the model.
`TypeError`	If name is not a string.
`KeyError`	If no component with the given name exists in the collection.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated values for the specified component.

fix_all_parameters()

Fix all free parameters in the model.

free_all_parameters()

Free all fixed parameters in the model.

to_dict()

Serialise the ComponentCollection to a dictionary.

Returns:

Type	Description
`dict`	Dictionary representation of the ComponentCollection.

from_dict(obj_dict) classmethod

Deserialise a ComponentCollection from its dictionary representation.

Parameters:

Name	Type	Description	Default
`obj_dict`	`dict`	Dictionary representation of the ComponentCollection, as produced by to_dict().	required

Returns:

Type	Description
`ComponentCollection`	The deserialised ComponentCollection.

__copy__()

Create a deep copy of the ComponentCollection.

Returns:

Type	Description
`ComponentCollection`	A deep copy of the ComponentCollection.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

__getitem__(idx)

Get an item by index, slice, or unique_name.

Parameters:

Name	Type	Description	Default
`idx`	`int \| slice \| str`	`Index, slice, or name of the item to get.`	required

Returns:

Type	Description
`ProtectedType_ \| EasyDynamicsList[ProtectedType_]`	The item at the specified index or name, or a new EasyDynamicsList if a slice is provided.

Raises:

Type	Description
`TypeError`	If idx is not an int, slice, or str.
`KeyError`	If idx is a str and no item with that name is found.
`AmbiguousNameError`	If idx is a str and multiple items with that name are found.

__setitem__(idx, value)

__setitem__(idx: int, value: ProtectedType_) -> None

__setitem__(
    idx: slice, value: Iterable[ProtectedType_]
) -> None

Set an item at an index.

Parameters:

Name	Type	Description	Default
`idx`	`int \| slice`	Index to set.	required
`value`	`ProtectedType_ \| Iterable[ProtectedType_]`	New value.	required

Raises:

Type	Description
`TypeError`	If `idx` or `value` has an invalid type.
`ValueError`	If slice assignment changes the slice length.

__delitem__(idx)

Delete an item by index, slice, or name.

Parameters:

Name	Type	Description	Default
`idx`	`int \| slice \| str`	Index, slice, or name of item to delete.	required

Raises:

Type	Description
`KeyError`	If `idx` is a string that does not match any item.
`TypeError`	If `idx` is not an int, slice, or string.

__len__()

Return the number of items in the collection.

insert(index, value)

Insert an item into the list at a specific index.

Parameters:

Name	Type	Description	Default
`index`	`int`	The index at which to insert the item.	required
`value`	`ProtectedType_`	The item to insert. Must be an instance of one of the protected types.	required

sort(key=None, reverse=False)

Sort the collection according to the given key function.

Parameters:

Name	Type	Description	Default
`key`	`Callable[[ProtectedType_], Any]`	Mapping function to sort by. By default, None.	`None`
`reverse`	`bool`	Whether to reverse the sort. By default, False.	`False`

pop(index=-1)

Remove and return an item at a specific index or name.

Parameters:

Name	Type	Description	Default
`index`	`int \| str`	The index or name at which to pop the item.	`-1`

Returns:

Type	Description
`ProtectedType_`	The item that was popped.

Raises:

Type	Description
`TypeError`	If index is not an int or str.
`KeyError`	If index is a str and no item with that name is found.

append(value)

Append an item to the end of the list.

Parameters:

Name	Type	Description	Default
`value`	`ProtectedType_`	The item to append. Must be an instance of one of the protected types.	required

get_names()

Get a list of the names of all items in the list.

Returns:

Type	Description
`list[str]`	A list of the names of all items in the list.

get_duplicate_names()

Get a list of duplicate names in the list.

Returns:

Type	Description
`list[str]`	A list of duplicate names in the list.

Functions:

`components`

Modules:

Name	Description
`damped_harmonic_oscillator`
`delta_function`
`exponential`
`expression_component`
`gaussian`
`lorentzian`
`mixins`
`model_component`
`polynomial`
`voigt`

Classes:

Name	Description
`DampedHarmonicOscillator`	Model of a Damped Harmonic Oscillator (DHO).
`DeltaFunction`	Delta function.
`Exponential`	Model of an exponential function.
`ExpressionComponent`	Model component defined by a symbolic expression.
`Gaussian`	Model of a Gaussian function.
`Lorentzian`	Model of a Lorentzian function.
`Polynomial`	Polynomial function component.
`Voigt`	Voigt profile — convolution of Gaussian and Lorentzian.

Classes

`DampedHarmonicOscillator(area=1.0, center=1.0, width=1.0, x_unit='meV', y_unit='dimensionless', name='DampedHarmonicOscillator', display_name=None, unique_name=None)`

Model of a Damped Harmonic Oscillator (DHO).

\[ I(x) = \frac{2 A x_0^2 \gamma}{\pi \left( (x^2 - x_0^2)^2 + (2\gamma x)^2 \right)} \]

where $A$ is the area (area), $x_0$ is the center (center), and $\gamma$ is the half width at half max (width). area has unit = x_unit * y_unit; center and width have unit = x_unit.

Examples:

Creating a Damped Harmonic Oscillator

The center parameter is the resonance frequency, which must be positive. Both phonon peaks (at ±center) are captured by the model:

import numpy as np
import easydynamics.sample_model as sm

dho = sm.DampedHarmonicOscillator(area=1.0, center=10.0, width=1.0)
x = np.linspace(-20, 20, 200)
values = dho.evaluate(x)

Modifying parameters after construction

import easydynamics.sample_model as sm

dho = sm.DampedHarmonicOscillator(area=2.0, center=5.0, width=0.5, name='Phonon')
dho.area = 3.0
dho.center = 8.0
dho.width = 0.3

Parameters:

Name	Type	Description	Default
`area`	`Numeric`	Integrated area under the DHO profile. Unit is `x_unit * y_unit`.	`1.0`
`center`	`Numeric`	Resonance frequency (x_0) in x_unit; approximately the peak position. Must be strictly positive; a minimum of `DHO_MINIMUM_CENTER` (1e-10) is enforced.	`1.0`
`width`	`Numeric`	Damping coefficient (gamma) in x_unit. Must be strictly positive. Approximately equal to the HWHM of each peak.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center and width are stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'DampedHarmonicOscillator'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`convert_x_unit`	Convert x-axis parameters (center, width) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis unit by rescaling the area parameter.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter (resonance frequency).
`width`	`Parameter`	Get the width parameter (damping coefficient).

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

area property writable

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

center property writable

Get the center parameter (resonance frequency).

Returns:

Type	Description
`Parameter`	The resonance frequency (x_0) Parameter with unit `x_unit`.

width property writable

Get the width parameter (damping coefficient).

Returns:

Type	Description
`Parameter`	The damping coefficient (gamma) Parameter with unit `x_unit`.

Methods:

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

convert_x_unit(new_x_unit)

Convert x-axis parameters (center, width) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

convert_y_unit(new_y_unit)

Convert the y-axis unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

`DeltaFunction(center=None, area=1.0, x_unit='meV', y_unit='dimensionless', name='DeltaFunction', display_name=None, unique_name=None)`

Delta function.

When called directly, returns zero everywhere except at the bin nearest to center, where it returns area / bin_width. In convolutions it acts as an identity element (handled by the Convolution class). area has unit = x_unit * y_unit; center has unit = x_unit.

If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Examples:

Creating a DeltaFunction (elastic line)

The DeltaFunction evaluates to zero everywhere when called directly. It acts as an identity in convolutions, making it useful for modelling the elastic line in QENS:

import numpy as np
import easydynamics.sample_model as sm

delta = sm.DeltaFunction(area=1.0)
x = np.linspace(-2, 2, 100)
values = delta.evaluate(x)  # all zeros except at the bin nearest to center

Creating a DeltaFunction with a free center

Pass a numeric value for center to place the elastic line at a specific energy transfer:

import easydynamics.sample_model as sm

delta = sm.DeltaFunction(area=0.7, center=0.5)
delta.area = 0.5

Parameters:

Name	Type	Description	Default
`center`	`Numeric \| None`	Position of the delta function in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`area`	`Numeric`	Integrated area (weight) of the delta function. Unit is `x_unit * y_unit`.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center is stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'DeltaFunction'`
`display_name`	`str \| None`	Display name of the component, shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`convert_x_unit`	Convert x-axis parameters (center) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis unit by rescaling the area parameter.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter.

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

area property writable

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

center property writable

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center Parameter with unit `x_unit`.

Methods:

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

convert_x_unit(new_x_unit)

Convert x-axis parameters (center) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

convert_y_unit(new_y_unit)

Convert the y-axis unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

`Exponential(amplitude=1.0, center=None, rate=1.0, x_unit='meV', y_unit='dimensionless', name='Exponential', display_name=None, unique_name=None)`

Model of an exponential function.

\[ I(x) = A e^{B (x-x_0)} \]

where $A$ is the amplitude, $x_0$ is the center, and $B$ is the rate. amplitude has unit = y_unit; center has unit = x_unit; rate has unit = 1/x_unit.

Examples:

Creating an Exponential with a fixed center

By default the center is fixed at 0. A negative rate gives a decaying exponential:

import numpy as np
import easydynamics.sample_model as sm

exp = sm.Exponential(amplitude=1.0, rate=-0.5)
x = np.linspace(0, 5, 100)
values = exp.evaluate(x)

Creating an Exponential with a free center and modifying parameters

Pass a numeric value for center to leave it free during fitting:

import easydynamics.sample_model as sm

exp = sm.Exponential(amplitude=2.0, center=1.0, rate=-1.0, name='Background')
exp.amplitude = 3.0
exp.rate = -0.5

Parameters:

Name	Type	Description	Default
`amplitude`	`Numeric`	Pre-exponential factor A. Unit is `y_unit`.	`1.0`
`center`	`Numeric \| None`	Reference point x_0 in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`rate`	`Numeric`	Exponential rate B in units of `1/x_unit`.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center is stored in this unit; rate is stored in `1/x_unit`.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output). amplitude is stored in this unit.	`'dimensionless'`
`name`	`str`	Name of the component.	`'Exponential'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Raises:

Type	Description
`TypeError`	If amplitude or rate is not numeric.
`ValueError`	If amplitude or rate is not finite.

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`convert_x_unit`	Convert center to new_x_unit and rate to 1/new_x_unit.
`convert_y_unit`	Convert the y-axis unit by rescaling the amplitude parameter.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`amplitude`	`Parameter`	Get the amplitude parameter.
`center`	`Parameter`	Get the center parameter.
`rate`	`Parameter`	Get the rate parameter.

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

amplitude property writable

Get the amplitude parameter.

Returns:

Type	Description
`Parameter`	The amplitude Parameter with unit `y_unit`.

center property writable

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center (x_0) Parameter with unit `x_unit`.

rate property writable

Get the rate parameter.

Returns:

Type	Description
`Parameter`	The exponential rate (B) Parameter with unit `1/x_unit`.

Methods:

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

convert_x_unit(new_x_unit)

Convert center to new_x_unit and rate to 1/new_x_unit.

The amplitude carries y_unit only and is unaffected.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit. The rate unit is set to `1/new_x_unit`.	required

convert_y_unit(new_y_unit)

Convert the y-axis unit by rescaling the amplitude parameter.

The amplitude is rescaled from old_y_unit to new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

`ExpressionComponent(expression, parameters=None, parameter_units=None, x_unit='meV', y_unit='dimensionless', name='Expression', display_name=None, unique_name=None)`

Model component defined by a symbolic expression.

The expression must contain x as the independent variable. All other symbols are treated as free parameters, which can be accessed and set as attributes after construction. Supported functions include exp, sin, cos, sqrt, erf, and others — see the _ALLOWED_FUNCS class variable for the full list.

Examples:

Defining a custom Gaussian expression

Parameters are given as a dictionary of initial values and can be accessed as attributes after construction:

import numpy as np
import easydynamics.sample_model as sm

expr = sm.ExpressionComponent(
    'A * exp(-(x - x0)**2 / (2*sigma**2))',
    parameters={'A': 10, 'x0': 0, 'sigma': 1},
    x_unit='meV',
    display_name='Gaussian Peak',
)
x = np.linspace(-3, 3, 100)
values = expr.evaluate(x)

Modifying parameter values after construction

Parameters can be set directly as attributes:

expr.A = 5
expr.sigma = 0.5

Giving parameters units

Parameters are dimensionless by default. Units can be given per parameter at construction, or relabelled later with set_unit (the numeric value is kept as-is). When units are in use, the unit of the evaluated expression is derived from the parameter units and x_unit (see output_unit), and a warning is issued if it does not match y_unit:

expr = sm.ExpressionComponent(
    'A * exp(-(x - x0)**2 / (2*sigma**2))',
    parameters={'A': 10, 'x0': 0, 'sigma': 1},
    parameter_units={'A': '1/meV', 'x0': 'meV', 'sigma': 'meV'},
    y_unit='1/meV',
)
expr.set_unit('A', '1/meV')

Physical constants

The symbols hbar (in meV*s) and kb (in meV/K) are provided automatically as read-only constants (DescriptorNumbers) when they appear in the expression:

boltzmann = sm.ExpressionComponent(
    'exp(-x / (kb * T))',
    parameters={'T': 300.0},
    parameter_units={'T': 'K'},
)

Use e.g. boltzmann.kb.convert_unit('eV/K') to work in another unit (this rescales the value, unlike set_unit).

Parameters:

Name	Type	Description	Default
`expression`	`str`	The symbolic expression as a string. Must contain 'x' as the independent variable. The symbols `hbar` and `kb` are provided automatically as read-only physical constants (in meVs and meV/K respectively) unless overridden via parameters*.	required
`parameters`	`dict[str, Numeric] \| None`	Dictionary of parameter names and their initial values. Parameters that are not given a unit are dimensionless.	`None`
`parameter_units`	`dict[str, str \| sc.Unit] \| None`	Optional units per parameter name. Each entry sets the unit of the named parameter without rescaling its value (see :meth:`set_unit`), and takes precedence over the unit of a Parameter instance given in parameters. When units are in use, a warning is issued if the expression's output unit does not match y_unit.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'Expression'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Unique name for the component.	`None`

Raises:

Type	Description
`ValueError`	If the expression is invalid or does not contain 'x', or if parameter_units names a parameter that is not in the expression.
`TypeError`	If any parameter value is not numeric, or if parameter_units is not a dictionary.

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`get_all_variables`	Return all parameters.
`set_unit`	Set the unit of a parameter without rescaling its value.
`convert_x_unit`	Convert the x-axis unit of the expression.
`convert_y_unit`	Convert the y-axis unit of the expression.
`__getattr__`	Allow access to parameters and physical constants as attributes.
`__setattr__`	Allow setting parameter values as attributes.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`expression`	`str`	Return the original expression string.
`constants`	`dict[str, DescriptorNumber]`	Get the physical constants used by the expression.
`output_unit`	`str`	Get the unit of the evaluated expression, derived from x_unit and the parameter units.

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

expression property writable

Return the original expression string.

Returns:

Type	Description
`str`	The original expression string provided at initialization.

constants property

Get the physical constants used by the expression.

Returns:

Type	Description
`dict[str, DescriptorNumber]`	The automatically provided constants (e.g. `hbar`, `kb`) keyed by symbol name.

output_unit property

Get the unit of the evaluated expression, derived from x_unit and the parameter units.

The unit is propagated through the expression tree: addition requires compatible units, multiplication and powers combine units, and functions like exp or sin require a dimensionless argument. Propagation raises sc.UnitError if the expression is not unit-consistent (e.g. adding meV to a dimensionless quantity, or taking exp of a quantity with a unit).

Returns:

Type	Description
`str`	The unit of the evaluated expression.

Methods:

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

get_all_variables()

Return all parameters.

Returns:

Type	Description
`list[Parameter]`	List of all parameters in the expression.

set_unit(name, unit)

Set the unit of a parameter without rescaling its value.

This relabels the unit: the numeric value, bounds, and variance are kept as-is. Use Parameter.convert_unit instead to rescale a value into a compatible unit. Issues a warning if the resulting output unit of the expression no longer matches y_unit. Raises the same exceptions as :meth:_relabel_parameter_unit on invalid input.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the parameter whose unit to set.	required
`unit`	`str \| sc.Unit`	The new unit.	required

convert_x_unit(_new_unit)

Convert the x-axis unit of the expression.

Unit conversion is not implemented for ExpressionComponent. Should it ever be needed, the viable path is dimensional analysis on the parameter units: for each parameter, determine the power n of the x-dimension in its unit and rescale its value by the x-unit conversion factor to the power n (the generalization of Polynomial's power-law rescaling). This only works when x_unit has a single unambiguous dimension.

Parameters:

Name	Type	Description	Default
`_new_unit`	`str \| sc.Unit`	The new unit to convert to (ignored).	required

Raises:

Type	Description
`NotImplementedError`	Always raised to indicate unit conversion is not supported.

convert_y_unit(_new_unit)

Convert the y-axis unit of the expression.

Unit conversion is not implemented for ExpressionComponent. See convert_x_unit for the approach that would make it possible.

Parameters:

Name	Type	Description	Default
`_new_unit`	`str \| sc.Unit`	The new unit to convert to (ignored).	required

Raises:

Type	Description
`NotImplementedError`	Always raised to indicate unit conversion is not supported.

__getattr__(name)

Allow access to parameters and physical constants as attributes.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the parameter or constant to access.	required

Raises:

Type	Description
`AttributeError`	If the parameter does not exist.

Returns:

Type	Description
`Parameter \| DescriptorNumber`	The parameter or constant with the given name.

__setattr__(name, value)

Allow setting parameter values as attributes.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the parameter to set.	required
`value`	`Numeric`	New value for the parameter.	required

Raises:

Type	Description
`AttributeError`	If the name refers to a physical constant.
`TypeError`	If the value is not numeric.

`Gaussian(area=1.0, center=None, width=1.0, x_unit='meV', y_unit='dimensionless', name='Gaussian', display_name=None, unique_name=None)`

Model of a Gaussian function.

\[ I(x) = \frac{A}{\sigma \sqrt{2\pi}} \exp\left( -\frac{1}{2} \left(\frac{x - x_0}{\sigma}\right)^2 \right) \]

where $A$ is the area, $x_0$ is the center, and $\sigma$ is the width. area has unit = x_unit * y_unit; center and width have unit = x_unit.

If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Examples:

Creating a Gaussian with a fixed center (typical QENS use)

By default the center is fixed at 0, which is the typical setup for a QENS elastic line:

import numpy as np
import easydynamics.sample_model as sm

g = sm.Gaussian(area=1.0, width=0.5)
x = np.linspace(-2, 2, 100)
values = g.evaluate(x)

Creating a Gaussian with a free center and modifying parameters

Pass a numeric value for center to leave it free during fitting, and use the property setters to update parameter values after construction:

import easydynamics.sample_model as sm

g = sm.Gaussian(area=2.0, center=0.5, width=0.3, name='Peak')
g.area = 3.0
g.width = 0.2

Parameters:

Name	Type	Description	Default
`area`	`Numeric`	Integrated area under the Gaussian. Unit is `x_unit * y_unit`.	`1.0`
`center`	`Numeric \| None`	Peak position in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`width`	`Numeric`	Standard deviation (sigma) in x_unit. Must be strictly positive.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center and width are stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'Gaussian'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`convert_x_unit`	Convert x-axis parameters (center, width) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis (output) unit by rescaling the area parameter.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter.
`width`	`Parameter`	Get the width parameter (sigma).

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

area property writable

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

center property writable

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center Parameter with unit `x_unit`.

width property writable

Get the width parameter (sigma).

Returns:

Type	Description
`Parameter`	The width (sigma) Parameter with unit `x_unit`.

Methods:

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

convert_x_unit(new_x_unit)

Convert x-axis parameters (center, width) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

convert_y_unit(new_y_unit)

Convert the y-axis (output) unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

`Lorentzian(area=1.0, center=None, width=1.0, x_unit='meV', y_unit='dimensionless', name='Lorentzian', display_name=None, unique_name=None)`

Model of a Lorentzian function.

\[ I(x) = \frac{A}{\pi} \frac{\Gamma}{(x - x_0)^2 + \Gamma^2} \]

where $A$ is the area, $x_0$ is the center, and $\Gamma$ is the hald width at half max (HWHM). area has unit = x_unit * y_unit; center and width have unit = x_unit.

If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Examples:

Creating a Lorentzian with a fixed center (typical QENS use)

By default the center is fixed at 0, which is the typical setup for a QENS quasi-elastic line:

import numpy as np
import easydynamics.sample_model as sm

l = sm.Lorentzian(area=1.0, width=0.3)
x = np.linspace(-2, 2, 100)
values = l.evaluate(x)

Creating a Lorentzian with a free center and modifying parameters

Pass a numeric value for center to leave it free during fitting:

import easydynamics.sample_model as sm

l = sm.Lorentzian(area=2.0, center=0.5, width=0.3, name='QE peak')
l.area = 3.0
l.width = 0.2

Parameters:

Name	Type	Description	Default
`area`	`Numeric`	Integrated area under the Lorentzian. Unit is `x_unit * y_unit`.	`1.0`
`center`	`Numeric \| None`	Peak position in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`width`	`Numeric`	Half-width at half-maximum (HWHM, gamma) in x_unit. Must be strictly positive.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center and width are stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'Lorentzian'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`convert_x_unit`	Convert x-axis parameters (center, width) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis (output) unit by rescaling the area parameter.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter.
`width`	`Parameter`	Get the width parameter (HWHM).

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

area property writable

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

center property writable

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center Parameter with unit `x_unit`.

width property writable

Get the width parameter (HWHM).

Returns:

Type	Description
`Parameter`	The HWHM (gamma) Parameter with unit `x_unit`.

Methods:

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

convert_x_unit(new_x_unit)

Convert x-axis parameters (center, width) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

convert_y_unit(new_y_unit)

Convert the y-axis (output) unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

`Polynomial(coefficients=(0.0,), x_unit='meV', y_unit='dimensionless', name='Polynomial', display_name=None, unique_name=None, suppress_warnings=False)`

Polynomial function component.

\[ I(x) = c_0 + c_1 x + c_2 x^2 + ... + c_N x^N \]

Coefficients are stored as dimensionless Parameters. When x_unit changes, the coefficient values are rescaled so the evaluated result stays the same. The output unit is y_unit.

Examples:

Creating a constant background (degree 0)

import numpy as np
import easydynamics.sample_model as sm

poly = sm.Polynomial(coefficients=[1.5])
x = np.linspace(-5, 5, 100)
values = poly.evaluate(x)

Creating a linear background (degree 1)

Coefficients are ordered as [c0, c1, ...], where c0 is the constant term:

import easydynamics.sample_model as sm

poly = sm.Polynomial(coefficients=[2.0, 0.1], name='Background')
poly.coefficients = [1.5, 0.05]

Creating a sparse polynomial from a dict

Powers that are not listed are filled with coefficients fixed to zero:

import easydynamics.sample_model as sm

poly = sm.Polynomial(coefficients={2: 1.5})  # 1.5*x^2, with c0 and c1 fixed at 0

Changing the degree after construction

import easydynamics.sample_model as sm

poly = sm.Polynomial(coefficients=[2.0, 0.1])
poly.add_coefficient(0.05)  # now 2.0 + 0.1*x + 0.05*x^2
removed = poly.remove_coefficient()  # returns 0.05, back to 2.0 + 0.1*x

coefficients : _CoefficientsInput, default=(0.0,) Either an ordered sequence of polynomial coefficients [c0, c1, ..., cN] where the polynomial is c0 + c1*x + c2*x^2 + ... + cN*x^N, or a sparse dict mapping integer powers to numeric values (e.g. {2: 1.5} for 1.5*x^2).

For a sequence, each element may be a plain numeric value (wrapped into a dimensionless
:class:`Parameter`) or an existing :class:`Parameter` instance.  For a dict, powers not
present are filled with fixed-to-zero Parameters, and the degree is taken from the
largest key.  Must contain at least one element.

x_unit : str | sc.Unit, default='meV' Unit of the x-axis. When the x_unit is changed via :meth:convert_x_unit, coefficient values are rescaled by power-law factors so the evaluated output remains unchanged. y_unit : str | sc.Unit, default='dimensionless' Unit of the y-axis (output). name : str, default='Polynomial' Name of the component. display_name : str | None, default=None Display name shown when plotting. Falls back to name if None. unique_name : str | None, default=None Globally unique identifier. Auto-generated if None. suppress_warnings : bool, default=False Whether to suppress warnings

Raises:

Type	Description
`TypeError`	If coefficients is not a list, tuple, ndarray, or dict, if any sequence element is neither numeric nor a :class:`Parameter`, or if any dict key is not an integer or dict value is not numeric.
`ValueError`	If coefficients is empty, or if any dict key is negative.

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`coefficient_values`	Get the coefficients of the polynomial as a list.
`add_coefficient`	Add a new coefficient at the next highest power, increasing the degree by one.
`remove_coefficient`	Remove the highest-power coefficient, decreasing the degree by one.
`get_all_variables`	Returns
`convert_x_unit`	Convert the x-axis unit by rescaling coefficients with power-law factors.
`convert_y_unit`	Rescale all coefficients so the evaluated output remains the same physical value.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`suppress_warnings`	`bool`	Get whether or not to suppress warnings.
`coefficients`	`list[Parameter]`	Get the coefficients of the polynomial as a list of Parameters.
`degree`	`int`	Returns

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

suppress_warnings property writable

Get whether or not to suppress warnings.

coefficients property writable

Get the coefficients of the polynomial as a list of Parameters.

Returns:

Type	Description
`list[Parameter]`	A shallow copy of the internal coefficient list `[c0, c1, ..., cN]`. Modifying the returned list does not affect the model; use the setter to replace values.

degree property writable

Returns:

Type	Description
`int`	Polynomial degree, equal to `len(coefficients) - 1`.

Methods:

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

coefficient_values()

Get the coefficients of the polynomial as a list.

Returns:

Type	Description
`list[float]`	Current numeric values of all coefficients `[c0.value, c1.value, ..., cN.value]`.

add_coefficient(value=0.0, fixed=False)

Add a new coefficient at the next highest power, increasing the degree by one.

Parameters:

Name	Type	Description	Default
`value`	`Numeric`	The numeric value of the new coefficient.	`0.0`
`fixed`	`bool`	If True, the new coefficient is fixed (not free for fitting).	`False`

Raises:

Type	Description
`TypeError`	If value is not a numeric value.

remove_coefficient()

Remove the highest-power coefficient, decreasing the degree by one.

Returns:

Type	Description
`float`	The value of the removed coefficient.

Raises:

Type	Description
`ValueError`	If only one coefficient remains; a Polynomial must always keep at least one.

get_all_variables()

Returns:

Type	Description
`list[DescriptorBase]`	The coefficient Parameters that constitute the fittable variables of this polynomial component.

convert_x_unit(new_x_unit)

Convert the x-axis unit by rescaling coefficients with power-law factors.

Each coefficient c_i is rescaled by (old_scale / new_scale) ** i so the evaluated polynomial output is unchanged after the conversion.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

Raises:

Type	Description
`UnitError`	If new_x_unit is not a valid unit string or `sc.Unit`, or if the conversion between the current unit and new_x_unit fails.

convert_y_unit(new_y_unit)

Rescale all coefficients so the evaluated output remains the same physical value.

All coefficients are multiplied by the conversion factor from old_y_unit to new_y_unit so that I(x) [new_y_unit] represents the same physical quantity as I(x) [old_y_unit].

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit. Must be dimensionally compatible with the current y_unit.	required

Raises:

Type	Description
`UnitError`	If new_y_unit is not a valid unit string or `sc.Unit`, or if the conversion between the current y_unit and new_y_unit fails.

`Voigt(area=1.0, center=None, gaussian_width=1.0, lorentzian_width=1.0, x_unit='meV', y_unit='dimensionless', name='Voigt', display_name=None, unique_name=None)`

Voigt profile — convolution of Gaussian and Lorentzian.

Uses scipy.special.voigt_profile to evaluate the profile. area has unit = x_unit * y_unit; center, gaussian_width, and lorentzian_width have unit = x_unit.

If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Examples:

Creating a Voigt profile with a fixed center (typical QENS use)

The Voigt profile is a convolution of a Gaussian and a Lorentzian. By default the center is fixed at 0:

import numpy as np
import easydynamics.sample_model as sm

v = sm.Voigt(area=1.0, gaussian_width=0.1, lorentzian_width=0.3)
x = np.linspace(-2, 2, 100)
values = v.evaluate(x)

Setting the Gaussian and Lorentzian widths independently

Pass a numeric value for center to leave it free during fitting, and use the property setters to adjust the two width components after construction:

import easydynamics.sample_model as sm

v = sm.Voigt(area=2.0, center=0.5, gaussian_width=0.2, lorentzian_width=0.4, name='Peak')
v.gaussian_width = 0.1
v.lorentzian_width = 0.2

Parameters:

Name	Type	Description	Default
`area`	`Numeric \| Parameter`	Integrated area under the Voigt profile. Unit is `x_unit * y_unit`.	`1.0`
`center`	`Numeric \| Parameter \| None`	Peak position in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`gaussian_width`	`Numeric \| Parameter`	Gaussian component standard deviation (sigma) in x_unit. Must be strictly positive.	`1.0`
`lorentzian_width`	`Numeric \| Parameter`	Lorentzian component HWHM (gamma) in x_unit. Must be strictly positive.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center, gaussian_width, and lorentzian_width are stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'Voigt'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.
`convert_x_unit`	Convert x-axis parameters (center, widths) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis unit by rescaling the area parameter.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter.
`gaussian_width`	`Parameter`	Get the Gaussian width parameter (sigma).
`lorentzian_width`	`Parameter`	Get the Lorentzian width parameter (HWHM).

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

area property writable

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

center property writable

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center Parameter with unit `x_unit`.

gaussian_width property writable

Get the Gaussian width parameter (sigma).

Returns:

Type	Description
`Parameter`	The Gaussian component width (sigma) Parameter with unit `x_unit`.

lorentzian_width property writable

Get the Lorentzian width parameter (HWHM).

Returns:

Type	Description
`Parameter`	The Lorentzian component HWHM (gamma) Parameter with unit `x_unit`.

Methods:

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

convert_x_unit(new_x_unit)

Convert x-axis parameters (center, widths) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

convert_y_unit(new_y_unit)

Convert the y-axis unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

Modules

`damped_harmonic_oscillator`

Classes:

Name	Description
`DampedHarmonicOscillator`	Model of a Damped Harmonic Oscillator (DHO).

Classes

DampedHarmonicOscillator(area=1.0, center=1.0, width=1.0, x_unit='meV', y_unit='dimensionless', name='DampedHarmonicOscillator', display_name=None, unique_name=None)

Model of a Damped Harmonic Oscillator (DHO).

\[ I(x) = \frac{2 A x_0^2 \gamma}{\pi \left( (x^2 - x_0^2)^2 + (2\gamma x)^2 \right)} \]

where $A$ is the area (area), $x_0$ is the center (center), and $\gamma$ is the half width at half max (width). area has unit = x_unit * y_unit; center and width have unit = x_unit.

Examples:

Creating a Damped Harmonic Oscillator

The center parameter is the resonance frequency, which must be positive. Both phonon peaks (at ±center) are captured by the model:

import numpy as np
import easydynamics.sample_model as sm

dho = sm.DampedHarmonicOscillator(area=1.0, center=10.0, width=1.0)
x = np.linspace(-20, 20, 200)
values = dho.evaluate(x)

Modifying parameters after construction

import easydynamics.sample_model as sm

dho = sm.DampedHarmonicOscillator(area=2.0, center=5.0, width=0.5, name='Phonon')
dho.area = 3.0
dho.center = 8.0
dho.width = 0.3

Parameters:

Name	Type	Description	Default
`area`	`Numeric`	Integrated area under the DHO profile. Unit is `x_unit * y_unit`.	`1.0`
`center`	`Numeric`	Resonance frequency (x_0) in x_unit; approximately the peak position. Must be strictly positive; a minimum of `DHO_MINIMUM_CENTER` (1e-10) is enforced.	`1.0`
`width`	`Numeric`	Damping coefficient (gamma) in x_unit. Must be strictly positive. Approximately equal to the HWHM of each peak.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center and width are stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'DampedHarmonicOscillator'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`convert_x_unit`	Convert x-axis parameters (center, width) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis unit by rescaling the area parameter.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.

Attributes:

Name	Type	Description
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter (resonance frequency).
`width`	`Parameter`	Get the width parameter (damping coefficient).
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.

Attributes

area property writable

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

center property writable

Get the center parameter (resonance frequency).

Returns:

Type	Description
`Parameter`	The resonance frequency (x_0) Parameter with unit `x_unit`.

width property writable

Get the width parameter (damping coefficient).

Returns:

Type	Description
`Parameter`	The damping coefficient (gamma) Parameter with unit `x_unit`.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

Methods:

convert_x_unit(new_x_unit)

Convert x-axis parameters (center, width) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

convert_y_unit(new_y_unit)

Convert the y-axis unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`delta_function`

Classes:

Name	Description
`DeltaFunction`	Delta function.

Classes

DeltaFunction(center=None, area=1.0, x_unit='meV', y_unit='dimensionless', name='DeltaFunction', display_name=None, unique_name=None)

Delta function.

When called directly, returns zero everywhere except at the bin nearest to center, where it returns area / bin_width. In convolutions it acts as an identity element (handled by the Convolution class). area has unit = x_unit * y_unit; center has unit = x_unit.

If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Examples:

Creating a DeltaFunction (elastic line)

The DeltaFunction evaluates to zero everywhere when called directly. It acts as an identity in convolutions, making it useful for modelling the elastic line in QENS:

import numpy as np
import easydynamics.sample_model as sm

delta = sm.DeltaFunction(area=1.0)
x = np.linspace(-2, 2, 100)
values = delta.evaluate(x)  # all zeros except at the bin nearest to center

Creating a DeltaFunction with a free center

Pass a numeric value for center to place the elastic line at a specific energy transfer:

import easydynamics.sample_model as sm

delta = sm.DeltaFunction(area=0.7, center=0.5)
delta.area = 0.5

Parameters:

Name	Type	Description	Default
`center`	`Numeric \| None`	Position of the delta function in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`area`	`Numeric`	Integrated area (weight) of the delta function. Unit is `x_unit * y_unit`.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center is stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'DeltaFunction'`
`display_name`	`str \| None`	Display name of the component, shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`convert_x_unit`	Convert x-axis parameters (center) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis unit by rescaling the area parameter.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.

Attributes:

Name	Type	Description
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter.
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.

Attributes

area property writable

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

center property writable

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center Parameter with unit `x_unit`.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

Methods:

convert_x_unit(new_x_unit)

Convert x-axis parameters (center) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

convert_y_unit(new_y_unit)

Convert the y-axis unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`exponential`

Classes:

Name	Description
`Exponential`	Model of an exponential function.

Classes

Exponential(amplitude=1.0, center=None, rate=1.0, x_unit='meV', y_unit='dimensionless', name='Exponential', display_name=None, unique_name=None)

Model of an exponential function.

\[ I(x) = A e^{B (x-x_0)} \]

where $A$ is the amplitude, $x_0$ is the center, and $B$ is the rate. amplitude has unit = y_unit; center has unit = x_unit; rate has unit = 1/x_unit.

Examples:

Creating an Exponential with a fixed center

By default the center is fixed at 0. A negative rate gives a decaying exponential:

import numpy as np
import easydynamics.sample_model as sm

exp = sm.Exponential(amplitude=1.0, rate=-0.5)
x = np.linspace(0, 5, 100)
values = exp.evaluate(x)

Creating an Exponential with a free center and modifying parameters

Pass a numeric value for center to leave it free during fitting:

import easydynamics.sample_model as sm

exp = sm.Exponential(amplitude=2.0, center=1.0, rate=-1.0, name='Background')
exp.amplitude = 3.0
exp.rate = -0.5

Parameters:

Name	Type	Description	Default
`amplitude`	`Numeric`	Pre-exponential factor A. Unit is `y_unit`.	`1.0`
`center`	`Numeric \| None`	Reference point x_0 in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`rate`	`Numeric`	Exponential rate B in units of `1/x_unit`.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center is stored in this unit; rate is stored in `1/x_unit`.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output). amplitude is stored in this unit.	`'dimensionless'`
`name`	`str`	Name of the component.	`'Exponential'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Raises:

Type	Description
`TypeError`	If amplitude or rate is not numeric.
`ValueError`	If amplitude or rate is not finite.

Methods:

Name	Description
`convert_x_unit`	Convert center to new_x_unit and rate to 1/new_x_unit.
`convert_y_unit`	Convert the y-axis unit by rescaling the amplitude parameter.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.

Attributes:

Name	Type	Description
`amplitude`	`Parameter`	Get the amplitude parameter.
`center`	`Parameter`	Get the center parameter.
`rate`	`Parameter`	Get the rate parameter.
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.

Attributes

amplitude property writable

Get the amplitude parameter.

Returns:

Type	Description
`Parameter`	The amplitude Parameter with unit `y_unit`.

center property writable

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center (x_0) Parameter with unit `x_unit`.

rate property writable

Get the rate parameter.

Returns:

Type	Description
`Parameter`	The exponential rate (B) Parameter with unit `1/x_unit`.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

Methods:

convert_x_unit(new_x_unit)

Convert center to new_x_unit and rate to 1/new_x_unit.

The amplitude carries y_unit only and is unaffected.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit. The rate unit is set to `1/new_x_unit`.	required

convert_y_unit(new_y_unit)

Convert the y-axis unit by rescaling the amplitude parameter.

The amplitude is rescaled from old_y_unit to new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`expression_component`

Classes:

Name	Description
`ExpressionComponent`	Model component defined by a symbolic expression.

Classes

ExpressionComponent(expression, parameters=None, parameter_units=None, x_unit='meV', y_unit='dimensionless', name='Expression', display_name=None, unique_name=None)

Model component defined by a symbolic expression.

The expression must contain x as the independent variable. All other symbols are treated as free parameters, which can be accessed and set as attributes after construction. Supported functions include exp, sin, cos, sqrt, erf, and others — see the _ALLOWED_FUNCS class variable for the full list.

Examples:

Defining a custom Gaussian expression

Parameters are given as a dictionary of initial values and can be accessed as attributes after construction:

import numpy as np
import easydynamics.sample_model as sm

expr = sm.ExpressionComponent(
    'A * exp(-(x - x0)**2 / (2*sigma**2))',
    parameters={'A': 10, 'x0': 0, 'sigma': 1},
    x_unit='meV',
    display_name='Gaussian Peak',
)
x = np.linspace(-3, 3, 100)
values = expr.evaluate(x)

Modifying parameter values after construction

Parameters can be set directly as attributes:

expr.A = 5
expr.sigma = 0.5

Giving parameters units

Parameters are dimensionless by default. Units can be given per parameter at construction, or relabelled later with set_unit (the numeric value is kept as-is). When units are in use, the unit of the evaluated expression is derived from the parameter units and x_unit (see output_unit), and a warning is issued if it does not match y_unit:

expr = sm.ExpressionComponent(
    'A * exp(-(x - x0)**2 / (2*sigma**2))',
    parameters={'A': 10, 'x0': 0, 'sigma': 1},
    parameter_units={'A': '1/meV', 'x0': 'meV', 'sigma': 'meV'},
    y_unit='1/meV',
)
expr.set_unit('A', '1/meV')

Physical constants

The symbols hbar (in meV*s) and kb (in meV/K) are provided automatically as read-only constants (DescriptorNumbers) when they appear in the expression:

boltzmann = sm.ExpressionComponent(
    'exp(-x / (kb * T))',
    parameters={'T': 300.0},
    parameter_units={'T': 'K'},
)

Use e.g. boltzmann.kb.convert_unit('eV/K') to work in another unit (this rescales the value, unlike set_unit).

Parameters:

Name	Type	Description	Default
`expression`	`str`	The symbolic expression as a string. Must contain 'x' as the independent variable. The symbols `hbar` and `kb` are provided automatically as read-only physical constants (in meVs and meV/K respectively) unless overridden via parameters*.	required
`parameters`	`dict[str, Numeric] \| None`	Dictionary of parameter names and their initial values. Parameters that are not given a unit are dimensionless.	`None`
`parameter_units`	`dict[str, str \| sc.Unit] \| None`	Optional units per parameter name. Each entry sets the unit of the named parameter without rescaling its value (see :meth:`set_unit`), and takes precedence over the unit of a Parameter instance given in parameters. When units are in use, a warning is issued if the expression's output unit does not match y_unit.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'Expression'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Unique name for the component.	`None`

Raises:

Type	Description
`ValueError`	If the expression is invalid or does not contain 'x', or if parameter_units names a parameter that is not in the expression.
`TypeError`	If any parameter value is not numeric, or if parameter_units is not a dictionary.

Methods:

Name	Description
`get_all_variables`	Return all parameters.
`set_unit`	Set the unit of a parameter without rescaling its value.
`convert_x_unit`	Convert the x-axis unit of the expression.
`convert_y_unit`	Convert the y-axis unit of the expression.
`__getattr__`	Allow access to parameters and physical constants as attributes.
`__setattr__`	Allow setting parameter values as attributes.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.

Attributes:

Name	Type	Description
`expression`	`str`	Return the original expression string.
`constants`	`dict[str, DescriptorNumber]`	Get the physical constants used by the expression.
`output_unit`	`str`	Get the unit of the evaluated expression, derived from x_unit and the parameter units.
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.

Attributes

expression property writable

Return the original expression string.

Returns:

Type	Description
`str`	The original expression string provided at initialization.

constants property

Get the physical constants used by the expression.

Returns:

Type	Description
`dict[str, DescriptorNumber]`	The automatically provided constants (e.g. `hbar`, `kb`) keyed by symbol name.

output_unit property

Get the unit of the evaluated expression, derived from x_unit and the parameter units.

The unit is propagated through the expression tree: addition requires compatible units, multiplication and powers combine units, and functions like exp or sin require a dimensionless argument. Propagation raises sc.UnitError if the expression is not unit-consistent (e.g. adding meV to a dimensionless quantity, or taking exp of a quantity with a unit).

Returns:

Type	Description
`str`	The unit of the evaluated expression.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

Methods:

get_all_variables()

Return all parameters.

Returns:

Type	Description
`list[Parameter]`	List of all parameters in the expression.

set_unit(name, unit)

Set the unit of a parameter without rescaling its value.

This relabels the unit: the numeric value, bounds, and variance are kept as-is. Use Parameter.convert_unit instead to rescale a value into a compatible unit. Issues a warning if the resulting output unit of the expression no longer matches y_unit. Raises the same exceptions as :meth:_relabel_parameter_unit on invalid input.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the parameter whose unit to set.	required
`unit`	`str \| sc.Unit`	The new unit.	required

convert_x_unit(_new_unit)

Convert the x-axis unit of the expression.

Unit conversion is not implemented for ExpressionComponent. Should it ever be needed, the viable path is dimensional analysis on the parameter units: for each parameter, determine the power n of the x-dimension in its unit and rescale its value by the x-unit conversion factor to the power n (the generalization of Polynomial's power-law rescaling). This only works when x_unit has a single unambiguous dimension.

Parameters:

Name	Type	Description	Default
`_new_unit`	`str \| sc.Unit`	The new unit to convert to (ignored).	required

Raises:

Type	Description
`NotImplementedError`	Always raised to indicate unit conversion is not supported.

convert_y_unit(_new_unit)

Convert the y-axis unit of the expression.

Unit conversion is not implemented for ExpressionComponent. See convert_x_unit for the approach that would make it possible.

Parameters:

Name	Type	Description	Default
`_new_unit`	`str \| sc.Unit`	The new unit to convert to (ignored).	required

Raises:

Type	Description
`NotImplementedError`	Always raised to indicate unit conversion is not supported.

__getattr__(name)

Allow access to parameters and physical constants as attributes.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the parameter or constant to access.	required

Raises:

Type	Description
`AttributeError`	If the parameter does not exist.

Returns:

Type	Description
`Parameter \| DescriptorNumber`	The parameter or constant with the given name.

__setattr__(name, value)

Allow setting parameter values as attributes.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the parameter to set.	required
`value`	`Numeric`	New value for the parameter.	required

Raises:

Type	Description
`AttributeError`	If the name refers to a physical constant.
`TypeError`	If the value is not numeric.

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`gaussian`

Classes:

Name	Description
`Gaussian`	Model of a Gaussian function.

Classes

Gaussian(area=1.0, center=None, width=1.0, x_unit='meV', y_unit='dimensionless', name='Gaussian', display_name=None, unique_name=None)

Model of a Gaussian function.

\[ I(x) = \frac{A}{\sigma \sqrt{2\pi}} \exp\left( -\frac{1}{2} \left(\frac{x - x_0}{\sigma}\right)^2 \right) \]

where $A$ is the area, $x_0$ is the center, and $\sigma$ is the width. area has unit = x_unit * y_unit; center and width have unit = x_unit.

If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Examples:

Creating a Gaussian with a fixed center (typical QENS use)

By default the center is fixed at 0, which is the typical setup for a QENS elastic line:

import numpy as np
import easydynamics.sample_model as sm

g = sm.Gaussian(area=1.0, width=0.5)
x = np.linspace(-2, 2, 100)
values = g.evaluate(x)

Creating a Gaussian with a free center and modifying parameters

Pass a numeric value for center to leave it free during fitting, and use the property setters to update parameter values after construction:

import easydynamics.sample_model as sm

g = sm.Gaussian(area=2.0, center=0.5, width=0.3, name='Peak')
g.area = 3.0
g.width = 0.2

Parameters:

Name	Type	Description	Default
`area`	`Numeric`	Integrated area under the Gaussian. Unit is `x_unit * y_unit`.	`1.0`
`center`	`Numeric \| None`	Peak position in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`width`	`Numeric`	Standard deviation (sigma) in x_unit. Must be strictly positive.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center and width are stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'Gaussian'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`convert_x_unit`	Convert x-axis parameters (center, width) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis (output) unit by rescaling the area parameter.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.

Attributes:

Name	Type	Description
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter.
`width`	`Parameter`	Get the width parameter (sigma).
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.

Attributes

area property writable

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

center property writable

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center Parameter with unit `x_unit`.

width property writable

Get the width parameter (sigma).

Returns:

Type	Description
`Parameter`	The width (sigma) Parameter with unit `x_unit`.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

Methods:

convert_x_unit(new_x_unit)

Convert x-axis parameters (center, width) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

convert_y_unit(new_y_unit)

Convert the y-axis (output) unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`lorentzian`

Classes:

Name	Description
`Lorentzian`	Model of a Lorentzian function.

Classes

Lorentzian(area=1.0, center=None, width=1.0, x_unit='meV', y_unit='dimensionless', name='Lorentzian', display_name=None, unique_name=None)

Model of a Lorentzian function.

\[ I(x) = \frac{A}{\pi} \frac{\Gamma}{(x - x_0)^2 + \Gamma^2} \]

where $A$ is the area, $x_0$ is the center, and $\Gamma$ is the hald width at half max (HWHM). area has unit = x_unit * y_unit; center and width have unit = x_unit.

If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Examples:

Creating a Lorentzian with a fixed center (typical QENS use)

By default the center is fixed at 0, which is the typical setup for a QENS quasi-elastic line:

import numpy as np
import easydynamics.sample_model as sm

l = sm.Lorentzian(area=1.0, width=0.3)
x = np.linspace(-2, 2, 100)
values = l.evaluate(x)

Creating a Lorentzian with a free center and modifying parameters

Pass a numeric value for center to leave it free during fitting:

import easydynamics.sample_model as sm

l = sm.Lorentzian(area=2.0, center=0.5, width=0.3, name='QE peak')
l.area = 3.0
l.width = 0.2

Parameters:

Name	Type	Description	Default
`area`	`Numeric`	Integrated area under the Lorentzian. Unit is `x_unit * y_unit`.	`1.0`
`center`	`Numeric \| None`	Peak position in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`width`	`Numeric`	Half-width at half-maximum (HWHM, gamma) in x_unit. Must be strictly positive.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center and width are stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'Lorentzian'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`convert_x_unit`	Convert x-axis parameters (center, width) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis (output) unit by rescaling the area parameter.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.

Attributes:

Name	Type	Description
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter.
`width`	`Parameter`	Get the width parameter (HWHM).
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.

Attributes

area property writable

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

center property writable

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center Parameter with unit `x_unit`.

width property writable

Get the width parameter (HWHM).

Returns:

Type	Description
`Parameter`	The HWHM (gamma) Parameter with unit `x_unit`.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

Methods:

convert_x_unit(new_x_unit)

Convert x-axis parameters (center, width) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

convert_y_unit(new_y_unit)

Convert the y-axis (output) unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`mixins`

Classes:

Name	Description
`CreateParametersMixin`	Provides parameter creation and validation methods for model components.

Classes

CreateParametersMixin

Provides parameter creation and validation methods for model components.

area_unit = x_unit * y_unit, so when y_unit='dimensionless', area_unit = x_unit.

`model_component`

Classes:

Name	Description
`ModelComponent`	Abstract base class for all model components.

Classes

ModelComponent(x_unit='meV', y_unit='dimensionless', name='ModelComponent', display_name=None, unique_name=None)

Abstract base class for all model components.

x_unit : str | sc.Unit, default='meV' Unit for the x-axis (independent variable) of this component. y_unit : str | sc.Unit, default='dimensionless' Unit for the y-axis (dependent variable / output) of this component. name : str, default='ModelComponent' Internal name used for parameter labelling and logging. display_name : str | None, default=None Human-readable name shown in plots and reports. Falls back to name if None. unique_name : str | None, default=None Globally unique identifier. Auto-generated if None.

Methods:

Name	Description
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`convert_x_unit`	Convert the x-axis unit of the component.
`convert_y_unit`	Convert the y-axis (output) unit. Subclasses with an area parameter should override this.
`evaluate`	Evaluate the model component at input x.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

Methods:

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

convert_x_unit(new_x_unit)

Convert the x-axis unit of the component.

The base implementation converts all parameters. Subclasses with mixed-unit parameters (e.g. area ≠ x_unit) should override this method. If the conversion between the current unit and new_x_unit fails, the component is rolled back to its original unit and the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

Raises:

Type	Description
`TypeError`	If new_x_unit is not a `str` or `sc.Unit`.

convert_y_unit(new_y_unit)

Convert the y-axis (output) unit. Subclasses with an area parameter should override this.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

Raises:

Type	Description
`NotImplementedError`	Always raised in this base implementation. Subclasses that carry an area parameter (area_unit = x_unit * y_unit) must override this method to rescale the area appropriately.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

Functions:

`polynomial`

Classes:

Name	Description
`Polynomial`	Polynomial function component.

Classes

Polynomial(coefficients=(0.0,), x_unit='meV', y_unit='dimensionless', name='Polynomial', display_name=None, unique_name=None, suppress_warnings=False)

Polynomial function component.

\[ I(x) = c_0 + c_1 x + c_2 x^2 + ... + c_N x^N \]

Coefficients are stored as dimensionless Parameters. When x_unit changes, the coefficient values are rescaled so the evaluated result stays the same. The output unit is y_unit.

Examples:

Creating a constant background (degree 0)

import numpy as np
import easydynamics.sample_model as sm

poly = sm.Polynomial(coefficients=[1.5])
x = np.linspace(-5, 5, 100)
values = poly.evaluate(x)

Creating a linear background (degree 1)

Coefficients are ordered as [c0, c1, ...], where c0 is the constant term:

import easydynamics.sample_model as sm

poly = sm.Polynomial(coefficients=[2.0, 0.1], name='Background')
poly.coefficients = [1.5, 0.05]

Creating a sparse polynomial from a dict

Powers that are not listed are filled with coefficients fixed to zero:

import easydynamics.sample_model as sm

poly = sm.Polynomial(coefficients={2: 1.5})  # 1.5*x^2, with c0 and c1 fixed at 0

Changing the degree after construction

import easydynamics.sample_model as sm

poly = sm.Polynomial(coefficients=[2.0, 0.1])
poly.add_coefficient(0.05)  # now 2.0 + 0.1*x + 0.05*x^2
removed = poly.remove_coefficient()  # returns 0.05, back to 2.0 + 0.1*x

coefficients : _CoefficientsInput, default=(0.0,) Either an ordered sequence of polynomial coefficients [c0, c1, ..., cN] where the polynomial is c0 + c1*x + c2*x^2 + ... + cN*x^N, or a sparse dict mapping integer powers to numeric values (e.g. {2: 1.5} for 1.5*x^2).

For a sequence, each element may be a plain numeric value (wrapped into a dimensionless
:class:`Parameter`) or an existing :class:`Parameter` instance.  For a dict, powers not
present are filled with fixed-to-zero Parameters, and the degree is taken from the
largest key.  Must contain at least one element.

x_unit : str | sc.Unit, default='meV' Unit of the x-axis. When the x_unit is changed via :meth:convert_x_unit, coefficient values are rescaled by power-law factors so the evaluated output remains unchanged. y_unit : str | sc.Unit, default='dimensionless' Unit of the y-axis (output). name : str, default='Polynomial' Name of the component. display_name : str | None, default=None Display name shown when plotting. Falls back to name if None. unique_name : str | None, default=None Globally unique identifier. Auto-generated if None. suppress_warnings : bool, default=False Whether to suppress warnings

Raises:

Type	Description
`TypeError`	If coefficients is not a list, tuple, ndarray, or dict, if any sequence element is neither numeric nor a :class:`Parameter`, or if any dict key is not an integer or dict value is not numeric.
`ValueError`	If coefficients is empty, or if any dict key is negative.

Methods:

Name	Description
`coefficient_values`	Get the coefficients of the polynomial as a list.
`add_coefficient`	Add a new coefficient at the next highest power, increasing the degree by one.
`remove_coefficient`	Remove the highest-power coefficient, decreasing the degree by one.
`get_all_variables`	Returns
`convert_x_unit`	Convert the x-axis unit by rescaling coefficients with power-law factors.
`convert_y_unit`	Rescale all coefficients so the evaluated output remains the same physical value.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.

Attributes:

Name	Type	Description
`coefficients`	`list[Parameter]`	Get the coefficients of the polynomial as a list of Parameters.
`degree`	`int`	Returns
`suppress_warnings`	`bool`	Get whether or not to suppress warnings.
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.

Attributes

coefficients property writable

Get the coefficients of the polynomial as a list of Parameters.

Returns:

Type	Description
`list[Parameter]`	A shallow copy of the internal coefficient list `[c0, c1, ..., cN]`. Modifying the returned list does not affect the model; use the setter to replace values.

degree property writable

Returns:

Type	Description
`int`	Polynomial degree, equal to `len(coefficients) - 1`.

suppress_warnings property writable

Get whether or not to suppress warnings.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

Methods:

coefficient_values()

Get the coefficients of the polynomial as a list.

Returns:

Type	Description
`list[float]`	Current numeric values of all coefficients `[c0.value, c1.value, ..., cN.value]`.

add_coefficient(value=0.0, fixed=False)

Add a new coefficient at the next highest power, increasing the degree by one.

Parameters:

Name	Type	Description	Default
`value`	`Numeric`	The numeric value of the new coefficient.	`0.0`
`fixed`	`bool`	If True, the new coefficient is fixed (not free for fitting).	`False`

Raises:

Type	Description
`TypeError`	If value is not a numeric value.

remove_coefficient()

Remove the highest-power coefficient, decreasing the degree by one.

Returns:

Type	Description
`float`	The value of the removed coefficient.

Raises:

Type	Description
`ValueError`	If only one coefficient remains; a Polynomial must always keep at least one.

get_all_variables()

Returns:

Type	Description
`list[DescriptorBase]`	The coefficient Parameters that constitute the fittable variables of this polynomial component.

convert_x_unit(new_x_unit)

Convert the x-axis unit by rescaling coefficients with power-law factors.

Each coefficient c_i is rescaled by (old_scale / new_scale) ** i so the evaluated polynomial output is unchanged after the conversion.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

Raises:

Type	Description
`UnitError`	If new_x_unit is not a valid unit string or `sc.Unit`, or if the conversion between the current unit and new_x_unit fails.

convert_y_unit(new_y_unit)

Rescale all coefficients so the evaluated output remains the same physical value.

All coefficients are multiplied by the conversion factor from old_y_unit to new_y_unit so that I(x) [new_y_unit] represents the same physical quantity as I(x) [old_y_unit].

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit. Must be dimensionally compatible with the current y_unit.	required

Raises:

Type	Description
`UnitError`	If new_y_unit is not a valid unit string or `sc.Unit`, or if the conversion between the current y_unit and new_y_unit fails.

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`voigt`

Classes:

Name	Description
`Voigt`	Voigt profile — convolution of Gaussian and Lorentzian.

Classes

Voigt(area=1.0, center=None, gaussian_width=1.0, lorentzian_width=1.0, x_unit='meV', y_unit='dimensionless', name='Voigt', display_name=None, unique_name=None)

Voigt profile — convolution of Gaussian and Lorentzian.

Uses scipy.special.voigt_profile to evaluate the profile. area has unit = x_unit * y_unit; center, gaussian_width, and lorentzian_width have unit = x_unit.

If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Examples:

Creating a Voigt profile with a fixed center (typical QENS use)

The Voigt profile is a convolution of a Gaussian and a Lorentzian. By default the center is fixed at 0:

import numpy as np
import easydynamics.sample_model as sm

v = sm.Voigt(area=1.0, gaussian_width=0.1, lorentzian_width=0.3)
x = np.linspace(-2, 2, 100)
values = v.evaluate(x)

Setting the Gaussian and Lorentzian widths independently

Pass a numeric value for center to leave it free during fitting, and use the property setters to adjust the two width components after construction:

import easydynamics.sample_model as sm

v = sm.Voigt(area=2.0, center=0.5, gaussian_width=0.2, lorentzian_width=0.4, name='Peak')
v.gaussian_width = 0.1
v.lorentzian_width = 0.2

Parameters:

Name	Type	Description	Default
`area`	`Numeric \| Parameter`	Integrated area under the Voigt profile. Unit is `x_unit * y_unit`.	`1.0`
`center`	`Numeric \| Parameter \| None`	Peak position in x_unit. If None, defaults to 0 and the center parameter is fixed.	`None`
`gaussian_width`	`Numeric \| Parameter`	Gaussian component standard deviation (sigma) in x_unit. Must be strictly positive.	`1.0`
`lorentzian_width`	`Numeric \| Parameter`	Lorentzian component HWHM (gamma) in x_unit. Must be strictly positive.	`1.0`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis. center, gaussian_width, and lorentzian_width are stored in this unit. area_unit = x_unit * y_unit.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`name`	`str`	Name of the component.	`'Voigt'`
`display_name`	`str \| None`	Display name shown when plotting. Falls back to name if None.	`None`
`unique_name`	`str \| None`	Globally unique identifier. Auto-generated if None.	`None`

Methods:

Name	Description
`convert_x_unit`	Convert x-axis parameters (center, widths) and area to new_x_unit.
`convert_y_unit`	Convert the y-axis unit by rescaling the area parameter.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__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`.
`get_fit_targets`	Get the fittable predictions of this component as FitTargets.
`fix_all_parameters`	Fix all parameters in the model component.
`free_all_parameters`	Free all parameters in the model component.
`evaluate`	Evaluate the model component at input x.

Attributes:

Name	Type	Description
`area`	`Parameter`	Get the area parameter.
`center`	`Parameter`	Get the center parameter.
`gaussian_width`	`Parameter`	Get the Gaussian width parameter (sigma).
`lorentzian_width`	`Parameter`	Get the Lorentzian width parameter (HWHM).
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.

Attributes

area property writable

Get the area parameter.

Returns:

Type	Description
`Parameter`	The area Parameter with unit `x_unit * y_unit`.

center property writable

Get the center parameter.

Returns:

Type	Description
`Parameter`	The center Parameter with unit `x_unit`.

gaussian_width property writable

Get the Gaussian width parameter (sigma).

Returns:

Type	Description
`Parameter`	The Gaussian component width (sigma) Parameter with unit `x_unit`.

lorentzian_width property writable

Get the Lorentzian width parameter (HWHM).

Returns:

Type	Description
`Parameter`	The Lorentzian component HWHM (gamma) Parameter with unit `x_unit`.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

Methods:

convert_x_unit(new_x_unit)

Convert x-axis parameters (center, widths) and area to new_x_unit.

Parameters:

Name	Type	Description	Default
`new_x_unit`	`str \| sc.Unit`	Target x-axis unit. Must be dimensionally compatible with the current x_unit.	required

convert_y_unit(new_y_unit)

Convert the y-axis unit by rescaling the area parameter.

The area is rescaled from x_unit * old_y_unit to x_unit * new_y_unit.

Parameters:

Name	Type	Description	Default
`new_y_unit`	`str \| sc.Unit`	Target y-axis unit.	required

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables()

Get all Descriptor and Parameter objects as a list.

Returns:

Type	Description
`List[DescriptorBase]`	List of `Descriptor` and `Parameter` objects.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

get_fit_targets()

Get the fittable predictions of this component as FitTargets.

Component models have a single prediction — their evaluate — named 'value' with no default dataset key; FitBinding supplies the dataset key to fit against. The target is a snapshot: its units reflect the component's x_unit/y_unit at call time (None means raw values are fitted without unit conversion).

Returns:

Type	Description
`list[FitTarget]`	A single FitTarget wrapping this component's evaluate.

fix_all_parameters()

Fix all parameters in the model component.

Sets fixed=True on every fittable parameter returned by :meth:get_fittable_parameters.

free_all_parameters()

Free all parameters in the model component.

Sets fixed=False on every fittable parameter returned by :meth:get_fittable_parameters.

evaluate(x, output='numpy')

Evaluate the model component at input x.

When x carries a unit (scipp input), parameter values are temporarily converted to that unit for the computation without mutating the parameters.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Input x values.	required
`output`	`str`	'numpy' returns np.ndarray; 'scipp' returns sc.Variable with y_unit.	`'numpy'`

Raises:

Type	Description
`ValueError`	If output is not 'numpy' or 'scipp'.

Returns:

Type	Description
`np.ndarray \| sc.Variable`	Evaluated model values at x.

`diffusion_model`

Modules:

Name	Description
`brownian_translational_diffusion`
`delta_lorentz`
`diffusion_model_base`
`jump_translational_diffusion`

Classes:

Name	Description
`BrownianTranslationalDiffusion`	Model of Brownian translational diffusion, consisting of a Lorentzian function for each
`JumpTranslationalDiffusion`	Model of Jump translational diffusion.

Classes

`BrownianTranslationalDiffusion(scale=1.0, diffusion_coefficient=1.0, Q=None, x_unit='meV', y_unit='dimensionless', name='BrownianTranslationalDiffusion', display_name='BrownianTranslationalDiffusion', lorentzian_name=None, lorentzian_display_name=None, unique_name=None)`

Model of Brownian translational diffusion, consisting of a Lorentzian function for each Q-value, where the width is given by $D Q^2$, where $D$ is the diffusion coefficient. The area of the Lorentzians is given by the scale parameter multiplied by the QISF, which is 1 for this model. The EISF is 0 for this model, so there is no delta function component. Q is assumed to have units of 1/angstrom. Creates ComponentCollections with Lorentzian components for given Q-values.

Examples:

Creating a BrownianTranslationalDiffusion model

The model creates one Lorentzian per Q-value, with width $D Q^2$. Pass Q values at construction or later via create_component_collections:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
diffusion_model = sm.BrownianTranslationalDiffusion(
    scale=1.0,
    diffusion_coefficient=2.4e-9,
    Q=Q,
)
component_collections = diffusion_model.create_component_collections()

See also the tutorials.

Parameters:

Name	Type	Description	Default
`scale`	`Numeric`	Scale factor for the diffusion model. Must be a non-negative number.	`1.0`
`diffusion_coefficient`	`Numeric`	Diffusion coefficient D in m^2/s.	`1.0`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis (energy/frequency). Must be convertible to meV.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity). Determines scale.unit = x_unit * y_unit.	`'dimensionless'`
`name`	`str`	Name of the diffusion model.	`'BrownianTranslationalDiffusion'`
`display_name`	`str \| None`	Display name of the diffusion model.	`'BrownianTranslationalDiffusion'`
`lorentzian_name`	`str \| None`	Name of the Lorentzian component. If None, it will be set to the name of the diffusion model.	`None`
`lorentzian_display_name`	`str \| None`	Display name of the Lorentzian component. If None, it will be set to the lorentzian_name.	`None`
`unique_name`	`str \| None`	Unique name of the diffusion model. If None, a unique name will be generated. By default, None.	`None`

Raises:

Type	Description
`TypeError`	If scale or diffusion_coefficient is not a number.
`ValueError`	If scale or diffusion_coefficient is negative.

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`get_all_variables`	Get all variables from the diffusion model.
`get_all_parameters`	Get all Parameters from the diffusion model.
`get_fittable_parameters`	Get all fittable Parameters from the diffusion model.
`get_free_parameters`	Get all free Parameters from the diffusion model.
`get_fit_parameters`	Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of the diffusion model.
`convert_y_unit`	Convert the y-axis unit of the diffusion model.
`get_fit_targets`	Get the fittable predictions of the diffusion model as FitTargets.
`get_global_variables`	Get all global variables from the diffusion model.
`get_independent_variables`	Get the independent variables from the diffusion model. If Q_index is provided, only the
`get_component_collections`	Get the ComponentCollection at the given Q index.
`calculate_width`	Calculate the half-width at half-maximum (HWHM) for the diffusion model.
`calculate_EISF`	Calculate the Elastic Incoherent Structure Factor (EISF) for the Brownian translational
`calculate_QISF`	Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).
`create_component_collections`	Create ComponentCollection components for the Brownian translational diffusion model at

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`scale`	`Parameter`	Get the scale parameter of the diffusion model.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.
`lorentzian_name`	`str`	Get the name of the Lorentzian component.
`lorentzian_display_name`	`str \| None`	Get the display name of the Lorentzian component.
`diffusion_coefficient`	`Parameter`	Get the diffusion coefficient parameter D.

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

scale property writable

Get the scale parameter of the diffusion model.

Returns:

Type	Description
`Parameter`	Scale parameter of the diffusion model.

Q property writable

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

lorentzian_name property writable

Get the name of the Lorentzian component.

Returns:

Type	Description
`str`	Name of the Lorentzian component.

lorentzian_display_name property writable

Get the display name of the Lorentzian component.

Returns:

Type	Description
`str \| None`	Display name of the Lorentzian component, or None if not set.

diffusion_coefficient property writable

Get the diffusion coefficient parameter D.

Returns:

Type	Description
`Parameter`	Diffusion coefficient D in m^2/s.

Methods:

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables(Q_index=None)

Get all variables from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get variables from. If None, all variables from all ComponentCollections are returned, in addition to the global variables.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

get_all_parameters(Q_index=None)

Get all Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get parameters from. If None, all parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

get_fittable_parameters(Q_index=None)

Get all fittable Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fittable parameters from. If None, all fittable parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fittable Parameters from the diffusion model.

get_free_parameters(Q_index=None)

Get all free Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get free parameters from. If None, all free parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all free Parameters from the diffusion model.

get_fit_parameters(Q_index=None)

Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fit parameters from. If None, all fit parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fit Parameters from the diffusion model.

clear_Q(confirm=False)

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

convert_x_unit(unit)

Convert the x-axis unit of the diffusion model.

Converts the scale parameter (unit x_unit * y_unit), any subclass-specific x-unit parameters, and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. Only energy units are supported (the unit must be convertible to meV).

Unit validation raises UnitError when the unit is not convertible to meV. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

convert_y_unit(unit)

Convert the y-axis unit of the diffusion model.

Converts the scale parameter from x_unit * old_y_unit to x_unit * new_y_unit and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. The new y-unit must be dimensionally compatible with the current one; the scale conversion raises UnitError otherwise. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

get_fit_targets()

Get the fittable predictions of the diffusion model as FitTargets.

The base implementation declares 'area' (scale * QISF(Q)) and 'width' (the HWHM Gamma(Q)), with default dataset keys derived from the Lorentzian component's name. Subclasses with additional predictions (e.g. a delta-function weight) extend this list. The targets are snapshots: units and default keys reflect the model state at call time.

Returns:

Type	Description
`list[FitTarget]`	The fittable predictions of this model.

get_global_variables()

Get all global variables from the diffusion model.

Returns:

Type	Description
`list[Parameter]`	A list of all global variables from the diffusion model.

get_independent_variables(Q_index=None)

Get the independent variables from the diffusion model. If Q_index is provided, only the independent variables for the specified Q value will be returned. If Q_index is None, independent variables for all Q values will be returned. These are variables that are not global but also not part of the component collections.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value for which to get the independent variables. If None, independent variables for all Q values will be included.	`None`

Returns:

Type	Description
`list[Parameter]`	List of independent variables in the model.

get_component_collections(Q_index=None)

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the desired ComponentCollection. If None, all ComponentCollections are returned.	`None`

Returns:

Type	Description
`ComponentCollection \| list[ComponentCollection]`	The ComponentCollection at the specified Q index. If Q_index is None, a list of all ComponentCollections is returned.

calculate_width(Q=None)

Calculate the half-width at half-maximum (HWHM) for the diffusion model.

Parameters:

Name	Type	Description	Default
`Q`	`Q_type \| None`	Scattering vector in 1/angstrom.	`None`

Returns:

Type	Description
`np.ndarray`	HWHM values in the unit of the model (e.g., meV).

calculate_EISF(Q=None)

Calculate the Elastic Incoherent Structure Factor (EISF) for the Brownian translational diffusion model.

Parameters:

Name	Type	Description	Default
`Q`	`Q_type \| None`	Scattering vector in 1/angstrom.	`None`

Returns:

Type	Description
`np.ndarray`	EISF values (dimensionless).

calculate_QISF(Q=None)

Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

Parameters:

Name	Type	Description	Default
`Q`	`Q_type \| None`	Scattering vector in 1/angstrom.	`None`

Returns:

Type	Description
`np.ndarray`	QISF values (dimensionless).

create_component_collections()

Create ComponentCollection components for the Brownian translational diffusion model at given Q values.

Returns:

Type	Description
`list[ComponentCollection]`	List of ComponentCollections with Lorentzian components for each Q value. Each Lorentzian has a width given by $D*Q^2$ and an area given by the scale parameter multiplied by the QISF (which is 1 for this model).

`JumpTranslationalDiffusion(scale=1.0, diffusion_coefficient=1.0, relaxation_time=1.0, Q=None, x_unit='meV', y_unit='dimensionless', name='JumpTranslationalDiffusion', display_name='JumpTranslationalDiffusion', lorentzian_name=None, lorentzian_display_name=None, unique_name=None)`

Model of Jump translational diffusion.

The model consists of a Lorentzian function for each Q-value, where the width is given by

\[ \Gamma(Q) = \frac{Q^2}{1+D t Q^2}. \]

where $D$ is the diffusion coefficient and $t$ is the relaxation time. Q is assumed to have units of 1/angstrom. Creates ComponentCollections with Lorentzian components for given Q-values.

Examples:

Creating a JumpTranslationalDiffusion model

Pass the diffusion coefficient (in m²/s) and relaxation time (in ps) along with Q values:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
diffusion_model = sm.JumpTranslationalDiffusion(
    scale=1.0,
    diffusion_coefficient=2.4e-9,
    relaxation_time=1.0,
    Q=Q,
)
component_collections = diffusion_model.create_component_collections()

See also the tutorials.

Parameters:

Name	Type	Description	Default
`scale`	`Numeric`	Scale factor for the diffusion model. Must be a non-negative number.	`1.0`
`diffusion_coefficient`	`Numeric`	Diffusion coefficient D in m^2/s.	`1.0`
`relaxation_time`	`Numeric`	Relaxation time t in ps.	`1.0`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis (energy/frequency). Must be convertible to meV.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity). Determines scale.unit = x_unit * y_unit.	`'dimensionless'`
`name`	`str`	Name of the diffusion model.	`'JumpTranslationalDiffusion'`
`display_name`	`str \| None`	Display name of the diffusion model.	`'JumpTranslationalDiffusion'`
`lorentzian_name`	`str \| None`	Name of the Lorentzian component. If None, it will be set to the name of the diffusion model with '_Lorentzian' appended. By default, None.	`None`
`lorentzian_display_name`	`str \| None`	Display name of the Lorentzian component. If None, it will be set to the display name of the diffusion model with '_Lorentzian' appended. By default, None	`None`
`unique_name`	`str \| None`	Unique name of the diffusion model. If None, a unique name will be generated. By default, None.	`None`

Raises:

Type	Description
`TypeError`	If scale, diffusion_coefficient, or relaxation_time are not numbers.
`ValueError`	If scale, diffusion_coefficient, or relaxation_time are negative.

Methods:

Name	Description
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`get_all_variables`	Get all variables from the diffusion model.
`get_all_parameters`	Get all Parameters from the diffusion model.
`get_fittable_parameters`	Get all fittable Parameters from the diffusion model.
`get_free_parameters`	Get all free Parameters from the diffusion model.
`get_fit_parameters`	Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of the diffusion model.
`convert_y_unit`	Convert the y-axis unit of the diffusion model.
`get_fit_targets`	Get the fittable predictions of the diffusion model as FitTargets.
`get_global_variables`	Get all global variables from the diffusion model.
`get_independent_variables`	Get the independent variables from the diffusion model. If Q_index is provided, only the
`get_component_collections`	Get the ComponentCollection at the given Q index.
`calculate_width`	Calculate the half-width at half-maximum (HWHM) for the diffusion model. $\Gamma(Q) =
`calculate_EISF`	Calculate the Elastic Incoherent Structure Factor (EISF).
`calculate_QISF`	Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).
`create_component_collections`	Create ComponentCollection components for the diffusion model at given Q values.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`scale`	`Parameter`	Get the scale parameter of the diffusion model.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.
`lorentzian_name`	`str`	Get the name of the Lorentzian component.
`lorentzian_display_name`	`str \| None`	Get the display name of the Lorentzian component.
`diffusion_coefficient`	`Parameter`	Get the diffusion coefficient parameter D.
`relaxation_time`	`Parameter`	Get the relaxation time parameter t.

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

scale property writable

Get the scale parameter of the diffusion model.

Returns:

Type	Description
`Parameter`	Scale parameter of the diffusion model.

Q property writable

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

lorentzian_name property writable

Get the name of the Lorentzian component.

Returns:

Type	Description
`str`	Name of the Lorentzian component.

lorentzian_display_name property writable

Get the display name of the Lorentzian component.

Returns:

Type	Description
`str \| None`	Display name of the Lorentzian component, or None if not set.

diffusion_coefficient property writable

Get the diffusion coefficient parameter D.

Returns:

Type	Description
`Parameter`	Diffusion coefficient D.

relaxation_time property writable

Get the relaxation time parameter t.

Returns:

Type	Description
`Parameter`	Relaxation time t in ps.

Methods:

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables(Q_index=None)

Get all variables from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get variables from. If None, all variables from all ComponentCollections are returned, in addition to the global variables.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

get_all_parameters(Q_index=None)

Get all Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get parameters from. If None, all parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

get_fittable_parameters(Q_index=None)

Get all fittable Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fittable parameters from. If None, all fittable parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fittable Parameters from the diffusion model.

get_free_parameters(Q_index=None)

Get all free Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get free parameters from. If None, all free parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all free Parameters from the diffusion model.

get_fit_parameters(Q_index=None)

Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fit parameters from. If None, all fit parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fit Parameters from the diffusion model.

clear_Q(confirm=False)

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

convert_x_unit(unit)

Convert the x-axis unit of the diffusion model.

Converts the scale parameter (unit x_unit * y_unit), any subclass-specific x-unit parameters, and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. Only energy units are supported (the unit must be convertible to meV).

Unit validation raises UnitError when the unit is not convertible to meV. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

convert_y_unit(unit)

Convert the y-axis unit of the diffusion model.

Converts the scale parameter from x_unit * old_y_unit to x_unit * new_y_unit and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. The new y-unit must be dimensionally compatible with the current one; the scale conversion raises UnitError otherwise. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

get_fit_targets()

Get the fittable predictions of the diffusion model as FitTargets.

The base implementation declares 'area' (scale * QISF(Q)) and 'width' (the HWHM Gamma(Q)), with default dataset keys derived from the Lorentzian component's name. Subclasses with additional predictions (e.g. a delta-function weight) extend this list. The targets are snapshots: units and default keys reflect the model state at call time.

Returns:

Type	Description
`list[FitTarget]`	The fittable predictions of this model.

get_global_variables()

Get all global variables from the diffusion model.

Returns:

Type	Description
`list[Parameter]`	A list of all global variables from the diffusion model.

get_independent_variables(Q_index=None)

Get the independent variables from the diffusion model. If Q_index is provided, only the independent variables for the specified Q value will be returned. If Q_index is None, independent variables for all Q values will be returned. These are variables that are not global but also not part of the component collections.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value for which to get the independent variables. If None, independent variables for all Q values will be included.	`None`

Returns:

Type	Description
`list[Parameter]`	List of independent variables in the model.

get_component_collections(Q_index=None)

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the desired ComponentCollection. If None, all ComponentCollections are returned.	`None`

Returns:

Type	Description
`ComponentCollection \| list[ComponentCollection]`	The ComponentCollection at the specified Q index. If Q_index is None, a list of all ComponentCollections is returned.

calculate_width(Q=None)

Calculate the half-width at half-maximum (HWHM) for the diffusion model. $\Gamma(Q) = Q^2/(1+D t Q^2)$, where $D$ is the diffusion coefficient and $t$ is the relaxation time.

Parameters:

Name	Type	Description	Default
`Q`	`Q_type \| None`	Scattering vector in 1/angstrom. Can be a single value or an array of values. If None, Q values stored in the model are used.	`None`

Returns:

Type	Description
`np.ndarray`	HWHM values in the unit of the model (e.g., meV).

calculate_EISF(Q)

Calculate the Elastic Incoherent Structure Factor (EISF).

Parameters:

Name	Type	Description	Default
`Q`	`Q_type`	Scattering vector in 1/angstrom. Can be a single value or an array of values.	required

Returns:

Type	Description
`np.ndarray`	EISF values (dimensionless).

calculate_QISF(Q)

Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

Parameters:

Name	Type	Description	Default
`Q`	`Q_type`	Scattering vector in 1/angstrom. Can be a single value or an array of values.	required

Returns:

Type	Description
`np.ndarray`	QISF values (dimensionless).

create_component_collections()

Create ComponentCollection components for the diffusion model at given Q values.

Returns:

Type	Description
`list[ComponentCollection]`	List of ComponentCollections with Jump Diffusion Lorentzian components.

Modules

`brownian_translational_diffusion`

Classes:

Name	Description
`BrownianTranslationalDiffusion`	Model of Brownian translational diffusion, consisting of a Lorentzian function for each

Classes

BrownianTranslationalDiffusion(scale=1.0, diffusion_coefficient=1.0, Q=None, x_unit='meV', y_unit='dimensionless', name='BrownianTranslationalDiffusion', display_name='BrownianTranslationalDiffusion', lorentzian_name=None, lorentzian_display_name=None, unique_name=None)

Model of Brownian translational diffusion, consisting of a Lorentzian function for each Q-value, where the width is given by $D Q^2$, where $D$ is the diffusion coefficient. The area of the Lorentzians is given by the scale parameter multiplied by the QISF, which is 1 for this model. The EISF is 0 for this model, so there is no delta function component. Q is assumed to have units of 1/angstrom. Creates ComponentCollections with Lorentzian components for given Q-values.

Examples:

Creating a BrownianTranslationalDiffusion model

The model creates one Lorentzian per Q-value, with width $D Q^2$. Pass Q values at construction or later via create_component_collections:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
diffusion_model = sm.BrownianTranslationalDiffusion(
    scale=1.0,
    diffusion_coefficient=2.4e-9,
    Q=Q,
)
component_collections = diffusion_model.create_component_collections()

See also the tutorials.

Parameters:

Name	Type	Description	Default
`scale`	`Numeric`	Scale factor for the diffusion model. Must be a non-negative number.	`1.0`
`diffusion_coefficient`	`Numeric`	Diffusion coefficient D in m^2/s.	`1.0`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis (energy/frequency). Must be convertible to meV.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity). Determines scale.unit = x_unit * y_unit.	`'dimensionless'`
`name`	`str`	Name of the diffusion model.	`'BrownianTranslationalDiffusion'`
`display_name`	`str \| None`	Display name of the diffusion model.	`'BrownianTranslationalDiffusion'`
`lorentzian_name`	`str \| None`	Name of the Lorentzian component. If None, it will be set to the name of the diffusion model.	`None`
`lorentzian_display_name`	`str \| None`	Display name of the Lorentzian component. If None, it will be set to the lorentzian_name.	`None`
`unique_name`	`str \| None`	Unique name of the diffusion model. If None, a unique name will be generated. By default, None.	`None`

Raises:

Type	Description
`TypeError`	If scale or diffusion_coefficient is not a number.
`ValueError`	If scale or diffusion_coefficient is negative.

Methods:

Name	Description
`calculate_width`	Calculate the half-width at half-maximum (HWHM) for the diffusion model.
`calculate_EISF`	Calculate the Elastic Incoherent Structure Factor (EISF) for the Brownian translational
`calculate_QISF`	Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).
`create_component_collections`	Create ComponentCollection components for the Brownian translational diffusion model at
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`get_all_variables`	Get all variables from the diffusion model.
`get_all_parameters`	Get all Parameters from the diffusion model.
`get_fittable_parameters`	Get all fittable Parameters from the diffusion model.
`get_free_parameters`	Get all free Parameters from the diffusion model.
`get_fit_parameters`	Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of the diffusion model.
`convert_y_unit`	Convert the y-axis unit of the diffusion model.
`get_fit_targets`	Get the fittable predictions of the diffusion model as FitTargets.
`get_global_variables`	Get all global variables from the diffusion model.
`get_independent_variables`	Get the independent variables from the diffusion model. If Q_index is provided, only the
`get_component_collections`	Get the ComponentCollection at the given Q index.

Attributes:

Name	Type	Description
`diffusion_coefficient`	`Parameter`	Get the diffusion coefficient parameter D.
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`scale`	`Parameter`	Get the scale parameter of the diffusion model.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.
`lorentzian_name`	`str`	Get the name of the Lorentzian component.
`lorentzian_display_name`	`str \| None`	Get the display name of the Lorentzian component.

Attributes

diffusion_coefficient property writable

Get the diffusion coefficient parameter D.

Returns:

Type	Description
`Parameter`	Diffusion coefficient D in m^2/s.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

scale property writable

Get the scale parameter of the diffusion model.

Returns:

Type	Description
`Parameter`	Scale parameter of the diffusion model.

Q property writable

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

lorentzian_name property writable

Get the name of the Lorentzian component.

Returns:

Type	Description
`str`	Name of the Lorentzian component.

lorentzian_display_name property writable

Get the display name of the Lorentzian component.

Returns:

Type	Description
`str \| None`	Display name of the Lorentzian component, or None if not set.

Methods:

calculate_width(Q=None)

Calculate the half-width at half-maximum (HWHM) for the diffusion model.

Parameters:

Name	Type	Description	Default
`Q`	`Q_type \| None`	Scattering vector in 1/angstrom.	`None`

Returns:

Type	Description
`np.ndarray`	HWHM values in the unit of the model (e.g., meV).

calculate_EISF(Q=None)

Calculate the Elastic Incoherent Structure Factor (EISF) for the Brownian translational diffusion model.

Parameters:

Name	Type	Description	Default
`Q`	`Q_type \| None`	Scattering vector in 1/angstrom.	`None`

Returns:

Type	Description
`np.ndarray`	EISF values (dimensionless).

calculate_QISF(Q=None)

Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

Parameters:

Name	Type	Description	Default
`Q`	`Q_type \| None`	Scattering vector in 1/angstrom.	`None`

Returns:

Type	Description
`np.ndarray`	QISF values (dimensionless).

create_component_collections()

Create ComponentCollection components for the Brownian translational diffusion model at given Q values.

Returns:

Type	Description
`list[ComponentCollection]`	List of ComponentCollections with Lorentzian components for each Q value. Each Lorentzian has a width given by $D*Q^2$ and an area given by the scale parameter multiplied by the QISF (which is 1 for this model).

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables(Q_index=None)

Get all variables from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get variables from. If None, all variables from all ComponentCollections are returned, in addition to the global variables.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

get_all_parameters(Q_index=None)

Get all Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get parameters from. If None, all parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

get_fittable_parameters(Q_index=None)

Get all fittable Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fittable parameters from. If None, all fittable parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fittable Parameters from the diffusion model.

get_free_parameters(Q_index=None)

Get all free Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get free parameters from. If None, all free parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all free Parameters from the diffusion model.

get_fit_parameters(Q_index=None)

Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fit parameters from. If None, all fit parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fit Parameters from the diffusion model.

clear_Q(confirm=False)

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

convert_x_unit(unit)

Convert the x-axis unit of the diffusion model.

Converts the scale parameter (unit x_unit * y_unit), any subclass-specific x-unit parameters, and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. Only energy units are supported (the unit must be convertible to meV).

Unit validation raises UnitError when the unit is not convertible to meV. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

convert_y_unit(unit)

Convert the y-axis unit of the diffusion model.

Converts the scale parameter from x_unit * old_y_unit to x_unit * new_y_unit and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. The new y-unit must be dimensionally compatible with the current one; the scale conversion raises UnitError otherwise. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

get_fit_targets()

Get the fittable predictions of the diffusion model as FitTargets.

The base implementation declares 'area' (scale * QISF(Q)) and 'width' (the HWHM Gamma(Q)), with default dataset keys derived from the Lorentzian component's name. Subclasses with additional predictions (e.g. a delta-function weight) extend this list. The targets are snapshots: units and default keys reflect the model state at call time.

Returns:

Type	Description
`list[FitTarget]`	The fittable predictions of this model.

get_global_variables()

Get all global variables from the diffusion model.

Returns:

Type	Description
`list[Parameter]`	A list of all global variables from the diffusion model.

get_independent_variables(Q_index=None)

Get the independent variables from the diffusion model. If Q_index is provided, only the independent variables for the specified Q value will be returned. If Q_index is None, independent variables for all Q values will be returned. These are variables that are not global but also not part of the component collections.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value for which to get the independent variables. If None, independent variables for all Q values will be included.	`None`

Returns:

Type	Description
`list[Parameter]`	List of independent variables in the model.

get_component_collections(Q_index=None)

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the desired ComponentCollection. If None, all ComponentCollections are returned.	`None`

Returns:

Type	Description
`ComponentCollection \| list[ComponentCollection]`	The ComponentCollection at the specified Q index. If Q_index is None, a list of all ComponentCollections is returned.

`delta_lorentz`

Classes:

Name	Description
`DeltaLorentz`	Model of Delta function and Lorentzian with intensities given by the Debye-Waller factor. $$ I

Classes

DeltaLorentz(scale=1.0, mean_u_squared=0.0, A_0=1.0, lorentzian_width=1.0, allow_Q_variation=None, Q=None, x_unit='meV', y_unit='dimensionless', name='DeltaLorentz', display_name=None, lorentzian_name='Lorentzian', lorentzian_display_name=None, delta_name='Delta function', delta_display_name=None, unique_name=None)

Model of Delta function and Lorentzian with intensities given by the Debye-Waller factor. $$ I = K \exp \left( \frac{-\langle u^2 \rangle Q^2}{3} \right)[A_0 \delta(E) + (A_1) L(E, \Gamma)] $$,

where $K$ is the scale factor, $\langle u^2 \rangle$ is the mean square displacement, $Q$ is the scattering vector, $A_0$ and $A_1$ are the relative amplitudes of the delta function and Lorentzian, respectively, with the constraint that $A_0+A_1=1$, and $L(E, \Gamma)$ is the Lorentzian function with width $\Gamma$. $A_0$, $A_1$ and the width of the Lorentzian can be the same at all $Q$ or be allowed to vary with $Q$.

Examples:

Creating a DeltaLorentz model with Q-dependent parameters

Set allow_Q_variation to allow individual parameters to vary with Q:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
model = sm.DeltaLorentz(
    display_name='DiffusionModel',
    scale=1.0,
    mean_u_squared=0.02,
    A_0=0.7,
    lorentzian_width=1.0,
    allow_Q_variation={'A_0': True, 'lorentzian_width': True},
    Q=Q,
)
component_collections = model.create_component_collections()

See also the tutorials.

Parameters:

Name	Type	Description	Default
`scale`	`Numeric`	Scale factor for the diffusion model. Must be a non-negative number.	`1.0`
`mean_u_squared`	`Numeric`	Mean square displacement in angstrom^2.	`0.0`
`A_0`	`Numeric`	Amplitude of the delta function.	`1.0`
`lorentzian_width`	`Numeric`	Width of the Lorentzian function.	`1.0`
`allow_Q_variation`	`dict \| None`	Dict describing whether to allow Q variation of A_0 and the Lorentzian width. The dict can have the keys "A_0" and/or "lorentzian_width", with boolean values indicating whether to allow Q-dependence for each parameter. If None, no Q-dependence will be allowed.	`None`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis (energy/frequency). Must be convertible to meV.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity). Determines scale.unit = x_unit * y_unit.	`'dimensionless'`
`name`	`str`	Name of the diffusion model.	`'DeltaLorentz'`
`display_name`	`str \| None`	Display name of the diffusion model.	`None`
`lorentzian_name`	`str`	Name of the Lorentzian component. If None, it will be set to the name of the diffusion model.	`'Lorentzian'`
`lorentzian_display_name`	`str \| None`	Display name of the Lorentzian component. If None, it will be set to the display name of the diffusion model.	`None`
`delta_name`	`str`	Name of the delta function component.	`'Delta function'`
`delta_display_name`	`str \| None`	Display name of the delta function component. If None, it will be set to the display name of the delta function component.	`None`
`unique_name`	`str \| None`	Unique name of the diffusion model. If None, a unique name will be generated. By default, None.	`None`

Raises:

Type	Description
`TypeError`	If delta_name is not a string or if delta_display_name is not a string or None.

Methods:

Name	Description
`calculate_width`	Calculate the half-width at half-maximum (HWHM) for the diffusion model. If the width is
`calculate_EISF`	Calculate the Elastic Incoherent Structure Factor (EISF) for the diffusion model.
`calculate_QISF`	Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).
`create_component_collections`	Create ComponentCollections for the DeltaLorentz model at given Q values.
`get_fit_targets`	Get the fittable predictions of the DeltaLorentz model as FitTargets.
`get_global_variables`	Get all global variables from the diffusion model.
`get_independent_variables`	Get the independent variables from the diffusion model. If Q_index is provided, only the
`get_all_variables`	Get a list of all variables (Parameters and Descriptors) in the model.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`get_all_parameters`	Get all Parameters from the diffusion model.
`get_fittable_parameters`	Get all fittable Parameters from the diffusion model.
`get_free_parameters`	Get all free Parameters from the diffusion model.
`get_fit_parameters`	Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of the diffusion model.
`convert_y_unit`	Convert the y-axis unit of the diffusion model.
`get_component_collections`	Get the ComponentCollection at the given Q index.

Attributes:

Name	Type	Description
`mean_u_squared`	`Parameter`	Get the mean square displacement parameter.
`A_0`	`Parameter`	Get the amplitude of the delta function.
`A_1`	`Parameter`	Get the amplitude of the Lorentzian function.
`lorentzian_width`	`Parameter`	Get the width of the Lorentzian function.
`delta_name`	`str`	Get the name of the delta function component.
`delta_display_name`	`str`	Get the display name of the delta function component.
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`scale`	`Parameter`	Get the scale parameter of the diffusion model.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.
`lorentzian_name`	`str`	Get the name of the Lorentzian component.
`lorentzian_display_name`	`str \| None`	Get the display name of the Lorentzian component.

Attributes

mean_u_squared property writable

Get the mean square displacement parameter.

Returns:

Type	Description
`Parameter`	Mean square displacement in angstrom^2.

A_0 property writable

Get the amplitude of the delta function.

Returns:

Type	Description
`Parameter`	Amplitude of the delta function.

A_1 property writable

Get the amplitude of the Lorentzian function.

Returns:

Type	Description
`Parameter`	Amplitude of the Lorentzian function.

lorentzian_width property writable

Get the width of the Lorentzian function.

Returns:

Type	Description
`Parameter`	Width of the Lorentzian function.

delta_name property writable

Get the name of the delta function component.

Returns:

Type	Description
`str`	Name of the delta function component.

delta_display_name property writable

Get the display name of the delta function component.

Returns:

Type	Description
`str`	Display name of the delta function component.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

scale property writable

Get the scale parameter of the diffusion model.

Returns:

Type	Description
`Parameter`	Scale parameter of the diffusion model.

Q property writable

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

lorentzian_name property writable

Get the name of the Lorentzian component.

Returns:

Type	Description
`str`	Name of the Lorentzian component.

lorentzian_display_name property writable

Get the display name of the Lorentzian component.

Returns:

Type	Description
`str \| None`	Display name of the Lorentzian component, or None if not set.

Methods:

calculate_width(Q=None)

Calculate the half-width at half-maximum (HWHM) for the diffusion model. If the width is allowed to vary with Q then the requested Q values are matched against the Q stored in the model and the corresponding per-Q widths are returned. If the width is not allowed to vary then the same width is returned for all Q values.

Parameters:

Name	Type	Description	Default
`Q`	`Q_type`	Scattering vector in 1/angstrom. If None, the Q stored in the model is used.	`None`

Returns:

Type	Description
`np.ndarray`	HWHM values in the unit of the model (e.g., meV).

Raises:

Type	Description
`ValueError`	If Q-variation is enabled but Q has not been set on the model yet, or if the requested Q values do not match the stored ones.

calculate_EISF(Q=None)

Calculate the Elastic Incoherent Structure Factor (EISF) for the diffusion model.

Parameters:

Name	Type	Description	Default
`Q`	`Q_type`	Scattering vector in 1/angstrom.	`None`

Returns:

Type	Description
`np.ndarray`	EISF values (dimensionless).

calculate_QISF(Q=None)

Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

Parameters:

Name	Type	Description	Default
`Q`	`Q_type`	Scattering vector in 1/angstrom.	`None`

Returns:

Type	Description
`np.ndarray`	QISF values (dimensionless).

create_component_collections()

Create ComponentCollections for the DeltaLorentz model at given Q values.

Returns:

Type	Description
`list[ComponentCollection]`	List of ComponentCollections with Lorentzian and delta function components for each Q value.

get_fit_targets()

Get the fittable predictions of the DeltaLorentz model as FitTargets.

Extends the base 'area' and 'width' predictions with 'delta_area' (scale * EISF(Q), the delta function's weight), whose default dataset key is derived from the delta component's name.

Returns:

Type	Description
`list[FitTarget]`	The fittable predictions of this model.

get_global_variables()

Get all global variables from the diffusion model.

Returns:

Type	Description
`list[Parameter]`	A list of all global variables from the diffusion model.

get_independent_variables(Q_index=None)

Get the independent variables from the diffusion model. If Q_index is provided, only the independent variables for the specified Q value will be returned. If Q_index is None, independent variables for all Q values will be returned.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value for which to get the independent variables. If None, independent variables for all Q values will be included.	`None`

Returns:

Type	Description
`list[Parameter]`	List of independent variables in the model.

get_all_variables(Q_index=None)

Get a list of all variables (Parameters and Descriptors) in the model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value for which to get the variables. If None, variables for all Q values will be included.	`None`

Returns:

Type	Description
`list[DescriptorNumber]`	List of all variables in the model.

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_parameters(Q_index=None)

Get all Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get parameters from. If None, all parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

get_fittable_parameters(Q_index=None)

Get all fittable Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fittable parameters from. If None, all fittable parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fittable Parameters from the diffusion model.

get_free_parameters(Q_index=None)

Get all free Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get free parameters from. If None, all free parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all free Parameters from the diffusion model.

get_fit_parameters(Q_index=None)

Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fit parameters from. If None, all fit parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fit Parameters from the diffusion model.

clear_Q(confirm=False)

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

convert_x_unit(unit)

Convert the x-axis unit of the diffusion model.

Converts the scale parameter (unit x_unit * y_unit), any subclass-specific x-unit parameters, and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. Only energy units are supported (the unit must be convertible to meV).

Unit validation raises UnitError when the unit is not convertible to meV. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

convert_y_unit(unit)

Convert the y-axis unit of the diffusion model.

Converts the scale parameter from x_unit * old_y_unit to x_unit * new_y_unit and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. The new y-unit must be dimensionally compatible with the current one; the scale conversion raises UnitError otherwise. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

get_component_collections(Q_index=None)

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the desired ComponentCollection. If None, all ComponentCollections are returned.	`None`

Returns:

Type	Description
`ComponentCollection \| list[ComponentCollection]`	The ComponentCollection at the specified Q index. If Q_index is None, a list of all ComponentCollections is returned.

Functions:

`diffusion_model_base`

Classes:

Name	Description
`DiffusionModelBase`	Base class for constructing diffusion models.

Classes

DiffusionModelBase(scale=1.0, Q=None, x_unit='meV', y_unit='dimensionless', name='DiffusionModel', display_name='DiffusionModel', lorentzian_name=None, lorentzian_display_name=None, unique_name=None)

Base class for constructing diffusion models.

Unit validation raises UnitError if x_unit is not a string or scipp Unit, or if it cannot be converted to meV.

Parameters:

Name	Type	Description	Default
`scale`	`Numeric`	Scale factor for the diffusion model. Must be a non-negative number. Its unit equals area_unit = x_unit * y_unit because scale * QISF/EISF (dimensionless) = component area.	`1.0`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis (energy/frequency). Must be convertible to meV.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity). Together with x_unit determines area_unit.	`'dimensionless'`
`name`	`str`	Name of the diffusion model.	`'DiffusionModel'`
`display_name`	`str \| None`	Display name of the diffusion model.	`'DiffusionModel'`
`lorentzian_name`	`str \| None`	Name of the Lorentzian component. If None, it will be set to the name of the diffusion model.	`None`
`lorentzian_display_name`	`str \| None`	Display name of the Lorentzian component. If None, it will be set to the lorentzian_name.	`None`
`unique_name`	`str \| None`	Unique name of the diffusion model. If None, a unique name will be generated. By default, None.	`None`

Raises:

Type	Description
`TypeError`	If scale is not a number.
`ValueError`	If scale is negative.

Methods:

Name	Description
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of the diffusion model.
`convert_y_unit`	Convert the y-axis unit of the diffusion model.
`get_fit_targets`	Get the fittable predictions of the diffusion model as FitTargets.
`get_global_variables`	Get all global variables from the diffusion model.
`get_independent_variables`	Get the independent variables from the diffusion model. If Q_index is provided, only the
`get_all_variables`	Get all variables from the diffusion model.
`get_all_parameters`	Get all Parameters from the diffusion model.
`get_fittable_parameters`	Get all fittable Parameters from the diffusion model.
`get_free_parameters`	Get all free Parameters from the diffusion model.
`get_fit_parameters`	Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.
`create_component_collections`	Create the ComponentCollections for the diffusion model based on the current Q values.
`get_component_collections`	Get the ComponentCollection at the given Q index.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.

Attributes:

Name	Type	Description
`scale`	`Parameter`	Get the scale parameter of the diffusion model.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.
`lorentzian_name`	`str`	Get the name of the Lorentzian component.
`lorentzian_display_name`	`str \| None`	Get the display name of the Lorentzian component.
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.

Attributes

scale property writable

Get the scale parameter of the diffusion model.

Returns:

Type	Description
`Parameter`	Scale parameter of the diffusion model.

Q property writable

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

lorentzian_name property writable

Get the name of the Lorentzian component.

Returns:

Type	Description
`str`	Name of the Lorentzian component.

lorentzian_display_name property writable

Get the display name of the Lorentzian component.

Returns:

Type	Description
`str \| None`	Display name of the Lorentzian component, or None if not set.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

Methods:

clear_Q(confirm=False)

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

convert_x_unit(unit)

Convert the x-axis unit of the diffusion model.

Converts the scale parameter (unit x_unit * y_unit), any subclass-specific x-unit parameters, and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. Only energy units are supported (the unit must be convertible to meV).

Unit validation raises UnitError when the unit is not convertible to meV. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

convert_y_unit(unit)

Convert the y-axis unit of the diffusion model.

Converts the scale parameter from x_unit * old_y_unit to x_unit * new_y_unit and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. The new y-unit must be dimensionally compatible with the current one; the scale conversion raises UnitError otherwise. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

get_fit_targets()

Get the fittable predictions of the diffusion model as FitTargets.

The base implementation declares 'area' (scale * QISF(Q)) and 'width' (the HWHM Gamma(Q)), with default dataset keys derived from the Lorentzian component's name. Subclasses with additional predictions (e.g. a delta-function weight) extend this list. The targets are snapshots: units and default keys reflect the model state at call time.

Returns:

Type	Description
`list[FitTarget]`	The fittable predictions of this model.

get_global_variables()

Get all global variables from the diffusion model.

Returns:

Type	Description
`list[Parameter]`	A list of all global variables from the diffusion model.

get_independent_variables(Q_index=None)

Get the independent variables from the diffusion model. If Q_index is provided, only the independent variables for the specified Q value will be returned. If Q_index is None, independent variables for all Q values will be returned. These are variables that are not global but also not part of the component collections.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value for which to get the independent variables. If None, independent variables for all Q values will be included.	`None`

Returns:

Type	Description
`list[Parameter]`	List of independent variables in the model.

get_all_variables(Q_index=None)

Get all variables from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get variables from. If None, all variables from all ComponentCollections are returned, in addition to the global variables.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

get_all_parameters(Q_index=None)

Get all Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get parameters from. If None, all parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

get_fittable_parameters(Q_index=None)

Get all fittable Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fittable parameters from. If None, all fittable parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fittable Parameters from the diffusion model.

get_free_parameters(Q_index=None)

Get all free Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get free parameters from. If None, all free parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all free Parameters from the diffusion model.

get_fit_parameters(Q_index=None)

Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fit parameters from. If None, all fit parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fit Parameters from the diffusion model.

create_component_collections()

Create the ComponentCollections for the diffusion model based on the current Q values.

Returns:

Type	Description
`list[ComponentCollection]`	A list of ComponentCollections corresponding to the current Q values.

get_component_collections(Q_index=None)

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the desired ComponentCollection. If None, all ComponentCollections are returned.	`None`

Returns:

Type	Description
`ComponentCollection \| list[ComponentCollection]`	The ComponentCollection at the specified Q index. If Q_index is None, a list of all ComponentCollections is returned.

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

Functions:

`jump_translational_diffusion`

Classes:

Name	Description
`JumpTranslationalDiffusion`	Model of Jump translational diffusion.

Classes

JumpTranslationalDiffusion(scale=1.0, diffusion_coefficient=1.0, relaxation_time=1.0, Q=None, x_unit='meV', y_unit='dimensionless', name='JumpTranslationalDiffusion', display_name='JumpTranslationalDiffusion', lorentzian_name=None, lorentzian_display_name=None, unique_name=None)

Model of Jump translational diffusion.

The model consists of a Lorentzian function for each Q-value, where the width is given by

\[ \Gamma(Q) = \frac{Q^2}{1+D t Q^2}. \]

where $D$ is the diffusion coefficient and $t$ is the relaxation time. Q is assumed to have units of 1/angstrom. Creates ComponentCollections with Lorentzian components for given Q-values.

Examples:

Creating a JumpTranslationalDiffusion model

Pass the diffusion coefficient (in m²/s) and relaxation time (in ps) along with Q values:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
diffusion_model = sm.JumpTranslationalDiffusion(
    scale=1.0,
    diffusion_coefficient=2.4e-9,
    relaxation_time=1.0,
    Q=Q,
)
component_collections = diffusion_model.create_component_collections()

See also the tutorials.

Parameters:

Name	Type	Description	Default
`scale`	`Numeric`	Scale factor for the diffusion model. Must be a non-negative number.	`1.0`
`diffusion_coefficient`	`Numeric`	Diffusion coefficient D in m^2/s.	`1.0`
`relaxation_time`	`Numeric`	Relaxation time t in ps.	`1.0`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis (energy/frequency). Must be convertible to meV.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity). Determines scale.unit = x_unit * y_unit.	`'dimensionless'`
`name`	`str`	Name of the diffusion model.	`'JumpTranslationalDiffusion'`
`display_name`	`str \| None`	Display name of the diffusion model.	`'JumpTranslationalDiffusion'`
`lorentzian_name`	`str \| None`	Name of the Lorentzian component. If None, it will be set to the name of the diffusion model with '_Lorentzian' appended. By default, None.	`None`
`lorentzian_display_name`	`str \| None`	Display name of the Lorentzian component. If None, it will be set to the display name of the diffusion model with '_Lorentzian' appended. By default, None	`None`
`unique_name`	`str \| None`	Unique name of the diffusion model. If None, a unique name will be generated. By default, None.	`None`

Raises:

Type	Description
`TypeError`	If scale, diffusion_coefficient, or relaxation_time are not numbers.
`ValueError`	If scale, diffusion_coefficient, or relaxation_time are negative.

Methods:

Name	Description
`calculate_width`	Calculate the half-width at half-maximum (HWHM) for the diffusion model. $\Gamma(Q) =
`calculate_EISF`	Calculate the Elastic Incoherent Structure Factor (EISF).
`calculate_QISF`	Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).
`create_component_collections`	Create ComponentCollection components for the diffusion model at given Q values.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`get_all_variables`	Get all variables from the diffusion model.
`get_all_parameters`	Get all Parameters from the diffusion model.
`get_fittable_parameters`	Get all fittable Parameters from the diffusion model.
`get_free_parameters`	Get all free Parameters from the diffusion model.
`get_fit_parameters`	Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of the diffusion model.
`convert_y_unit`	Convert the y-axis unit of the diffusion model.
`get_fit_targets`	Get the fittable predictions of the diffusion model as FitTargets.
`get_global_variables`	Get all global variables from the diffusion model.
`get_independent_variables`	Get the independent variables from the diffusion model. If Q_index is provided, only the
`get_component_collections`	Get the ComponentCollection at the given Q index.

Attributes:

Name	Type	Description
`diffusion_coefficient`	`Parameter`	Get the diffusion coefficient parameter D.
`relaxation_time`	`Parameter`	Get the relaxation time parameter t.
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`scale`	`Parameter`	Get the scale parameter of the diffusion model.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.
`lorentzian_name`	`str`	Get the name of the Lorentzian component.
`lorentzian_display_name`	`str \| None`	Get the display name of the Lorentzian component.

Attributes

diffusion_coefficient property writable

Get the diffusion coefficient parameter D.

Returns:

Type	Description
`Parameter`	Diffusion coefficient D.

relaxation_time property writable

Get the relaxation time parameter t.

Returns:

Type	Description
`Parameter`	Relaxation time t in ps.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

scale property writable

Get the scale parameter of the diffusion model.

Returns:

Type	Description
`Parameter`	Scale parameter of the diffusion model.

Q property writable

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

lorentzian_name property writable

Get the name of the Lorentzian component.

Returns:

Type	Description
`str`	Name of the Lorentzian component.

lorentzian_display_name property writable

Get the display name of the Lorentzian component.

Returns:

Type	Description
`str \| None`	Display name of the Lorentzian component, or None if not set.

Methods:

calculate_width(Q=None)

Calculate the half-width at half-maximum (HWHM) for the diffusion model. $\Gamma(Q) = Q^2/(1+D t Q^2)$, where $D$ is the diffusion coefficient and $t$ is the relaxation time.

Parameters:

Name	Type	Description	Default
`Q`	`Q_type \| None`	Scattering vector in 1/angstrom. Can be a single value or an array of values. If None, Q values stored in the model are used.	`None`

Returns:

Type	Description
`np.ndarray`	HWHM values in the unit of the model (e.g., meV).

calculate_EISF(Q)

Calculate the Elastic Incoherent Structure Factor (EISF).

Parameters:

Name	Type	Description	Default
`Q`	`Q_type`	Scattering vector in 1/angstrom. Can be a single value or an array of values.	required

Returns:

Type	Description
`np.ndarray`	EISF values (dimensionless).

calculate_QISF(Q)

Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

Parameters:

Name	Type	Description	Default
`Q`	`Q_type`	Scattering vector in 1/angstrom. Can be a single value or an array of values.	required

Returns:

Type	Description
`np.ndarray`	QISF values (dimensionless).

create_component_collections()

Create ComponentCollection components for the diffusion model at given Q values.

Returns:

Type	Description
`list[ComponentCollection]`	List of ComponentCollections with Jump Diffusion Lorentzian components.

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables(Q_index=None)

Get all variables from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get variables from. If None, all variables from all ComponentCollections are returned, in addition to the global variables.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

get_all_parameters(Q_index=None)

Get all Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get parameters from. If None, all parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters from the diffusion model.

get_fittable_parameters(Q_index=None)

Get all fittable Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fittable parameters from. If None, all fittable parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fittable Parameters from the diffusion model.

get_free_parameters(Q_index=None)

Get all free Parameters from the diffusion model.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get free parameters from. If None, all free parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all free Parameters from the diffusion model.

get_fit_parameters(Q_index=None)

Get all fit Parameters from the diffusion model. This is an alias for get_free_parameters.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the ComponentCollection to get fit parameters from. If None, all fit parameters from all ComponentCollections are returned.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all fit Parameters from the diffusion model.

clear_Q(confirm=False)

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

convert_x_unit(unit)

Convert the x-axis unit of the diffusion model.

Converts the scale parameter (unit x_unit * y_unit), any subclass-specific x-unit parameters, and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. Only energy units are supported (the unit must be convertible to meV).

Unit validation raises UnitError when the unit is not convertible to meV. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

convert_y_unit(unit)

Convert the y-axis unit of the diffusion model.

Converts the scale parameter from x_unit * old_y_unit to x_unit * new_y_unit and the existing component collections in place — parameter values and object identity are preserved, and nothing is scheduled for regeneration. The new y-unit must be dimensionally compatible with the current one; the scale conversion raises UnitError otherwise. If any conversion fails, the already-converted state is rolled back best-effort before the failing conversion's exception is re-raised.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit.	required

Raises:

Type	Description
`TypeError`	If unit is not a string or sc.Unit.

get_fit_targets()

Get the fittable predictions of the diffusion model as FitTargets.

The base implementation declares 'area' (scale * QISF(Q)) and 'width' (the HWHM Gamma(Q)), with default dataset keys derived from the Lorentzian component's name. Subclasses with additional predictions (e.g. a delta-function weight) extend this list. The targets are snapshots: units and default keys reflect the model state at call time.

Returns:

Type	Description
`list[FitTarget]`	The fittable predictions of this model.

get_global_variables()

Get all global variables from the diffusion model.

Returns:

Type	Description
`list[Parameter]`	A list of all global variables from the diffusion model.

get_independent_variables(Q_index=None)

Get the independent variables from the diffusion model. If Q_index is provided, only the independent variables for the specified Q value will be returned. If Q_index is None, independent variables for all Q values will be returned. These are variables that are not global but also not part of the component collections.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value for which to get the independent variables. If None, independent variables for all Q values will be included.	`None`

Returns:

Type	Description
`list[Parameter]`	List of independent variables in the model.

get_component_collections(Q_index=None)

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the desired ComponentCollection. If None, all ComponentCollections are returned.	`None`

Returns:

Type	Description
`ComponentCollection \| list[ComponentCollection]`	The ComponentCollection at the specified Q index. If Q_index is None, a list of all ComponentCollections is returned.

`instrument_model`

Classes:

Name	Description
`InstrumentModel`	InstrumentModel represents a model of the instrument in an experiment at various Q.

Classes

`InstrumentModel(display_name='MyInstrumentModel', unique_name=None, Q=None, resolution_model=None, background_model=None, energy_offset=None, x_unit='meV')`

InstrumentModel represents a model of the instrument in an experiment at various Q.

It can contain a model of the resolution function for convolutions, of the background and an offset in the energy axis.

Examples:

Creating an InstrumentModel with resolution and background

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
resolution_model = sm.ResolutionModel(components=sm.Gaussian(width=0.05))
background_model = sm.BackgroundModel(components=sm.Polynomial(coefficients=[0.001]))

instrument_model = sm.InstrumentModel(
    Q=Q,
    resolution_model=resolution_model,
    background_model=background_model,
)

Fixing resolution parameters after calibration

After fitting a vanadium run, fix the resolution parameters before fitting the sample:

instrument_model.fix_resolution_parameters()
instrument_model.get_all_variables(Q_index=0)

Parameters:

Name	Type	Description	Default
`display_name`	`str`	The display name of the InstrumentModel.	`'MyInstrumentModel'`
`unique_name`	`str \| None`	The unique name of the InstrumentModel.	`None`
`Q`	`Q_type \| None`	The Q values where the instrument is modelled.	`None`
`resolution_model`	`ResolutionModel \| SampleModel \| None`	The resolution model of the instrument. If a SampleModel it will be converted to a ResolutionModel. If None, an empty resolution model is created and no resolution convolution is carried out.	`None`
`background_model`	`BackgroundModel \| None`	The background model of the instrument. If None, an empty background model is created, and the background evaluates to 0.	`None`
`energy_offset`	`Numeric \| None`	Template energy offset of the instrument. Will be copied to each Q value. If None, the energy offset will be 0.	`None`
`x_unit`	`str \| sc.Unit`	The unit of the energy axis.	`'meV'`

Raises:

Type	Description
`TypeError`	If resolution_model is not a ResolutionModel or None, or if background_model is not a BackgroundModel or None, or if energy_offset is not a number or None.

Methods:

Name	Description
`clear_Q`	Clear the Q values of the InstrumentModel and any associated ResolutionModel and
`convert_x_unit`	Convert the unit of the InstrumentModel.
`get_all_variables`	Get all variables in the InstrumentModel.
`fix_resolution_parameters`	Fix all parameters in the resolution model.
`free_resolution_parameters`	Free all parameters in the resolution model.
`normalize_resolution`	Normalize the resolution model to have area 1.
`get_energy_offset`	Get the energy offset Parameter at a specific Q index.
`fix_energy_offset`	Fix energy offset parameters.
`free_energy_offset`	Free energy offset parameters.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object from a full encoded dictionary.
`__copy__`	Return a copy of the object.

Attributes:

Name	Type	Description
`resolution_model`	`ResolutionModel`	Get the resolution model of the instrument.
`background_model`	`BackgroundModel`	Get the background model of the instrument.
`Q`	`sc.Variable \| None`	Get the Q values of the InstrumentModel.
`x_unit`	`str \| sc.Unit \| None`	Get the x-axis unit of the InstrumentModel.
`energy_offset`	`Parameter`	Get the template energy offset of the instrument.
`unique_name`	`str`	Get the unique name of the object.
`display_name`	`str`	Get a pretty display name.

Attributes

resolution_model property writable

Get the resolution model of the instrument.

Returns:

Type	Description
`ResolutionModel`	The resolution model of the instrument.

background_model property writable

Get the background model of the instrument.

Returns:

Type	Description
`BackgroundModel`	The background model of the instrument.

Q property writable

Get the Q values of the InstrumentModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the InstrumentModel in 1/angstrom, or None if not set.

x_unit property writable

Get the x-axis unit of the InstrumentModel.

Returns:

Type	Description
`str \| sc.Unit \| None`	The x-axis unit of the InstrumentModel.

energy_offset property writable

Get the template energy offset of the instrument.

Returns:

Type	Description
`Parameter`	The energy offset Parameter. Each Q value gets its own copy via get_energy_offset().

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

Methods:

clear_Q(confirm=False)

Clear the Q values of the InstrumentModel and any associated ResolutionModel and BackgroundModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

convert_x_unit(x_unit)

Convert the unit of the InstrumentModel.

Parameters:

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

Raises:

Type	Description
`ValueError`	If x_unit is not a valid unit string or scipp Unit.

get_all_variables(Q_index=None)

Get all variables in the InstrumentModel.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value to get variables for. If None, get variables for all Q values.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all variables in the InstrumentModel. If Q_index is specified, only variables from the ComponentCollection at the given Q index are included. Otherwise, all variables in the InstrumentModel are included.

fix_resolution_parameters()

Fix all parameters in the resolution model.

free_resolution_parameters()

Free all parameters in the resolution model.

normalize_resolution()

Normalize the resolution model to have area 1.

get_energy_offset(Q_index=None)

Get the energy offset Parameter at a specific Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value to get the energy offset for. If None, get the energy offset for all Q values.	`None`

Raises:

Type	Description
`ValueError`	If no Q values are set in the InstrumentModel.

Returns:

Type	Description
`Parameter \| list[Parameter]`	The energy offset Parameter at the specified Q index, or a list of Parameters if Q_index is None.

fix_energy_offset(Q_index=None)

Fix energy offset parameters.

If Q_index is specified, only fix the energy offset for that Q value. If Q_index is None, fix energy offsets for all Q values.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value to fix the energy offset for. If None, fix energy offsets for all Q values.	`None`

free_energy_offset(Q_index=None)

Free energy offset parameters.

If Q_index is specified, only free the energy offset for that Q value. If Q_index is None, free energy offsets for all Q values.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	The index of the Q value to free the energy offset for. If None, free energy offsets for all Q values.	`None`

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	Encoded object containing all information to reform an EasyScience object.

from_dict(obj_dict) classmethod

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

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`NewBase`	Reformed EasyScience object.

Raises:

Type	Description
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

Functions:

`model_base`

Classes:

Name	Description
`ModelBase`	Base class for Sample Models.

Classes

`ModelBase(display_name='MyModelBase', unique_name=None, x_unit='meV', y_unit='dimensionless', components=None, Q=None)`

Base class for Sample Models.

Contains common functionality for models with components and Q dependence.

Parameters:

Name	Type	Description	Default
`display_name`	`str`	Display name of the model.	`'MyModelBase'`
`unique_name`	`str \| None`	Unique name of the model. If None, a unique name will be generated.	`None`
`x_unit`	`str \| sc.Unit \| None`	Unit of the x-axis (energy, Q, etc.).	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the model output (intensity).	`'dimensionless'`
`components`	`ModelComponent \| ComponentCollection \| None`	Template components of the model. If None, no components are added. These components are copied into ComponentCollections for each Q value.	`None`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`

Raises:

Type	Description
`TypeError`	If components is not a ModelComponent or ComponentCollection.

Methods:

Name	Description
`evaluate`	Evaluate the sample model at all Q for the given x values.
`append_component`	Append a ModelComponent or ComponentCollection to the SampleModel.
`remove_component`	Remove a ModelComponent from the SampleModel by its name.
`clear_components`	Clear all ModelComponents from the SampleModel.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of all components in the model.
`convert_y_unit`	Convert the y-axis unit of all components in the model.
`fix_all_parameters`	Fix all Parameters in all ComponentCollections.
`free_all_parameters`	Free all Parameters in all ComponentCollections.
`get_all_variables`	Get all Parameters and Descriptors from all ComponentCollections in the ModelBase.
`get_component_collection`	Get the ComponentCollection at the given Q index.
`normalize_area`	Normalize the area of the model across all Q values.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`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
`components`	`list[ModelComponent]`	Get the components of the SampleModel.
`component_collections_is_dirty`	`bool`	Return whether component collections need to be rebuilt before use.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.

Attributes

components property writable

Get the components of the SampleModel.

Returns:

Type	Description
`list[ModelComponent]`	The components of the SampleModel.

component_collections_is_dirty property

Return whether component collections need to be rebuilt before use.

Returns:

Type	Description
`bool`	`True` if component collections have not been built yet or are stale.

Q property writable

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

Methods:

evaluate(x, output='numpy')

Evaluate the sample model at all Q for the given x values.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Energy axis values to evaluate the model at.	required
`output`	`str`	'numpy' returns np.ndarray per Q; 'scipp' returns sc.Variable per Q.	`'numpy'`

Raises:

Type	Description
`ValueError`	If there are no components in the model to evaluate.

Returns:

Type	Description
`list[np.ndarray] \| list[sc.Variable]`	A list of arrays containing the evaluated model values for each Q. The length of the list will match the number of Q values in the model.

append_component(component)

Append a ModelComponent or ComponentCollection to the SampleModel.

Parameters:

Name	Type	Description	Default
`component`	`ModelComponent \| ComponentCollection`	The ModelComponent or ComponentCollection to append.	required

remove_component(name)

Remove a ModelComponent from the SampleModel by its name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the ModelComponent to remove.	required

clear_components()

Clear all ModelComponents from the SampleModel.

clear_Q(confirm=False)

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

convert_x_unit(unit)

Convert the x-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit to convert to.	required

convert_y_unit(unit)

Convert the y-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit to convert to.	required

fix_all_parameters()

Fix all Parameters in all ComponentCollections.

free_all_parameters()

Free all Parameters in all ComponentCollections.

get_all_variables(Q_index=None)

Get all Parameters and Descriptors from all ComponentCollections in the ModelBase.

Ignores the Parameters and Descriptors in self._components as these are just templates.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	If None, get variables for all ComponentCollections. If int, get variables for the ComponentCollection at this index.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters and Descriptors from the ComponentCollections in the ModelBase.

get_component_collection(Q_index)

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int`	The index of the desired ComponentCollection.	required

Returns:

Type	Description
`ComponentCollection`	The ComponentCollection at the given Q index.

normalize_area()

Normalize the area of the model across all Q values.

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

Functions:

`resolution_model`

Classes:

Name	Description
`ResolutionModel`	ResolutionModel represents a model of the instrument resolution in an experiment at various Q.

Classes

`ResolutionModel(display_name='MyResolutionModel', unique_name=None, x_unit='meV', y_unit='dimensionless', components=None, Q=None)`

ResolutionModel represents a model of the instrument resolution in an experiment at various Q.

Examples:

Creating a Gaussian resolution model

A single Gaussian is the most common resolution model. Note that DeltaFunction, Polynomial, and Exponential components are not allowed in a ResolutionModel:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
resolution_model = sm.ResolutionModel(
    components=sm.Gaussian(width=0.05, area=1.0),
    Q=Q,
)
energy = np.linspace(-2, 2, 100)
resolution = resolution_model.evaluate(energy)

Building a resolution model from a fitted SampleModel

After fitting vanadium data with a SampleModel, use from_sample_model to convert it directly into a ResolutionModel:

resolution_model = sm.ResolutionModel.from_sample_model(fitted_sample_model)

Parameters:

Name	Type	Description	Default
`display_name`	`str`	Display name of the model.	`'MyResolutionModel'`
`unique_name`	`str \| None`	Unique name of the model. If None, a unique name will be generated.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`components`	`ModelComponent \| ComponentCollection \| None`	Template components. DeltaFunction, Polynomial, and Exponential are not allowed.	`None`
`Q`	`Q_type \| None`	Q values for the model. If None, Q is not set.	`None`

Methods:

Name	Description
`append_component`	Append a component to the ResolutionModel.
`from_sample_model`	Create a ResolutionModel from a SampleModel.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`get_all_variables`	Get all Parameters and Descriptors from all ComponentCollections in the ModelBase.
`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`.
`evaluate`	Evaluate the sample model at all Q for the given x values.
`remove_component`	Remove a ModelComponent from the SampleModel by its name.
`clear_components`	Clear all ModelComponents from the SampleModel.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of all components in the model.
`convert_y_unit`	Convert the y-axis unit of all components in the model.
`fix_all_parameters`	Fix all Parameters in all ComponentCollections.
`free_all_parameters`	Free all Parameters in all ComponentCollections.
`get_component_collection`	Get the ComponentCollection at the given Q index.
`normalize_area`	Normalize the area of the model across all Q values.

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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`components`	`list[ModelComponent]`	Get the components of the SampleModel.
`component_collections_is_dirty`	`bool`	Return whether component collections need to be rebuilt before use.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

components property writable

Get the components of the SampleModel.

Returns:

Type	Description
`list[ModelComponent]`	The components of the SampleModel.

component_collections_is_dirty property

Return whether component collections need to be rebuilt before use.

Returns:

Type	Description
`bool`	`True` if component collections have not been built yet or are stale.

Q property writable

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

Methods:

append_component(component)

Append a component to the ResolutionModel.

Does not allow DeltaFunction, Polynomial, or Exponential components, as these are not physical resolution components.

Parameters:

Name	Type	Description	Default
`component`	`ModelComponent \| ComponentCollection`	Component(s) to append.	required

Raises:

Type	Description
`TypeError`	If the component is a DeltaFunction, Polynomial, or Exponential.

from_sample_model(sample_model, normalize_area=True, fix_parameters=True) classmethod

Create a ResolutionModel from a SampleModel.

Parameters:

Name	Type	Description	Default
`sample_model`	`SampleModel`	SampleModel to create the ResolutionModel from.	required
`normalize_area`	`bool`	Whether to normalize the components in the ResolutionModel to have area 1.	`True`
`fix_parameters`	`bool`	Whether to fix the parameters in the ResolutionModel.	`True`

Returns:

Type	Description
`ResolutionModel`	ResolutionModel created from the SampleModel.

Raises:

Type	Description
`TypeError`	If sample_model is not a SampleModel, or if normalize_area or fix_parameters are not bool.

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_variables(Q_index=None)

Get all Parameters and Descriptors from all ComponentCollections in the ModelBase.

Ignores the Parameters and Descriptors in self._components as these are just templates.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	If None, get variables for all ComponentCollections. If int, get variables for the ComponentCollection at this index.	`None`

Returns:

Type	Description
`list[Parameter]`	A list of all Parameters and Descriptors from the ComponentCollections in the ModelBase.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

evaluate(x, output='numpy')

Evaluate the sample model at all Q for the given x values.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	Energy axis values to evaluate the model at.	required
`output`	`str`	'numpy' returns np.ndarray per Q; 'scipp' returns sc.Variable per Q.	`'numpy'`

Raises:

Type	Description
`ValueError`	If there are no components in the model to evaluate.

Returns:

Type	Description
`list[np.ndarray] \| list[sc.Variable]`	A list of arrays containing the evaluated model values for each Q. The length of the list will match the number of Q values in the model.

remove_component(name)

Remove a ModelComponent from the SampleModel by its name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the ModelComponent to remove.	required

clear_components()

Clear all ModelComponents from the SampleModel.

clear_Q(confirm=False)

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

convert_x_unit(unit)

Convert the x-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit to convert to.	required

convert_y_unit(unit)

Convert the y-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit to convert to.	required

fix_all_parameters()

Fix all Parameters in all ComponentCollections.

free_all_parameters()

Free all Parameters in all ComponentCollections.

get_component_collection(Q_index)

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int`	The index of the desired ComponentCollection.	required

Returns:

Type	Description
`ComponentCollection`	The ComponentCollection at the given Q index.

normalize_area()

Normalize the area of the model across all Q values.

`sample_model`

Classes:

Name	Description
`SampleModel`	SampleModel represents a model of a sample with components and diffusion models, parameterized

Classes

`SampleModel(display_name='MySampleModel', unique_name=None, x_unit='meV', y_unit='dimensionless', components=None, Q=None, diffusion_models=None, temperature=None, temperature_unit='K', detailed_balance_settings=None)`

SampleModel represents a model of a sample with components and diffusion models, parameterized by Q and optionally temperature. Generates ComponentCollections for each Q value, combining components from the base model and diffusion models.

Applies detailed balancing based on temperature if provided.

Examples:

Creating a SampleModel with a static component

A single component is copied to each Q value automatically:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
energy = np.linspace(-2, 2, 100)

sample_model = sm.SampleModel(
    components=[
        sm.DeltaFunction(display_name='Elastic', area=0.5),
        sm.Lorentzian(display_name='QE', area=0.5, width=0.3),
    ],
    Q=Q,
)
intensity = sample_model.evaluate(energy)

Adding a diffusion model and enabling detailed balance

Pass temperature to apply the detailed balance factor automatically:

import numpy as np
import easydynamics.sample_model as sm

Q = np.linspace(0.5, 2, 7)
btd = sm.BrownianTranslationalDiffusion(diffusion_coefficient=2.4e-9, scale=0.5)
sample_model = sm.SampleModel(diffusion_models=btd, Q=Q, temperature=10)
intensity = sample_model.evaluate(np.linspace(-2, 2, 100))

Parameters:

Name	Type	Description	Default
`display_name`	`str`	Display name of the model.	`'MySampleModel'`
`unique_name`	`str \| None`	Unique name of the model. If None, a unique name will be generated.	`None`
`x_unit`	`str \| sc.Unit`	Unit of the x-axis.	`'meV'`
`y_unit`	`str \| sc.Unit`	Unit of the y-axis (output).	`'dimensionless'`
`components`	`ModelComponent \| ComponentCollection \| None`	Template components copied into each Q's ComponentCollection.	`None`
`Q`	`Q_type \| None`	Q values. If None, Q is not set.	`None`
`diffusion_models`	`DiffusionModelBase \| list[DiffusionModelBase] \| None`	Diffusion models to include. Each must be a DiffusionModelBase.	`None`
`temperature`	`float \| None`	Sample temperature in temperature_unit. If provided, detailed balance is applied.	`None`
`temperature_unit`	`str \| sc.Unit`	Unit for the temperature parameter.	`'K'`
`detailed_balance_settings`	`DetailedBalanceSettings \| None`	Detailed balance settings. If None, default settings are used.	`None`

Raises:

Type	Description
`TypeError`	If diffusion_models contains non-DiffusionModelBase items, temperature is not numeric, or detailed_balance_settings is not a DetailedBalanceSettings instance.
`ValueError`	If temperature is negative.

Methods:

Name	Description
`append_diffusion_model`	Append a DiffusionModel to the SampleModel.
`remove_diffusion_model`	Remove a DiffusionModel from the SampleModel by name.
`clear_diffusion_models`	Clear all DiffusionModels from the SampleModel.
`convert_temperature_unit`	Convert the unit of the temperature Parameter.
`evaluate`	Evaluate the sample model at all Q for the given x values.
`get_all_variables`	Get all Parameters and Descriptors from all ComponentCollections in the SampleModel.
`to_dict`	Convert an EasyScience object into a full dictionary using
`from_dict`	Re-create an EasyScience object with DescriptorNumber attributes
`__copy__`	Return a copy of the object.
`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`.
`append_component`	Append a ModelComponent or ComponentCollection to the SampleModel.
`remove_component`	Remove a ModelComponent from the SampleModel by its name.
`clear_components`	Clear all ModelComponents from the SampleModel.
`clear_Q`	Clear the Q values of the SampleModel, removing all component collections and their
`convert_x_unit`	Convert the x-axis unit of all components in the model.
`convert_y_unit`	Convert the y-axis unit of all components in the model.
`fix_all_parameters`	Fix all Parameters in all ComponentCollections.
`free_all_parameters`	Free all Parameters in all ComponentCollections.
`get_component_collection`	Get the ComponentCollection at the given Q index.
`normalize_area`	Normalize the area of the model across all Q values.

Attributes:

Name	Type	Description
`diffusion_models`	`list[DiffusionModelBase]`	Get the diffusion models of the SampleModel.
`temperature`	`Parameter \| None`	Get the temperature of the SampleModel.
`temperature_unit`	`str \| sc.Unit`	Get the temperature unit.
`normalize_detailed_balance`	`bool`	Get whether to divide the detailed balance factor by temperature.
`use_detailed_balance`	`bool`	Get whether detailed balance correction is applied.
`detailed_balance_settings`	`DetailedBalanceSettings`	Get the detailed balance settings.
`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.
`x_unit`	`str \| sc.Unit \| None`	Get the unit of the x-axis.
`y_unit`	`str \| sc.Unit \| None`	Get the unit of the model output.
`components`	`list[ModelComponent]`	Get the components of the SampleModel.
`component_collections_is_dirty`	`bool`	Return whether component collections need to be rebuilt before use.
`Q`	`sc.Variable \| None`	Get the Q values of the SampleModel.

Attributes

diffusion_models property writable

Get the diffusion models of the SampleModel.

Returns:

Type	Description
`list[DiffusionModelBase]`	The diffusion models of the SampleModel.

temperature property writable

Get the temperature of the SampleModel.

Returns:

Type	Description
`Parameter \| None`	The temperature Parameter of the SampleModel, or None if not set.

temperature_unit property writable

Get the temperature unit.

Returns:

Type	Description
`str \| sc.Unit`	The unit of the temperature parameter.

normalize_detailed_balance property writable

Get whether to divide the detailed balance factor by temperature.

Returns:

Type	Description
`bool`	True if the detailed balance factor is divided by temperature, False otherwise.

use_detailed_balance property writable

Get whether detailed balance correction is applied.

Returns:

Type	Description
`bool`	True if detailed balance is applied during evaluation, False otherwise

detailed_balance_settings property writable

Get the detailed balance settings.

Returns:

Type	Description
`DetailedBalanceSettings`	The detailed balance settings object.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
`str`	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
`str`	The name of the model.

x_unit property writable

Get the unit of the x-axis.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the x-axis.

y_unit property writable

Get the unit of the model output.

Returns:

Type	Description
`str \| sc.Unit \| None`	The unit of the y-axis.

components property writable

Get the components of the SampleModel.

Returns:

Type	Description
`list[ModelComponent]`	The components of the SampleModel.

component_collections_is_dirty property

Return whether component collections need to be rebuilt before use.

Returns:

Type	Description
`bool`	`True` if component collections have not been built yet or are stale.

Q property writable

Get the Q values of the SampleModel.

Returns:

Type	Description
`sc.Variable \| None`	The Q values of the SampleModel in 1/angstrom, or None if not set.

Methods:

append_diffusion_model(diffusion_model)

Append a DiffusionModel to the SampleModel.

Parameters:

Name	Type	Description	Default
`diffusion_model`	`DiffusionModelBase`	The DiffusionModel to append.	required

Raises:

Type	Description
`TypeError`	If the diffusion_model is not a DiffusionModelBase.

remove_diffusion_model(name)

Remove a DiffusionModel from the SampleModel by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the DiffusionModel to remove.	required

Raises:

Type	Description
`ValueError`	If no DiffusionModel with the given name is found.

clear_diffusion_models()

Clear all DiffusionModels from the SampleModel.

convert_temperature_unit(unit)

Convert the unit of the temperature Parameter.

Parameters:

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

Raises:

Type	Description
`ValueError`	If temperature is not set or conversion fails.
`Exception`	If the provided unit is invalid or cannot be converted.

evaluate(x, output='numpy')

Evaluate the sample model at all Q for the given x values.

Parameters:

Name	Type	Description	Default
`x`	`Numeric \| list \| np.ndarray \| sc.Variable \| sc.DataArray`	The x values to evaluate the model at.	required
`output`	`str`	'numpy' returns list of np.ndarray; 'scipp' returns list of sc.Variable.	`'numpy'`

Returns:

Type	Description
`list[np.ndarray] \| list[sc.Variable]`	List of evaluated model values for each Q.

get_all_variables(Q_index=None)

Get all Parameters and Descriptors from all ComponentCollections in the SampleModel.

Also includes temperature if set and all variables from diffusion models. Ignores the Parameters and Descriptors in self._components as these are just templates.

Parameters:

Name	Type	Description	Default
`Q_index`	`int \| None`	If specified, only get variables from the ComponentCollection at the given Q index. If None, get variables from all ComponentCollections.	`None`

Returns:

Type	Description
`list[Parameter]`	All Parameters and Descriptors in the SampleModel.

to_dict(skip=None)

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

Parameters:

Name	Type	Description	Default
`skip`	`Optional[List[str]]`	List of field names as strings to skip when forming the dictionary. By default, None.	`None`

Returns:

Type	Description
`Dict[str, Any]`	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.

Parameters:

Name	Type	Description	Default
`obj_dict`	`Dict[str, Any]`	Dictionary containing the serialized contents (from `SerializerDict`) of an EasyScience object.	required

Returns:

Type	Description
`ModelBase`	Reformed EasyScience object.

Raises:

Type	Description
`SyntaxError`	If a deserialized parameter cannot be attached back to the class definition.
`ValueError`	If the input dictionary does not describe the expected class.

__copy__()

Return a copy of the object.

get_all_parameters()

Get all Parameter objects as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_fittable_parameters()

Get all parameters which can be fitted as a list.

Returns:

Type	Description
`List[Parameter]`	List of `Parameter` objects.

get_free_parameters()

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

Returns:

Type	Description
`List[Parameter]`	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.

append_component(component)

Append a ModelComponent or ComponentCollection to the SampleModel.

Parameters:

Name	Type	Description	Default
`component`	`ModelComponent \| ComponentCollection`	The ModelComponent or ComponentCollection to append.	required

remove_component(name)

Remove a ModelComponent from the SampleModel by its name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the ModelComponent to remove.	required

clear_components()

Clear all ModelComponents from the SampleModel.

clear_Q(confirm=False)

Clear the Q values of the SampleModel, removing all component collections and their associated Parameters.

Parameters:

Name	Type	Description	Default
`confirm`	`bool`	Confirmation to clear Q values.	`False`

Raises:

Type	Description
`ValueError`	If confirm is not True.

convert_x_unit(unit)

Convert the x-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new x-axis unit to convert to.	required

convert_y_unit(unit)

Convert the y-axis unit of all components in the model.

Parameters:

Name	Type	Description	Default
`unit`	`str \| sc.Unit`	The new y-axis unit to convert to.	required

fix_all_parameters()

Fix all Parameters in all ComponentCollections.

free_all_parameters()

Free all Parameters in all ComponentCollections.

get_component_collection(Q_index)

Get the ComponentCollection at the given Q index.

Parameters:

Name	Type	Description	Default
`Q_index`	`int`	The index of the desired ComponentCollection.	required

Returns:

Type	Description
`ComponentCollection`	The ComponentCollection at the given Q index.

normalize_area()

Normalize the area of the model across all Q values.

sample_model

Classes

BackgroundModel(display_name='MyBackgroundModel', unique_name=None, x_unit='meV', y_unit='dimensionless', components=None, Q=None)

Attributes

unique_name property writable

display_name property writable

name property writable

x_unit property writable

y_unit property writable

components property writable

component_collections_is_dirty property

Q property writable

Methods:

to_dict(skip=None)

from_dict(obj_dict) classmethod

__copy__()

get_all_variables(Q_index=None)

get_all_parameters()

get_fittable_parameters()

get_free_parameters()

get_fit_parameters()

evaluate(x, output='numpy')

append_component(component)

remove_component(name)

clear_components()

clear_Q(confirm=False)

convert_x_unit(unit)

convert_y_unit(unit)

fix_all_parameters()

free_all_parameters()

get_component_collection(Q_index)

normalize_area()

ComponentCollection(components=None, x_unit='meV', y_unit='dimensionless', name='ComponentCollection', display_name=None, unique_name=None)

Attributes

unique_name property writable

display_name property writable

name property writable

x_unit property writable

y_unit property writable

is_empty property writable

Methods:

get_all_parameters()

get_fittable_parameters()

get_free_parameters()

get_fit_parameters()

__getitem__(idx)

__setitem__(idx, value)

__delitem__(idx)

__len__()

insert(index, value)

sort(key=None, reverse=False)

pop(index=-1)

append(value)

get_names()

get_duplicate_names()

convert_x_unit(new_x_unit)

convert_y_unit(new_y_unit)

append_component(component)

list_component_names()

get_fit_targets()

normalize_area()

get_all_variables()

evaluate(x, output='numpy')

evaluate_component(x, name, output='numpy')

fix_all_parameters()

free_all_parameters()

to_dict()

from_dict(obj_dict) classmethod

__copy__()

DampedHarmonicOscillator(area=1.0, center=1.0, width=1.0, x_unit='meV', y_unit='dimensionless', name='DampedHarmonicOscillator', display_name=None, unique_name=None)

Attributes

unique_name property writable

display_name property writable

name property writable

x_unit property writable

y_unit property writable

area property writable

center property writable

width property writable

Methods:

`sample_model`

`BackgroundModel(display_name='MyBackgroundModel', unique_name=None, x_unit='meV', y_unit='dimensionless', components=None, Q=None)`

`unique_name` `property` `writable`

`display_name` `property` `writable`

`name` `property` `writable`

`x_unit` `property` `writable`

`y_unit` `property` `writable`

`components` `property` `writable`

`component_collections_is_dirty` `property`

`Q` `property` `writable`

`to_dict(skip=None)`

`from_dict(obj_dict)` `classmethod`

`copy()`

`get_all_variables(Q_index=None)`

`get_all_parameters()`

`get_fittable_parameters()`

`get_free_parameters()`

`get_fit_parameters()`

`evaluate(x, output='numpy')`

`append_component(component)`

`remove_component(name)`

`clear_components()`

`clear_Q(confirm=False)`

`convert_x_unit(unit)`

`convert_y_unit(unit)`

`fix_all_parameters()`

`free_all_parameters()`

`get_component_collection(Q_index)`

`normalize_area()`

`ComponentCollection(components=None, x_unit='meV', y_unit='dimensionless', name='ComponentCollection', display_name=None, unique_name=None)`

`unique_name` `property` `writable`

`display_name` `property` `writable`

`name` `property` `writable`

`x_unit` `property` `writable`

`y_unit` `property` `writable`

`is_empty` `property` `writable`

`get_all_parameters()`

`get_fittable_parameters()`

`get_free_parameters()`

`get_fit_parameters()`

`getitem(idx)`

`setitem(idx, value)`

`delitem(idx)`

`len()`

`insert(index, value)`

`sort(key=None, reverse=False)`

`pop(index=-1)`

`append(value)`

`get_names()`

`get_duplicate_names()`

`convert_x_unit(new_x_unit)`

`convert_y_unit(new_y_unit)`

`append_component(component)`

`list_component_names()`

`get_fit_targets()`

`normalize_area()`

`get_all_variables()`

`evaluate(x, output='numpy')`

`evaluate_component(x, name, output='numpy')`

`fix_all_parameters()`

`free_all_parameters()`

`to_dict()`

`from_dict(obj_dict)` `classmethod`

`copy()`

`DampedHarmonicOscillator(area=1.0, center=1.0, width=1.0, x_unit='meV', y_unit='dimensionless', name='DampedHarmonicOscillator', display_name=None, unique_name=None)`

`unique_name` `property` `writable`

`display_name` `property` `writable`

`name` `property` `writable`

`x_unit` `property` `writable`

`y_unit` `property` `writable`

`area` `property` `writable`

`center` `property` `writable`

`width` `property` `writable`

`to_dict(skip=None)`

`from_dict(obj_dict)` `classmethod`

`copy()`

`get_all_variables()`

`get_all_parameters()`

`get_fittable_parameters()`

`get_free_parameters()`