sample_model

BackgroundModel

Bases: ModelBase

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

Source code in src/easydynamics/sample_model/background_model.py

class BackgroundModel(ModelBase):
    """
    BackgroundModel represents a model of the background in an experiment at various Q.
    """

    def __init__(
        self,
        display_name: str | None = 'MyBackgroundModel',
        unique_name: str | None = None,
        unit: str | sc.Unit = 'meV',
        components: ModelComponent | ComponentCollection | None = None,
        Q: Q_type | None = None,
    ) -> None:
        """
        Initialize the BackgroundModel.

        Parameters
        ----------
        display_name : str | None, default='MyBackgroundModel'
            Display name of the model.
        unique_name : str | None, default=None
            Unique name of the model. If None, a unique name will be generated.
        unit : str | sc.Unit, default='meV'
            Unit of the model.
        components : ModelComponent | ComponentCollection | None, default=None
            Template components of the model. If None, no components are added. These components
            are copied into ComponentCollections for each Q value.
        Q : Q_type | None, default=None
            Q values for the model. If None, Q is not set.
        """
        super().__init__(
            display_name=display_name,
            unique_name=unique_name,
            unit=unit,
            components=components,
            Q=Q,
        )

__init__(display_name='MyBackgroundModel', unique_name=None, unit='meV', components=None, Q=None)

Initialize the BackgroundModel.

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
unit	str | sc.Unit	Unit of the model.	'meV'
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

Source code in src/easydynamics/sample_model/background_model.py

def __init__(
    self,
    display_name: str | None = 'MyBackgroundModel',
    unique_name: str | None = None,
    unit: str | sc.Unit = 'meV',
    components: ModelComponent | ComponentCollection | None = None,
    Q: Q_type | None = None,
) -> None:
    """
    Initialize the BackgroundModel.

    Parameters
    ----------
    display_name : str | None, default='MyBackgroundModel'
        Display name of the model.
    unique_name : str | None, default=None
        Unique name of the model. If None, a unique name will be generated.
    unit : str | sc.Unit, default='meV'
        Unit of the model.
    components : ModelComponent | ComponentCollection | None, default=None
        Template components of the model. If None, no components are added. These components
        are copied into ComponentCollections for each Q value.
    Q : Q_type | None, default=None
        Q values for the model. If None, Q is not set.
    """
    super().__init__(
        display_name=display_name,
        unique_name=unique_name,
        unit=unit,
        components=components,
        Q=Q,
    )

ComponentCollection

Bases: EasyDynamicsList, EasyDynamicsModelBase

Collection of model components.

Examples:

Create a ComponentCollection with two components:

>>> 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])

Append a component to the collection:

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

Evaluate the collection at a given energy axis:

>>> import numpy as np
>>> x = np.linspace(-5, 5, 100)
>>> values = collection.evaluate(x)

Remove a component by name:

>>> collection.remove('Gaussian1')

List component names:

>>> collection.list_component_names()
['Lorentzian1', 'Gaussian2']

Source code in src/easydynamics/sample_model/component_collection.py

class ComponentCollection(EasyDynamicsList, EasyDynamicsModelBase):
    """
    Collection of model components.

    Examples
    --------
    Create a ComponentCollection with two components:
    >>> 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])

    Append a component to the collection:
    >>> component3 = sm.Gaussian(name='Gaussian2', area=0.5, width=0.8)
    >>> collection.append(component3)

    Evaluate the collection at a given energy axis:
    >>> import numpy as np
    >>> x = np.linspace(-5, 5, 100)
    >>> values = collection.evaluate(x)

    Remove a component by name:
    >>> collection.remove('Gaussian1')

    List component names:
    >>> collection.list_component_names()
    ['Lorentzian1', 'Gaussian2']
    """

    def __init__(
        self,
        components: ModelComponent | list[ModelComponent] | None = None,
        unit: str | sc.Unit = 'meV',
        name: str = 'ComponentCollection',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize a new ComponentCollection.

        Parameters
        ----------
        components : ModelComponent | list[ModelComponent] | None, default=None
            Initial model components to add to the ComponentCollection.
        unit : str | sc.Unit, default='meV'
            Unit of the collection.
        name : str, default='ComponentCollection'
            Name of the collection.
        display_name : str | None, default=None
            Display name of the collection.
        unique_name : str | None, default=None
            Unique name of the collection.

        Raises
        ------
        TypeError
            If unit is not a string or sc.Unit, or if components is not a list of ModelComponent.
        """
        if components is None:
            components = []
        if isinstance(components, ModelComponent):
            components = [components]
        elif not isinstance(components, list):
            raise TypeError(
                f'components must be a ModelComponent or a list of ModelComponent, got {type(components).__name__} instead.'  # noqa: E501
            )
        for comp in components:
            if not isinstance(comp, ModelComponent):
                raise TypeError(
                    f'All items in components must be instances of ModelComponent, got {type(comp).__name__} instead.'  # noqa: E501
                )

        EasyDynamicsList.__init__(
            self,
            *components,
            protected_types=ModelComponent,
        )

        EasyDynamicsModelBase.__init__(
            self,
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

    # ------------------------------------------------------------------
    # Properties
    # ------------------------------------------------------------------

    @property
    def is_empty(self) -> bool:
        """
        Check if the ComponentCollection has no components.

        Returns
        -------
        bool
            True if the collection has no components, False otherwise.
        """
        return not self

    @is_empty.setter
    def is_empty(self, _value: bool) -> None:
        """
        Is_empty is a read-only property that indicates whether the collection has components.

        Parameters
        ----------
        _value : bool
            The value to set (ignored).

        Raises
        ------
        AttributeError
            Always raised since is_empty is read-only.
        """
        raise AttributeError(
            'is_empty is a read-only property that indicates '
            'whether the collection has components.'
        )

    def convert_unit(self, unit: str | sc.Unit) -> None:
        """
        Convert the unit of the ComponentCollection and all its components.

        Parameters
        ----------
        unit : str | sc.Unit
            The target unit to convert to.

        Raises
        ------
        TypeError
            If unit is not a string or sc.Unit.
        Exception
            If any component cannot be converted to the specified unit.
        """

        if not isinstance(unit, (str, sc.Unit)):
            raise TypeError(f'Unit must be a string or sc.Unit, got {type(unit).__name__}')

        old_unit = self._unit

        try:
            for component in self:
                component.convert_unit(unit)
            self._unit = unit
        except Exception as e:
            # Attempt to rollback on failure
            try:
                for component in self:
                    component.convert_unit(old_unit)
            except Exception:  # noqa: S110
                pass  # Best effort rollback
            raise e

    # ------------------------------------------------------------------
    # Component management
    # ------------------------------------------------------------------

    def append_component(self, component: ModelComponent | ComponentCollection) -> None:
        """
        Append a model component or the components from another ComponentCollection to this
        ComponentCollection.

        Parameters
        ----------
        component : ModelComponent | ComponentCollection
            The component to append. If a ComponentCollection is provided, all of its components
            will be appended.
        """
        if isinstance(component, ComponentCollection):
            self.extend(component)
        else:
            self.append(component)

    def list_component_names(self) -> list[str]:
        """
        List the names of all components in the model.

        Returns
        -------
        list[str]
            List of names of the components in the collection.
        """

        return [component.name for component in self]

    def normalize_area(self) -> None:
        """
        Normalize the areas of all components so they sum to 1.

        This is useful for convolutions.

        Raises
        ------
        ValueError
            If there are no components in the model or if the total area is zero or not finite,
            which would prevent normalization.
        """
        if not self:
            raise ValueError('No components in the model to normalize.')

        area_params = []
        total_area = Parameter(name='total_area', value=0.0, unit=self._unit)

        for component in self:
            if hasattr(component, 'area'):
                area_params.append(component.area)
                total_area += component.area
            else:
                warnings.warn(
                    f"Component '{component.name}' does not have an 'area' attribute "
                    f'and will be skipped in normalization.',
                    UserWarning,
                    stacklevel=2,
                )

        if total_area.value == 0:
            raise ValueError('Total area is zero; cannot normalize.')

        if not np.isfinite(total_area.value):
            raise ValueError('Total area is not finite; cannot normalize.')

        for param in area_params:
            param.value /= total_area.value

    # ------------------------------------------------------------------
    # Other methods
    # ------------------------------------------------------------------

    def get_all_variables(self) -> list[DescriptorBase]:
        """
        Get all parameters from the model component.

        Returns
        -------
        list[DescriptorBase]
            List of parameters in the component.
        """

        return [var for component in self for var in component.get_all_variables()]

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        """
        Evaluate the sum of all components.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            Energy axis.

        Returns
        -------
        np.ndarray
            Evaluated model values.
        """

        if not self:
            return np.zeros_like(x)
        return sum(component.evaluate(x) for component in self)

    def evaluate_component(
        self,
        x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
        name: str,
    ) -> np.ndarray:
        """
        Evaluate a single component by name.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            Energy axis.
        name : str
            Component name.

        Raises
        ------
        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
        -------
        np.ndarray
            Evaluated values for the specified component.
        """
        if not self:
            raise ValueError('No components in the model to evaluate.')

        if not isinstance(name, str):
            raise TypeError(f'Component name must be a string, got {type(name)} instead.')

        matches = [comp for comp in self if comp.name == name]
        if not matches:
            raise KeyError(f"No component named '{name}' exists.")

        component = matches[0]

        return component.evaluate(x)

    def fix_all_parameters(self) -> None:
        """Fix all free parameters in the model."""
        for param in self.get_fittable_parameters():
            param.fixed = True

    def free_all_parameters(self) -> None:
        """Free all fixed parameters in the model."""
        for param in self.get_fittable_parameters():
            param.fixed = False

    # ------------------------------------------------------------------
    # Dunder methods
    # ------------------------------------------------------------------

    def __contains__(self, item: str | ModelComponent) -> bool:
        """
        Check if a component with the given name or instance exists in the ComponentCollection.

        Parameters
        ----------
        item : str | ModelComponent
            The component name or instance to check for.

        Returns
        -------
        bool
            True if the component exists, False otherwise.
        """

        if isinstance(item, str):
            # Check by component name
            return any(comp.name == item for comp in self)
        if isinstance(item, ModelComponent):
            # Check by component instance
            return any(comp is item for comp in self)
        return False

    def __repr__(self) -> str:
        """
        Return a string representation of the ComponentCollection.

        Returns
        -------
        str
            String representation of the ComponentCollection.
        """
        comp_names = ', '.join(c.name for c in self) or 'No components'

        return f"<ComponentCollection name='{self.name}' | Components: {comp_names}>"

    def to_dict(self) -> dict:
        return {
            '@module': self.__class__.__module__,
            '@class': self.__class__.__name__,
            'unit': str(self.unit),
            'name': self.name,
            'display_name': self.display_name,
            'components': [c.to_dict() for c in self._data],
        }

    @classmethod
    def from_dict(cls, obj_dict: dict) -> ComponentCollection:

        def deserialise_component(d: dict) -> ModelComponent:
            """
            Deserialise a component from its dictionary representation.
            Parameters
            ----------
            d : dict
                The dictionary representation of the component.
            Returns
            -------
            ModelComponent
                The deserialised component.
            """
            module = importlib.import_module(d['@module'])
            cls = getattr(module, d['@class'])
            return cls.from_dict(d)

        components = [deserialise_component(c) for c in obj_dict.get('components', [])]

        return cls(
            components=components,
            unit=obj_dict.get('unit', 'meV'),
            name=obj_dict.get('name', 'ComponentCollection'),
            display_name=obj_dict.get('display_name'),
        )

    def __copy__(self) -> ComponentCollection:
        """
        Create a deep copy of the ComponentCollection.

        Returns
        -------
        ComponentCollection
            A deep copy of the ComponentCollection.
        """

        return self.from_dict(self.to_dict())

is_empty property writable

Check if the ComponentCollection has no components.

Returns:

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

__init__(components=None, unit='meV', name='ComponentCollection', display_name=None, unique_name=None)

Initialize a new ComponentCollection.

Parameters:

Name	Type	Description	Default
components	ModelComponent | list[ModelComponent] | None	Initial model components to add to the ComponentCollection.	None
unit	str | sc.Unit	Unit of the collection.	'meV'
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 unit is not a string or sc.Unit, or if components is not a list of ModelComponent.

Source code in src/easydynamics/sample_model/component_collection.py

def __init__(
    self,
    components: ModelComponent | list[ModelComponent] | None = None,
    unit: str | sc.Unit = 'meV',
    name: str = 'ComponentCollection',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize a new ComponentCollection.

    Parameters
    ----------
    components : ModelComponent | list[ModelComponent] | None, default=None
        Initial model components to add to the ComponentCollection.
    unit : str | sc.Unit, default='meV'
        Unit of the collection.
    name : str, default='ComponentCollection'
        Name of the collection.
    display_name : str | None, default=None
        Display name of the collection.
    unique_name : str | None, default=None
        Unique name of the collection.

    Raises
    ------
    TypeError
        If unit is not a string or sc.Unit, or if components is not a list of ModelComponent.
    """
    if components is None:
        components = []
    if isinstance(components, ModelComponent):
        components = [components]
    elif not isinstance(components, list):
        raise TypeError(
            f'components must be a ModelComponent or a list of ModelComponent, got {type(components).__name__} instead.'  # noqa: E501
        )
    for comp in components:
        if not isinstance(comp, ModelComponent):
            raise TypeError(
                f'All items in components must be instances of ModelComponent, got {type(comp).__name__} instead.'  # noqa: E501
            )

    EasyDynamicsList.__init__(
        self,
        *components,
        protected_types=ModelComponent,
    )

    EasyDynamicsModelBase.__init__(
        self,
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

convert_unit(unit)

Convert the unit of the ComponentCollection and all its components.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The target unit to convert to.	required

Raises:

Type	Description
TypeError	If unit is not a string or sc.Unit.
Exception	If any component cannot be converted to the specified unit.

Source code in src/easydynamics/sample_model/component_collection.py

def convert_unit(self, unit: str | sc.Unit) -> None:
    """
    Convert the unit of the ComponentCollection and all its components.

    Parameters
    ----------
    unit : str | sc.Unit
        The target unit to convert to.

    Raises
    ------
    TypeError
        If unit is not a string or sc.Unit.
    Exception
        If any component cannot be converted to the specified unit.
    """

    if not isinstance(unit, (str, sc.Unit)):
        raise TypeError(f'Unit must be a string or sc.Unit, got {type(unit).__name__}')

    old_unit = self._unit

    try:
        for component in self:
            component.convert_unit(unit)
        self._unit = unit
    except Exception as e:
        # Attempt to rollback on failure
        try:
            for component in self:
                component.convert_unit(old_unit)
        except Exception:  # noqa: S110
            pass  # Best effort rollback
        raise e

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

Source code in src/easydynamics/sample_model/component_collection.py

def append_component(self, component: ModelComponent | ComponentCollection) -> None:
    """
    Append a model component or the components from another ComponentCollection to this
    ComponentCollection.

    Parameters
    ----------
    component : ModelComponent | ComponentCollection
        The component to append. If a ComponentCollection is provided, all of its components
        will be appended.
    """
    if isinstance(component, ComponentCollection):
        self.extend(component)
    else:
        self.append(component)

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.

Source code in src/easydynamics/sample_model/component_collection.py

def list_component_names(self) -> list[str]:
    """
    List the names of all components in the model.

    Returns
    -------
    list[str]
        List of names of the components in the collection.
    """

    return [component.name for component in self]

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.

Source code in src/easydynamics/sample_model/component_collection.py

def normalize_area(self) -> None:
    """
    Normalize the areas of all components so they sum to 1.

    This is useful for convolutions.

    Raises
    ------
    ValueError
        If there are no components in the model or if the total area is zero or not finite,
        which would prevent normalization.
    """
    if not self:
        raise ValueError('No components in the model to normalize.')

    area_params = []
    total_area = Parameter(name='total_area', value=0.0, unit=self._unit)

    for component in self:
        if hasattr(component, 'area'):
            area_params.append(component.area)
            total_area += component.area
        else:
            warnings.warn(
                f"Component '{component.name}' does not have an 'area' attribute "
                f'and will be skipped in normalization.',
                UserWarning,
                stacklevel=2,
            )

    if total_area.value == 0:
        raise ValueError('Total area is zero; cannot normalize.')

    if not np.isfinite(total_area.value):
        raise ValueError('Total area is not finite; cannot normalize.')

    for param in area_params:
        param.value /= total_area.value

get_all_variables()

Get all parameters from the model component.

Returns:

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

Source code in src/easydynamics/sample_model/component_collection.py

def get_all_variables(self) -> list[DescriptorBase]:
    """
    Get all parameters from the model component.

    Returns
    -------
    list[DescriptorBase]
        List of parameters in the component.
    """

    return [var for component in self for var in component.get_all_variables()]

evaluate(x)

Evaluate the sum of all components.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	Energy axis.	required

Returns:

Type	Description
np.ndarray	Evaluated model values.

Source code in src/easydynamics/sample_model/component_collection.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    """
    Evaluate the sum of all components.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        Energy axis.

    Returns
    -------
    np.ndarray
        Evaluated model values.
    """

    if not self:
        return np.zeros_like(x)
    return sum(component.evaluate(x) for component in self)

evaluate_component(x, name)

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

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	Evaluated values for the specified component.

Source code in src/easydynamics/sample_model/component_collection.py

def evaluate_component(
    self,
    x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
    name: str,
) -> np.ndarray:
    """
    Evaluate a single component by name.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        Energy axis.
    name : str
        Component name.

    Raises
    ------
    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
    -------
    np.ndarray
        Evaluated values for the specified component.
    """
    if not self:
        raise ValueError('No components in the model to evaluate.')

    if not isinstance(name, str):
        raise TypeError(f'Component name must be a string, got {type(name)} instead.')

    matches = [comp for comp in self if comp.name == name]
    if not matches:
        raise KeyError(f"No component named '{name}' exists.")

    component = matches[0]

    return component.evaluate(x)

fix_all_parameters()

Fix all free parameters in the model.

Source code in src/easydynamics/sample_model/component_collection.py

def fix_all_parameters(self) -> None:
    """Fix all free parameters in the model."""
    for param in self.get_fittable_parameters():
        param.fixed = True

free_all_parameters()

Free all fixed parameters in the model.

Source code in src/easydynamics/sample_model/component_collection.py

def free_all_parameters(self) -> None:
    """Free all fixed parameters in the model."""
    for param in self.get_fittable_parameters():
        param.fixed = False

__contains__(item)

Check if a component with the given name or instance exists in the ComponentCollection.

Parameters:

Name	Type	Description	Default
item	str | ModelComponent	The component name or instance to check for.	required

Returns:

Type	Description
bool	True if the component exists, False otherwise.

Source code in src/easydynamics/sample_model/component_collection.py

def __contains__(self, item: str | ModelComponent) -> bool:
    """
    Check if a component with the given name or instance exists in the ComponentCollection.

    Parameters
    ----------
    item : str | ModelComponent
        The component name or instance to check for.

    Returns
    -------
    bool
        True if the component exists, False otherwise.
    """

    if isinstance(item, str):
        # Check by component name
        return any(comp.name == item for comp in self)
    if isinstance(item, ModelComponent):
        # Check by component instance
        return any(comp is item for comp in self)
    return False

__repr__()

Return a string representation of the ComponentCollection.

Returns:

Type	Description
str	String representation of the ComponentCollection.

Source code in src/easydynamics/sample_model/component_collection.py

def __repr__(self) -> str:
    """
    Return a string representation of the ComponentCollection.

    Returns
    -------
    str
        String representation of the ComponentCollection.
    """
    comp_names = ', '.join(c.name for c in self) or 'No components'

    return f"<ComponentCollection name='{self.name}' | Components: {comp_names}>"

__copy__()

Create a deep copy of the ComponentCollection.

Returns:

Type	Description
ComponentCollection	A deep copy of the ComponentCollection.

Source code in src/easydynamics/sample_model/component_collection.py

def __copy__(self) -> ComponentCollection:
    """
    Create a deep copy of the ComponentCollection.

    Returns
    -------
    ComponentCollection
        A deep copy of the ComponentCollection.
    """

    return self.from_dict(self.to_dict())

DampedHarmonicOscillator

Bases: CreateParametersMixin, ModelComponent

Model of a Damped Harmonic Oscillator (DHO).

The intensity is given by $$ 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, \(x_0\) is the center, and \(\gamma\) is the width.

Source code in src/easydynamics/sample_model/components/damped_harmonic_oscillator.py

class DampedHarmonicOscillator(CreateParametersMixin, ModelComponent):
    r"""
    Model of a Damped Harmonic Oscillator (DHO).

    The intensity is given by $$ 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, $x_0$ is the center, and $\gamma$ is the width.
    """

    def __init__(
        self,
        area: Numeric | Parameter = 1.0,
        center: Numeric | Parameter = 1.0,
        width: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'DampedHarmonicOscillator',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Damped Harmonic Oscillator.

        Parameters
        ----------
        area : Numeric | Parameter, default=1.0
            Area under the curve.
        center : Numeric | Parameter, default=1.0
            Resonance frequency, approximately the peak position.
        width : Numeric | Parameter, default=1.0
            Damping constant, approximately the half width at half max (HWHM) of the peaks. By
            default, 1.0.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='DampedHarmonicOscillator'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.
        """

        super().__init__(
            name=name,
            display_name=display_name,
            unique_name=unique_name,
            unit=unit,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center,
            name=name,
            fix_if_none=False,
            unit=self._unit,
            enforce_minimum_center=True,
        )

        width = self._create_width_parameter(width=width, name=name, unit=self._unit)

        self._area = area
        self._center = center
        self._width = width

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """
        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """
        return self._center

    @center.setter
    def center(self, value: Numeric) -> None:
        """
        Set the value of the center parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the center parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')

        if float(value) <= 0:
            raise ValueError('center must be positive')
        self._center.value = value

    @property
    def width(self) -> Parameter:
        """
        Get the width parameter.

        Returns
        -------
        Parameter
            The width parameter.
        """
        return self._width

    @width.setter
    def width(self, value: Numeric) -> None:
        """
        Set the value of the width parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the width parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('width must be a number')

        if float(value) <= 0:
            raise ValueError('width must be positive')

        self._width.value = value

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        r"""
        Evaluate the Damped Harmonic Oscillator at the given x values.

        If x is a scipp Variable, the unit of the DHO will be converted to match x. The intensity
        is given by $$ 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, $x_0$ is the center, and $\gamma$ is the width.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the DHO.

        Returns
        -------
        np.ndarray
            The intensity of the DHO at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        normalization = 2 * self.center.value**2 * self.width.value / np.pi
        # No division by zero here, width>0 enforced in setter
        denominator = (x**2 - self.center.value**2) ** 2 + (2 * self.width.value * x) ** 2

        return self.area.value * normalization / (denominator)

    def __repr__(self) -> str:
        """
        Return a string representation of the Damped Harmonic Oscillator.

        Returns
        -------
        str
            A string representation of the Damped Harmonic Oscillator.
        """
        return (
            f'DampedHarmonicOscillator(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n '
            f'    area = {self.area},\n '
            f'    center = {self.center},\n '
            f'    width = {self.width})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

width property writable

Get the width parameter.

Returns:

Type	Description
Parameter	The width parameter.

__init__(area=1.0, center=1.0, width=1.0, unit='meV', name='DampedHarmonicOscillator', display_name=None, unique_name=None)

Initialize the Damped Harmonic Oscillator.

Parameters:

Name	Type	Description	Default
area	Numeric | Parameter	Area under the curve.	1.0
center	Numeric | Parameter	Resonance frequency, approximately the peak position.	1.0
width	Numeric | Parameter	Damping constant, approximately the half width at half max (HWHM) of the peaks. By default, 1.0.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'DampedHarmonicOscillator'
display_name	str | None	Display name of the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/damped_harmonic_oscillator.py

def __init__(
    self,
    area: Numeric | Parameter = 1.0,
    center: Numeric | Parameter = 1.0,
    width: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'DampedHarmonicOscillator',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Damped Harmonic Oscillator.

    Parameters
    ----------
    area : Numeric | Parameter, default=1.0
        Area under the curve.
    center : Numeric | Parameter, default=1.0
        Resonance frequency, approximately the peak position.
    width : Numeric | Parameter, default=1.0
        Damping constant, approximately the half width at half max (HWHM) of the peaks. By
        default, 1.0.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='DampedHarmonicOscillator'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.
    """

    super().__init__(
        name=name,
        display_name=display_name,
        unique_name=unique_name,
        unit=unit,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center,
        name=name,
        fix_if_none=False,
        unit=self._unit,
        enforce_minimum_center=True,
    )

    width = self._create_width_parameter(width=width, name=name, unit=self._unit)

    self._area = area
    self._center = center
    self._width = width

evaluate(x)

Evaluate the Damped Harmonic Oscillator at the given x values.

If x is a scipp Variable, the unit of the DHO will be converted to match x. The intensity is given by $$ 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, \(x_0\) is the center, and \(\gamma\) is the width.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the DHO.	required

Returns:

Type	Description
np.ndarray	The intensity of the DHO at the given x values.

Source code in src/easydynamics/sample_model/components/damped_harmonic_oscillator.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    r"""
    Evaluate the Damped Harmonic Oscillator at the given x values.

    If x is a scipp Variable, the unit of the DHO will be converted to match x. The intensity
    is given by $$ 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, $x_0$ is the center, and $\gamma$ is the width.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the DHO.

    Returns
    -------
    np.ndarray
        The intensity of the DHO at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    normalization = 2 * self.center.value**2 * self.width.value / np.pi
    # No division by zero here, width>0 enforced in setter
    denominator = (x**2 - self.center.value**2) ** 2 + (2 * self.width.value * x) ** 2

    return self.area.value * normalization / (denominator)

__repr__()

Return a string representation of the Damped Harmonic Oscillator.

Returns:

Type	Description
str	A string representation of the Damped Harmonic Oscillator.

Source code in src/easydynamics/sample_model/components/damped_harmonic_oscillator.py

def __repr__(self) -> str:
    """
    Return a string representation of the Damped Harmonic Oscillator.

    Returns
    -------
    str
        A string representation of the Damped Harmonic Oscillator.
    """
    return (
        f'DampedHarmonicOscillator(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n '
        f'    area = {self.area},\n '
        f'    center = {self.center},\n '
        f'    width = {self.width})'
    )

DeltaFunction

Bases: CreateParametersMixin, ModelComponent

Delta function.

Evaluates to zero everywhere, except in convolutions, where it acts as an identity. This is handled by the Convolution method. If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Source code in src/easydynamics/sample_model/components/delta_function.py

class DeltaFunction(CreateParametersMixin, ModelComponent):
    """
    Delta function.

    Evaluates to zero everywhere, except in convolutions, where it acts as an identity. This is
    handled by the Convolution method. If the center is not provided, it will be centered at 0 and
    fixed, which is typically what you want in QENS.
    """

    def __init__(
        self,
        center: Numeric | Parameter | None = None,
        area: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'DeltaFunction',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Delta function.

        Parameters
        ----------
        center : Numeric | Parameter | None, default=None
            Center of the delta function. If None, it will be centered at 0 and fixed.
        area : Numeric | Parameter, default=1.0
            Total area under the curve.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='DeltaFunction'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.
        """
        # Validate inputs and create Parameters if not given
        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )

        self._area = area
        self._center = center

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """

        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """

        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """

        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the center parameter value.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter. If None, defaults to 0 and is fixed.

        Raises
        ------
        TypeError
            If the value is not a number or None.
        """

        if value is None:
            value = 0.0
            self._center.fixed = True
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        """
        Evaluate the Delta function at the given x values.

        The Delta function evaluates to zero everywhere, except at the center. Its numerical
        integral is equal to the area. It acts as an identity in convolutions.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Delta function.

        Returns
        -------
        np.ndarray
            The evaluated Delta function at the given x values.
        """

        # x assumed sorted, 1D numpy array
        x = self._prepare_x_for_evaluate(x)
        model = np.zeros_like(x, dtype=float)
        center = self.center.value
        area = self.area.value

        if x.min() - EPSILON <= center <= x.max() + EPSILON:
            # nearest index
            i = np.argmin(np.abs(x - center))

            # left half-width
            if i == 0:  # noqa: SIM108
                left = x[1] - x[0] if x.size > 1 else 0.5
            else:
                left = x[i] - x[i - 1]

            # right half-width
            if i == x.size - 1:  # noqa: SIM108
                right = x[-1] - x[-2] if x.size > 1 else 0.5
            else:
                right = x[i + 1] - x[i]

            # effective bin width: half left + half right
            bin_width = 0.5 * (left + right)

            model[i] = area / bin_width

        return model

    def __repr__(self) -> str:
        """
        Return a string representation of the Delta function.

        Returns
        -------
        str
            A string representation of the Delta function.
        """

        return (
            f'DeltaFunction(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self.unit},\n'
            f'    area = {self.area},\n'
            f'    center = {self.center})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

__init__(center=None, area=1.0, unit='meV', name='DeltaFunction', display_name=None, unique_name=None)

Initialize the Delta function.

Parameters:

Name	Type	Description	Default
center	Numeric | Parameter | None	Center of the delta function. If None, it will be centered at 0 and fixed.	None
area	Numeric | Parameter	Total area under the curve.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'DeltaFunction'
display_name	str | None	Display name of the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/delta_function.py

def __init__(
    self,
    center: Numeric | Parameter | None = None,
    area: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'DeltaFunction',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Delta function.

    Parameters
    ----------
    center : Numeric | Parameter | None, default=None
        Center of the delta function. If None, it will be centered at 0 and fixed.
    area : Numeric | Parameter, default=1.0
        Total area under the curve.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='DeltaFunction'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.
    """
    # Validate inputs and create Parameters if not given
    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )

    self._area = area
    self._center = center

evaluate(x)

Evaluate the Delta function at the given x values.

The Delta function evaluates to zero everywhere, except at the center. Its numerical integral is equal to the area. It acts as an identity in convolutions.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Delta function.	required

Returns:

Type	Description
np.ndarray	The evaluated Delta function at the given x values.

Source code in src/easydynamics/sample_model/components/delta_function.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    """
    Evaluate the Delta function at the given x values.

    The Delta function evaluates to zero everywhere, except at the center. Its numerical
    integral is equal to the area. It acts as an identity in convolutions.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Delta function.

    Returns
    -------
    np.ndarray
        The evaluated Delta function at the given x values.
    """

    # x assumed sorted, 1D numpy array
    x = self._prepare_x_for_evaluate(x)
    model = np.zeros_like(x, dtype=float)
    center = self.center.value
    area = self.area.value

    if x.min() - EPSILON <= center <= x.max() + EPSILON:
        # nearest index
        i = np.argmin(np.abs(x - center))

        # left half-width
        if i == 0:  # noqa: SIM108
            left = x[1] - x[0] if x.size > 1 else 0.5
        else:
            left = x[i] - x[i - 1]

        # right half-width
        if i == x.size - 1:  # noqa: SIM108
            right = x[-1] - x[-2] if x.size > 1 else 0.5
        else:
            right = x[i + 1] - x[i]

        # effective bin width: half left + half right
        bin_width = 0.5 * (left + right)

        model[i] = area / bin_width

    return model

__repr__()

Return a string representation of the Delta function.

Returns:

Type	Description
str	A string representation of the Delta function.

Source code in src/easydynamics/sample_model/components/delta_function.py

def __repr__(self) -> str:
    """
    Return a string representation of the Delta function.

    Returns
    -------
    str
        A string representation of the Delta function.
    """

    return (
        f'DeltaFunction(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self.unit},\n'
        f'    area = {self.area},\n'
        f'    center = {self.center})'
    )

Exponential

Bases: CreateParametersMixin, ModelComponent

Model of an exponential function.

The intensity is given by

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

where \(A\) is the amplitude, \(x_0\) is the center, and \(B\) describes the rate of decay or growth.

Source code in src/easydynamics/sample_model/components/exponential.py

class Exponential(CreateParametersMixin, ModelComponent):
    r"""
    Model of an exponential function.

    The intensity is given by

    $$ I(x) = A e^{B (x-x_0)}, $$

    where $A$ is the amplitude, $x_0$ is the center, and $B$ describes the rate of decay or growth.
    """

    def __init__(
        self,
        amplitude: Numeric | Parameter = 1.0,
        center: Numeric | Parameter | None = None,
        rate: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'Exponential',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Exponential component.

        Parameters
        ----------
        amplitude : Numeric | Parameter, default=1.0
            Amplitude of the Exponential.
        center : Numeric | Parameter | None, default=None
            Center of the Exponential. If None, the center is fixed at 0.
        rate : Numeric | Parameter, default=1.0
            Decay or growth constant of the Exponential.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='Exponential'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.

        Raises
        ------
        TypeError
            If amplitude, center, or rate are not numbers or Parameters.
        ValueError
            If amplitude, center or rate are not finite numbers.
        """
        # Validate inputs and create Parameters if not given
        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        if not isinstance(amplitude, (Parameter, Numeric)):
            raise TypeError('amplitude must be a number or a Parameter.')

        if isinstance(amplitude, Numeric):
            if not np.isfinite(amplitude):
                raise ValueError('amplitude must be a finite number or a Parameter')

            amplitude = Parameter(name=name + ' amplitude', value=float(amplitude), unit=unit)

        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )

        if not isinstance(rate, (Parameter, Numeric)):
            raise TypeError('rate must be a number or a Parameter.')

        if isinstance(rate, Numeric):
            if not np.isfinite(rate):
                raise ValueError('rate must be a finite number or a Parameter')

            rate = Parameter(name=name + ' rate', value=float(rate), unit='1/' + str(unit))

        self._amplitude = amplitude
        self._center = center
        self._rate = rate

    @property
    def amplitude(self) -> Parameter:
        """
        Get the amplitude parameter.

        Returns
        -------
        Parameter
            The amplitude parameter.
        """

        return self._amplitude

    @amplitude.setter
    def amplitude(self, value: Numeric) -> None:
        """
        Set the value of the amplitude parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the amplitude parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """

        if not isinstance(value, Numeric):
            raise TypeError('amplitude must be a number')
        self._amplitude.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """

        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the center parameter value.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """

        if value is None:
            value = 0.0
            self._center.fixed = True

        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    @property
    def rate(self) -> Parameter:
        """
        Get the rate parameter.

        Returns
        -------
        Parameter
            The rate parameter.
        """
        return self._rate

    @rate.setter
    def rate(self, value: Numeric) -> None:
        """
        Set the rate parameter value.

        Parameters
        ----------
        value : Numeric
            The new value for the rate parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError('rate must be a number')

        self._rate.value = value

    def evaluate(
        self,
        x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
    ) -> np.ndarray:
        r"""
        Evaluate the Exponential at the given x values.

        If x is a scipp Variable, the unit of the Exponential will be converted to match x. The
        intensity is given by $$ I(x) = A \exp\left( r (x - x_0) \right) $$

        where $A$ is the amplitude, $x_0$ is the center, and $r$ is the rate.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Exponential.

        Returns
        -------
        np.ndarray
            The intensity of the Exponential at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)
        exponent = self.rate.value * (x - self.center.value)

        return self.amplitude.value * np.exp(exponent)

    def convert_unit(self, unit: str | sc.Unit) -> None:
        """
        Convert the unit of the Parameters in the component.

        Parameters
        ----------
        unit : str | sc.Unit
            The new unit to convert to.

        Raises
        ------
        TypeError
            If unit is not a string or sc.Unit.
        Exception
            If conversion fails for any parameter.
        """

        if not isinstance(unit, (str, sc.Unit)):
            raise TypeError('unit must be a string or sc.Unit')

        old_unit = self._unit
        pars = [self.amplitude, self.center]
        try:
            for p in pars:
                p.convert_unit(unit)
            self.rate.convert_unit('1/' + str(unit))
            self._unit = unit
        except Exception as e:
            # Attempt to rollback on failure
            try:
                for p in pars:
                    p.convert_unit(old_unit)
                self.rate.convert_unit('1/' + str(old_unit))
            except Exception:  # noqa: S110
                pass  # Best effort rollback
            raise e

    def __repr__(self) -> str:
        """
        Return a string representation of the Exponential.

        Returns
        -------
        str
            A string representation of the Exponential.
        """

        return (
            f'Exponential(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n '
            f'    amplitude = {self.amplitude},\n '
            f'    center = {self.center},\n '
            f'    rate = {self.rate})'
        )

amplitude property writable

Get the amplitude parameter.

Returns:

Type	Description
Parameter	The amplitude parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

rate property writable

Get the rate parameter.

Returns:

Type	Description
Parameter	The rate parameter.

__init__(amplitude=1.0, center=None, rate=1.0, unit='meV', name='Exponential', display_name=None, unique_name=None)

Initialize the Exponential component.

Parameters:

Name	Type	Description	Default
amplitude	Numeric | Parameter	Amplitude of the Exponential.	1.0
center	Numeric | Parameter | None	Center of the Exponential. If None, the center is fixed at 0.	None
rate	Numeric | Parameter	Decay or growth constant of the Exponential.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'Exponential'
display_name	str | None	Display name of the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Raises:

Type	Description
TypeError	If amplitude, center, or rate are not numbers or Parameters.
ValueError	If amplitude, center or rate are not finite numbers.

Source code in src/easydynamics/sample_model/components/exponential.py

def __init__(
    self,
    amplitude: Numeric | Parameter = 1.0,
    center: Numeric | Parameter | None = None,
    rate: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'Exponential',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Exponential component.

    Parameters
    ----------
    amplitude : Numeric | Parameter, default=1.0
        Amplitude of the Exponential.
    center : Numeric | Parameter | None, default=None
        Center of the Exponential. If None, the center is fixed at 0.
    rate : Numeric | Parameter, default=1.0
        Decay or growth constant of the Exponential.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='Exponential'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.

    Raises
    ------
    TypeError
        If amplitude, center, or rate are not numbers or Parameters.
    ValueError
        If amplitude, center or rate are not finite numbers.
    """
    # Validate inputs and create Parameters if not given
    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    if not isinstance(amplitude, (Parameter, Numeric)):
        raise TypeError('amplitude must be a number or a Parameter.')

    if isinstance(amplitude, Numeric):
        if not np.isfinite(amplitude):
            raise ValueError('amplitude must be a finite number or a Parameter')

        amplitude = Parameter(name=name + ' amplitude', value=float(amplitude), unit=unit)

    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )

    if not isinstance(rate, (Parameter, Numeric)):
        raise TypeError('rate must be a number or a Parameter.')

    if isinstance(rate, Numeric):
        if not np.isfinite(rate):
            raise ValueError('rate must be a finite number or a Parameter')

        rate = Parameter(name=name + ' rate', value=float(rate), unit='1/' + str(unit))

    self._amplitude = amplitude
    self._center = center
    self._rate = rate

evaluate(x)

Evaluate the Exponential at the given x values.

If x is a scipp Variable, the unit of the Exponential will be converted to match x. The intensity is given by $$ I(x) = A \exp\left( r (x - x_0) \right) $$

where \(A\) is the amplitude, \(x_0\) is the center, and \(r\) is the rate.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Exponential.	required

Returns:

Type	Description
np.ndarray	The intensity of the Exponential at the given x values.

Source code in src/easydynamics/sample_model/components/exponential.py

def evaluate(
    self,
    x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
) -> np.ndarray:
    r"""
    Evaluate the Exponential at the given x values.

    If x is a scipp Variable, the unit of the Exponential will be converted to match x. The
    intensity is given by $$ I(x) = A \exp\left( r (x - x_0) \right) $$

    where $A$ is the amplitude, $x_0$ is the center, and $r$ is the rate.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Exponential.

    Returns
    -------
    np.ndarray
        The intensity of the Exponential at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)
    exponent = self.rate.value * (x - self.center.value)

    return self.amplitude.value * np.exp(exponent)

convert_unit(unit)

Convert the unit of the Parameters in the component.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The new unit to convert to.	required

Raises:

Type	Description
TypeError	If unit is not a string or sc.Unit.
Exception	If conversion fails for any parameter.

Source code in src/easydynamics/sample_model/components/exponential.py

def convert_unit(self, unit: str | sc.Unit) -> None:
    """
    Convert the unit of the Parameters in the component.

    Parameters
    ----------
    unit : str | sc.Unit
        The new unit to convert to.

    Raises
    ------
    TypeError
        If unit is not a string or sc.Unit.
    Exception
        If conversion fails for any parameter.
    """

    if not isinstance(unit, (str, sc.Unit)):
        raise TypeError('unit must be a string or sc.Unit')

    old_unit = self._unit
    pars = [self.amplitude, self.center]
    try:
        for p in pars:
            p.convert_unit(unit)
        self.rate.convert_unit('1/' + str(unit))
        self._unit = unit
    except Exception as e:
        # Attempt to rollback on failure
        try:
            for p in pars:
                p.convert_unit(old_unit)
            self.rate.convert_unit('1/' + str(old_unit))
        except Exception:  # noqa: S110
            pass  # Best effort rollback
        raise e

__repr__()

Return a string representation of the Exponential.

Returns:

Type	Description
str	A string representation of the Exponential.

Source code in src/easydynamics/sample_model/components/exponential.py

def __repr__(self) -> str:
    """
    Return a string representation of the Exponential.

    Returns
    -------
    str
        A string representation of the Exponential.
    """

    return (
        f'Exponential(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n '
        f'    amplitude = {self.amplitude},\n '
        f'    center = {self.center},\n '
        f'    rate = {self.rate})'
    )

ExpressionComponent

Bases: ModelComponent

Model component defined by a symbolic expression.

Source code in src/easydynamics/sample_model/components/expression_component.py

class ExpressionComponent(ModelComponent):
    """
    Model component defined by a symbolic expression.
    """

    # -------------------------
    # Allowed symbolic functions
    # -------------------------
    _ALLOWED_FUNCS: ClassVar[dict[str, object]] = {
        # Exponentials & logs
        'exp': sp.exp,
        'log': sp.log,
        'ln': sp.log,
        'sqrt': sp.sqrt,
        # Trigonometric
        'sin': sp.sin,
        'cos': sp.cos,
        'tan': sp.tan,
        'sinc': sp.sinc,
        'cot': sp.cot,
        'sec': sp.sec,
        'csc': sp.csc,
        'asin': sp.asin,
        'acos': sp.acos,
        'atan': sp.atan,
        # Hyperbolic
        'sinh': sp.sinh,
        'cosh': sp.cosh,
        'tanh': sp.tanh,
        # Misc
        'abs': sp.Abs,
        'sign': sp.sign,
        'floor': sp.floor,
        'ceil': sp.ceiling,
        # Special functions
        'erf': sp.erf,
    }

    # -------------------------
    # Allowed constants
    # -------------------------
    _ALLOWED_CONSTANTS: ClassVar[dict[str, object]] = {
        'pi': sp.pi,
        'E': sp.E,
    }

    _RESERVED_NAMES: ClassVar[dict[str, object]] = {'x'}

    def __init__(
        self,
        expression: str,
        parameters: dict[str, Numeric] | None = None,
        unit: str | sc.Unit = 'meV',
        name: str = 'Expression',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the ExpressionComponent.

        Parameters
        ----------
        expression : str
            The symbolic expression as a string. Must contain 'x' as the independent variable.
        parameters : dict[str, Numeric] | None, default=None
            Dictionary of parameter names and their initial values.
        unit : str | sc.Unit, default='meV'
            Unit of the output.
        name : str, default='Expression'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name for the component.
        unique_name : str | None, default=None
            Unique name for the component.

        Raises
        ------
        ValueError
            If the expression is invalid or does not contain 'x'.
        TypeError
            If any parameter value is not numeric.

        Examples
        --------
        >>> expr = ExpressionComponent(
        ...     'A * exp(-(x - x0)**2 / (2*sigma**2))',
        ...     parameters={'A': 10, 'x0': 0, 'sigma': 1},
        ...     unit='meV',
        ...     display_name='Gaussian Peak',
        ... )

        >>> expr.A = 5
        >>> y = expr.evaluate(x)
        """
        super().__init__(unit=unit, name=name, display_name=display_name, unique_name=unique_name)

        if 'np.' in expression:
            raise ValueError(
                'NumPy syntax (np.*) is not supported. '
                "Use functions like 'exp', 'sin', etc. directly."
            )

        self._expression_str = expression

        locals_dict = {}
        locals_dict.update(self._ALLOWED_FUNCS)
        locals_dict.update(self._ALLOWED_CONSTANTS)

        try:
            self._expr = sp.sympify(expression, locals=locals_dict)
        except Exception as e:
            raise ValueError(f'Invalid expression: {expression}') from e

        # Extract symbols from the expression
        symbols = self._expr.free_symbols
        symbol_names = sorted(str(s) for s in symbols)

        if 'x' not in symbol_names:
            raise ValueError("Expression must contain 'x' as independent variable")

        # Reject unknown functions early so invalid expressions fail at init,
        # not later during numerical evaluation.
        allowed_function_names = set(self._ALLOWED_FUNCS) | {
            func.__name__ for func in self._ALLOWED_FUNCS.values()
        }

        # Walk all function-call nodes in the parsed expression (e.g. sin(x), foo(x)).
        # Keep only function names that are not in our allowlist.
        unknown_function_names: set[str] = set()
        function_atoms = self._expr.atoms(sp.Function)
        for function_atom in function_atoms:
            function_name = function_atom.func.__name__
            if function_name not in allowed_function_names:
                unknown_function_names.add(function_name)

        unknown_functions = sorted(unknown_function_names)

        if unknown_functions:
            raise ValueError(
                f'Unsupported function(s) in expression: {", ".join(unknown_functions)}'
            )

        # Create parameters
        if parameters is not None and not isinstance(parameters, dict):
            raise TypeError(
                f'Parameters must be None or a dictionary, got {type(parameters).__name__}'
            )

        if parameters is not None:
            for name, value in parameters.items():
                if not isinstance(value, (Numeric, Parameter, dict)):
                    raise TypeError(
                        f"Parameter '{name}' must be numeric, "
                        f'a Parameter instance, or a dictionary, got {type(value).__name__}'
                    )
        parameters = parameters or {}
        self._parameters: dict[str, Parameter] = {}

        self._symbol_names = symbol_names
        for name in self._symbol_names:
            if name in self._RESERVED_NAMES:
                continue

            value = parameters.get(name, 1.0)
            if isinstance(value, Parameter):
                self._parameters[name] = value

            elif isinstance(value, dict) and value.get('@class') == 'Parameter':
                self._parameters[name] = Parameter.from_dict(value)
            else:
                self._parameters[name] = Parameter(
                    name=name,
                    value=value,
                    unit=self._unit,
                )

        # Create numerical function
        ordered_symbols = [sp.Symbol(name) for name in self._symbol_names]

        self._func = sp.lambdify(
            ordered_symbols,
            self._expr,
            modules=[{'erf': erf}, 'numpy'],
        )

        # -------------------------
        # Properties
        # -------------------------

    @property
    def expression(self) -> str:
        """
        Return the original expression string.

        Returns
        -------
        str
             The original expression string provided at initialization.
        """
        return self._expression_str

    @expression.setter
    def expression(self, _new_expr: str) -> None:
        """
        Prevent changing the expression after initialization.

        Parameters
        ----------
        _new_expr : str
            New expression string (ignored).

        Raises
        ------
        AttributeError
            Always raised to prevent changing the expression.
        """
        raise AttributeError('Expression cannot be changed after initialization')

    def evaluate(
        self,
        x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
    ) -> np.ndarray:
        """
        Evaluate the expression for given x values.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            Input values for the independent variable.

        Returns
        -------
        np.ndarray
            Evaluated results.
        """
        x = self._prepare_x_for_evaluate(x)

        args = []
        for name in self._symbol_names:
            if name == 'x':
                args.append(x)
            else:
                args.append(self._parameters[name].value)

        return self._func(*args)

    def get_all_variables(self) -> list[Parameter]:
        """
        Return all parameters.

        Returns
        -------
        list[Parameter]
            List of all parameters in the expression.
        """
        return list(self._parameters.values())

    def convert_unit(self, _new_unit: str | sc.Unit) -> None:
        """
        Convert the unit of the expression.

        Unit conversion is not implemented for ExpressionComponent.

        Parameters
        ----------
        _new_unit : str | sc.Unit
            The new unit to convert to (ignored).

        Raises
        ------
        NotImplementedError
            Always raised to indicate unit conversion is not supported.
        """

        raise NotImplementedError('Unit conversion is not implemented for ExpressionComponent')

    # -------------------------
    # dunder methods
    # -------------------------

    def __getattr__(self, name: str) -> Parameter:
        """
        Allow access to parameters as attributes.

        Parameters
        ----------
        name : str
            Name of the parameter to access.

        Raises
        ------
        AttributeError
            If the parameter does not exist.

        Returns
        -------
        Parameter
            The parameter with the given name.
        """
        if '_parameters' in self.__dict__ and name in self._parameters:
            return self._parameters[name]
        raise AttributeError(f"{self.__class__.__name__} has no attribute '{name}'")

    def __setattr__(self, name: str, value: Numeric) -> None:
        """
        Allow setting parameter values as attributes.

        Parameters
        ----------
        name : str
            Name of the parameter to set.
        value : Numeric
            New value for the parameter.

        Raises
        ------
        TypeError
            If the value is not numeric.
        """
        if '_parameters' in self.__dict__ and name in self._parameters:
            param = self._parameters[name]

            if not isinstance(value, Numeric):
                raise TypeError(f'{name} must be numeric')

            param.value = value
        else:
            # For other attributes, use default behavior
            super().__setattr__(name, value)

    def __dir__(self) -> list[str]:
        """
        Include parameter names in dir() output for better IDE support.

        Returns
        -------
        list[str]
            List of attribute names, including parameters.
        """
        return super().__dir__() + list(self._parameters.keys())

    def __repr__(self) -> str:
        """
        Return a string representation of the ExpressionComponent.

        Returns
        -------
        str
            String representation of the ExpressionComponent.
        """
        param_str = ', '.join(f'{k}={v.value}' for k, v in self._parameters.items())
        return (
            f'ExpressionComponent(name={self.name}, display_name={self.display_name}, '
            f'unit={self._unit},\n'
            f"    expr='{self._expression_str}',\n"
            f'    parameters={{ {param_str} }} )'
        )

expression property writable

Return the original expression string.

Returns:

Type	Description
str	The original expression string provided at initialization.

__init__(expression, parameters=None, unit='meV', name='Expression', display_name=None, unique_name=None)

Initialize the ExpressionComponent.

Parameters:

Name	Type	Description	Default
expression	str	The symbolic expression as a string. Must contain 'x' as the independent variable.	required
parameters	dict[str, Numeric] | None	Dictionary of parameter names and their initial values.	None
unit	str | sc.Unit	Unit of the output.	'meV'
name	str	Name of the component for indexing.	'Expression'
display_name	str | None	Display name for the component.	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'.
TypeError	If any parameter value is not numeric.

Examples:

>>> expr = ExpressionComponent(
...     'A * exp(-(x - x0)**2 / (2*sigma**2))',
...     parameters={'A': 10, 'x0': 0, 'sigma': 1},
...     unit='meV',
...     display_name='Gaussian Peak',
... )

>>> expr.A = 5
>>> y = expr.evaluate(x)

Source code in src/easydynamics/sample_model/components/expression_component.py

def __init__(
    self,
    expression: str,
    parameters: dict[str, Numeric] | None = None,
    unit: str | sc.Unit = 'meV',
    name: str = 'Expression',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the ExpressionComponent.

    Parameters
    ----------
    expression : str
        The symbolic expression as a string. Must contain 'x' as the independent variable.
    parameters : dict[str, Numeric] | None, default=None
        Dictionary of parameter names and their initial values.
    unit : str | sc.Unit, default='meV'
        Unit of the output.
    name : str, default='Expression'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name for the component.
    unique_name : str | None, default=None
        Unique name for the component.

    Raises
    ------
    ValueError
        If the expression is invalid or does not contain 'x'.
    TypeError
        If any parameter value is not numeric.

    Examples
    --------
    >>> expr = ExpressionComponent(
    ...     'A * exp(-(x - x0)**2 / (2*sigma**2))',
    ...     parameters={'A': 10, 'x0': 0, 'sigma': 1},
    ...     unit='meV',
    ...     display_name='Gaussian Peak',
    ... )

    >>> expr.A = 5
    >>> y = expr.evaluate(x)
    """
    super().__init__(unit=unit, name=name, display_name=display_name, unique_name=unique_name)

    if 'np.' in expression:
        raise ValueError(
            'NumPy syntax (np.*) is not supported. '
            "Use functions like 'exp', 'sin', etc. directly."
        )

    self._expression_str = expression

    locals_dict = {}
    locals_dict.update(self._ALLOWED_FUNCS)
    locals_dict.update(self._ALLOWED_CONSTANTS)

    try:
        self._expr = sp.sympify(expression, locals=locals_dict)
    except Exception as e:
        raise ValueError(f'Invalid expression: {expression}') from e

    # Extract symbols from the expression
    symbols = self._expr.free_symbols
    symbol_names = sorted(str(s) for s in symbols)

    if 'x' not in symbol_names:
        raise ValueError("Expression must contain 'x' as independent variable")

    # Reject unknown functions early so invalid expressions fail at init,
    # not later during numerical evaluation.
    allowed_function_names = set(self._ALLOWED_FUNCS) | {
        func.__name__ for func in self._ALLOWED_FUNCS.values()
    }

    # Walk all function-call nodes in the parsed expression (e.g. sin(x), foo(x)).
    # Keep only function names that are not in our allowlist.
    unknown_function_names: set[str] = set()
    function_atoms = self._expr.atoms(sp.Function)
    for function_atom in function_atoms:
        function_name = function_atom.func.__name__
        if function_name not in allowed_function_names:
            unknown_function_names.add(function_name)

    unknown_functions = sorted(unknown_function_names)

    if unknown_functions:
        raise ValueError(
            f'Unsupported function(s) in expression: {", ".join(unknown_functions)}'
        )

    # Create parameters
    if parameters is not None and not isinstance(parameters, dict):
        raise TypeError(
            f'Parameters must be None or a dictionary, got {type(parameters).__name__}'
        )

    if parameters is not None:
        for name, value in parameters.items():
            if not isinstance(value, (Numeric, Parameter, dict)):
                raise TypeError(
                    f"Parameter '{name}' must be numeric, "
                    f'a Parameter instance, or a dictionary, got {type(value).__name__}'
                )
    parameters = parameters or {}
    self._parameters: dict[str, Parameter] = {}

    self._symbol_names = symbol_names
    for name in self._symbol_names:
        if name in self._RESERVED_NAMES:
            continue

        value = parameters.get(name, 1.0)
        if isinstance(value, Parameter):
            self._parameters[name] = value

        elif isinstance(value, dict) and value.get('@class') == 'Parameter':
            self._parameters[name] = Parameter.from_dict(value)
        else:
            self._parameters[name] = Parameter(
                name=name,
                value=value,
                unit=self._unit,
            )

    # Create numerical function
    ordered_symbols = [sp.Symbol(name) for name in self._symbol_names]

    self._func = sp.lambdify(
        ordered_symbols,
        self._expr,
        modules=[{'erf': erf}, 'numpy'],
    )

evaluate(x)

Evaluate the expression for given x values.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	Input values for the independent variable.	required

Returns:

Type	Description
np.ndarray	Evaluated results.

Source code in src/easydynamics/sample_model/components/expression_component.py

def evaluate(
    self,
    x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
) -> np.ndarray:
    """
    Evaluate the expression for given x values.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        Input values for the independent variable.

    Returns
    -------
    np.ndarray
        Evaluated results.
    """
    x = self._prepare_x_for_evaluate(x)

    args = []
    for name in self._symbol_names:
        if name == 'x':
            args.append(x)
        else:
            args.append(self._parameters[name].value)

    return self._func(*args)

get_all_variables()

Return all parameters.

Returns:

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

Source code in src/easydynamics/sample_model/components/expression_component.py

def get_all_variables(self) -> list[Parameter]:
    """
    Return all parameters.

    Returns
    -------
    list[Parameter]
        List of all parameters in the expression.
    """
    return list(self._parameters.values())

convert_unit(_new_unit)

Convert the unit of the expression.

Unit conversion is not implemented for ExpressionComponent.

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.

Source code in src/easydynamics/sample_model/components/expression_component.py

def convert_unit(self, _new_unit: str | sc.Unit) -> None:
    """
    Convert the unit of the expression.

    Unit conversion is not implemented for ExpressionComponent.

    Parameters
    ----------
    _new_unit : str | sc.Unit
        The new unit to convert to (ignored).

    Raises
    ------
    NotImplementedError
        Always raised to indicate unit conversion is not supported.
    """

    raise NotImplementedError('Unit conversion is not implemented for ExpressionComponent')

__getattr__(name)

Allow access to parameters as attributes.

Parameters:

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

Raises:

Type	Description
AttributeError	If the parameter does not exist.

Returns:

Type	Description
Parameter	The parameter with the given name.

Source code in src/easydynamics/sample_model/components/expression_component.py

def __getattr__(self, name: str) -> Parameter:
    """
    Allow access to parameters as attributes.

    Parameters
    ----------
    name : str
        Name of the parameter to access.

    Raises
    ------
    AttributeError
        If the parameter does not exist.

    Returns
    -------
    Parameter
        The parameter with the given name.
    """
    if '_parameters' in self.__dict__ and name in self._parameters:
        return self._parameters[name]
    raise AttributeError(f"{self.__class__.__name__} has no attribute '{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
TypeError	If the value is not numeric.

Source code in src/easydynamics/sample_model/components/expression_component.py

def __setattr__(self, name: str, value: Numeric) -> None:
    """
    Allow setting parameter values as attributes.

    Parameters
    ----------
    name : str
        Name of the parameter to set.
    value : Numeric
        New value for the parameter.

    Raises
    ------
    TypeError
        If the value is not numeric.
    """
    if '_parameters' in self.__dict__ and name in self._parameters:
        param = self._parameters[name]

        if not isinstance(value, Numeric):
            raise TypeError(f'{name} must be numeric')

        param.value = value
    else:
        # For other attributes, use default behavior
        super().__setattr__(name, value)

__dir__()

Include parameter names in dir() output for better IDE support.

Returns:

Type	Description
list[str]	List of attribute names, including parameters.

Source code in src/easydynamics/sample_model/components/expression_component.py

def __dir__(self) -> list[str]:
    """
    Include parameter names in dir() output for better IDE support.

    Returns
    -------
    list[str]
        List of attribute names, including parameters.
    """
    return super().__dir__() + list(self._parameters.keys())

__repr__()

Return a string representation of the ExpressionComponent.

Returns:

Type	Description
str	String representation of the ExpressionComponent.

Source code in src/easydynamics/sample_model/components/expression_component.py

def __repr__(self) -> str:
    """
    Return a string representation of the ExpressionComponent.

    Returns
    -------
    str
        String representation of the ExpressionComponent.
    """
    param_str = ', '.join(f'{k}={v.value}' for k, v in self._parameters.items())
    return (
        f'ExpressionComponent(name={self.name}, display_name={self.display_name}, '
        f'unit={self._unit},\n'
        f"    expr='{self._expression_str}',\n"
        f'    parameters={{ {param_str} }} )'
    )

Gaussian

Bases: CreateParametersMixin, ModelComponent

Model of a Gaussian function.

The intensity is given by

$$ 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.

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

Source code in src/easydynamics/sample_model/components/gaussian.py

class Gaussian(CreateParametersMixin, ModelComponent):
    r"""
    Model of a Gaussian function.

     The intensity is given by

     $$ 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.

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

    def __init__(
        self,
        area: Numeric | Parameter = 1.0,
        center: Numeric | Parameter | None = None,
        width: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'Gaussian',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Gaussian component.

        Parameters
        ----------
        area : Numeric | Parameter, default=1.0
            Area of the Gaussian.
        center : Numeric | Parameter | None, default=None
            Center of the Gaussian. If None.
        width : Numeric | Parameter, default=1.0
            Standard deviation.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='Gaussian'
            Name of the component for indexing.
        display_name : str | None, default=None
            Name of the component.
        unique_name : str | None, default=None
            Unique name of the component. if None, a unique_name is automatically generated. By
            default, None.
        """
        # Validate inputs and create Parameters if not given
        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )
        width = self._create_width_parameter(width=width, name=name, unit=self._unit)

        self._area = area
        self._center = center
        self._width = width

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """

        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """

        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """

        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the center parameter value.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter. If None, defaults to 0 and is fixed.

        Raises
        ------
        TypeError
            If the value is not a number or None.
        """

        if value is None:
            value = 0.0
            self._center.fixed = True
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    @property
    def width(self) -> Parameter:
        """
        Get the width parameter (standard deviation).

        Returns
        -------
        Parameter
            The width parameter.
        """
        return self._width

    @width.setter
    def width(self, value: Numeric) -> None:
        """
        Set the width parameter value.

        Parameters
        ----------
        value : Numeric
            The new value for the width parameter.

        Raises
        ------
        TypeError
            If the value is not a number or None.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('width must be a number')

        if float(value) <= 0:
            raise ValueError('width must be positive')

        self._width.value = value

    def evaluate(
        self,
        x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
    ) -> np.ndarray:
        r"""
        Evaluate the Gaussian at the given x values.

        If x is a scipp Variable, the unit of the Gaussian will be converted to match x. The
        intensity is given by $$ 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.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Gaussian.

        Returns
        -------
        np.ndarray
            The intensity of the Gaussian at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        normalization = 1 / (np.sqrt(2 * np.pi) * self.width.value)
        exponent = -0.5 * ((x - self.center.value) / self.width.value) ** 2

        return self.area.value * normalization * np.exp(exponent)

    def __repr__(self) -> str:
        """
        Return a string representation of the Gaussian.

        Returns
        -------
        str
            A string representation of the Gaussian.
        """

        return (
            f'Gaussian(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n'
            f'    area = {self.area},\n'
            f'    center = {self.center},\n'
            f'    width = {self.width})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

width property writable

Get the width parameter (standard deviation).

Returns:

Type	Description
Parameter	The width parameter.

__init__(area=1.0, center=None, width=1.0, unit='meV', name='Gaussian', display_name=None, unique_name=None)

Initialize the Gaussian component.

Parameters:

Name	Type	Description	Default
area	Numeric | Parameter	Area of the Gaussian.	1.0
center	Numeric | Parameter | None	Center of the Gaussian. If None.	None
width	Numeric | Parameter	Standard deviation.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'Gaussian'
display_name	str | None	Name of the component.	None
unique_name	str | None	Unique name of the component. if None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/gaussian.py

def __init__(
    self,
    area: Numeric | Parameter = 1.0,
    center: Numeric | Parameter | None = None,
    width: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'Gaussian',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Gaussian component.

    Parameters
    ----------
    area : Numeric | Parameter, default=1.0
        Area of the Gaussian.
    center : Numeric | Parameter | None, default=None
        Center of the Gaussian. If None.
    width : Numeric | Parameter, default=1.0
        Standard deviation.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='Gaussian'
        Name of the component for indexing.
    display_name : str | None, default=None
        Name of the component.
    unique_name : str | None, default=None
        Unique name of the component. if None, a unique_name is automatically generated. By
        default, None.
    """
    # Validate inputs and create Parameters if not given
    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )
    width = self._create_width_parameter(width=width, name=name, unit=self._unit)

    self._area = area
    self._center = center
    self._width = width

evaluate(x)

Evaluate the Gaussian at the given x values.

If x is a scipp Variable, the unit of the Gaussian will be converted to match x. The intensity is given by $$ 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.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Gaussian.	required

Returns:

Type	Description
np.ndarray	The intensity of the Gaussian at the given x values.

Source code in src/easydynamics/sample_model/components/gaussian.py

def evaluate(
    self,
    x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
) -> np.ndarray:
    r"""
    Evaluate the Gaussian at the given x values.

    If x is a scipp Variable, the unit of the Gaussian will be converted to match x. The
    intensity is given by $$ 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.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Gaussian.

    Returns
    -------
    np.ndarray
        The intensity of the Gaussian at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    normalization = 1 / (np.sqrt(2 * np.pi) * self.width.value)
    exponent = -0.5 * ((x - self.center.value) / self.width.value) ** 2

    return self.area.value * normalization * np.exp(exponent)

__repr__()

Return a string representation of the Gaussian.

Returns:

Type	Description
str	A string representation of the Gaussian.

Source code in src/easydynamics/sample_model/components/gaussian.py

def __repr__(self) -> str:
    """
    Return a string representation of the Gaussian.

    Returns
    -------
    str
        A string representation of the Gaussian.
    """

    return (
        f'Gaussian(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n'
        f'    area = {self.area},\n'
        f'    center = {self.center},\n'
        f'    width = {self.width})'
    )

Lorentzian

Bases: CreateParametersMixin, ModelComponent

Model of a Lorentzian function.

The intensity is given by $$ 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 half width at half maximum (HWHM).

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

Source code in src/easydynamics/sample_model/components/lorentzian.py

class Lorentzian(CreateParametersMixin, ModelComponent):
    r"""
    Model of a Lorentzian function.

    The intensity is given by $$ 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 half width at half maximum
    (HWHM).

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

    def __init__(
        self,
        area: Numeric | Parameter = 1.0,
        center: Numeric | Parameter | None = None,
        width: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'Lorentzian',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Lorentzian component.

        Parameters
        ----------
        area : Numeric | Parameter, default=1.0
            Area of the Lorentzian.
        center : Numeric | Parameter | None, default=None
            Center of the Lorentzian. If None, defaults to 0 and is fixed.
        width : Numeric | Parameter, default=1.0
            Half width at half maximum (HWHM).
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='Lorentzian'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name for the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.
        """

        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )
        width = self._create_width_parameter(width=width, name=name, unit=self._unit)

        self._area = area
        self._center = center
        self._width = width

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """
        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """
        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the value of the center parameter.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter. If None, defaults to 0 and is fixed.

        Raises
        ------
        TypeError
            If the value is not a number or None.
        """

        if value is None:
            value = 0.0
            self._center.fixed = True
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    @property
    def width(self) -> Parameter:
        """
        Get the width parameter (HWHM).

        Returns
        -------
        Parameter
            The width parameter.
        """
        return self._width

    @width.setter
    def width(self, value: Numeric) -> None:
        """
        Set the width parameter value (HWHM).

        Parameters
        ----------
        value : Numeric
            The new value for the width parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('width must be a number')

        if float(value) <= 0:
            raise ValueError('width must be positive')
        self._width.value = value

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        r"""
        Evaluate the Lorentzian at the given x values.

        If x is a scipp Variable, the unit of the Lorentzian will be converted to match x. The
        intensity is given by

        $$ 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 half width at half maximum
        (HWHM).

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Lorentzian.

        Returns
        -------
        np.ndarray
            The intensity of the Lorentzian at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        normalization = self.width.value / np.pi
        denominator = (x - self.center.value) ** 2 + self.width.value**2

        return self.area.value * normalization / denominator

    def __repr__(self) -> str:
        """
        Return a string representation of the Lorentzian.

        Returns
        -------
        str
            A string representation of the Lorentzian.
        """
        return (
            f'Lorentzian(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n'
            f'    area = {self.area},\n'
            f'    center = {self.center},\n'
            f'    width = {self.width})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

width property writable

Get the width parameter (HWHM).

Returns:

Type	Description
Parameter	The width parameter.

__init__(area=1.0, center=None, width=1.0, unit='meV', name='Lorentzian', display_name=None, unique_name=None)

Initialize the Lorentzian component.

Parameters:

Name	Type	Description	Default
area	Numeric | Parameter	Area of the Lorentzian.	1.0
center	Numeric | Parameter | None	Center of the Lorentzian. If None, defaults to 0 and is fixed.	None
width	Numeric | Parameter	Half width at half maximum (HWHM).	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'Lorentzian'
display_name	str | None	Display name for the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/lorentzian.py

def __init__(
    self,
    area: Numeric | Parameter = 1.0,
    center: Numeric | Parameter | None = None,
    width: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'Lorentzian',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Lorentzian component.

    Parameters
    ----------
    area : Numeric | Parameter, default=1.0
        Area of the Lorentzian.
    center : Numeric | Parameter | None, default=None
        Center of the Lorentzian. If None, defaults to 0 and is fixed.
    width : Numeric | Parameter, default=1.0
        Half width at half maximum (HWHM).
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='Lorentzian'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name for the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.
    """

    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )
    width = self._create_width_parameter(width=width, name=name, unit=self._unit)

    self._area = area
    self._center = center
    self._width = width

evaluate(x)

Evaluate the Lorentzian at the given x values.

If x is a scipp Variable, the unit of the Lorentzian will be converted to match x. The intensity is given by

\[ 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 half width at half maximum (HWHM).

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Lorentzian.	required

Returns:

Type	Description
np.ndarray	The intensity of the Lorentzian at the given x values.

Source code in src/easydynamics/sample_model/components/lorentzian.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    r"""
    Evaluate the Lorentzian at the given x values.

    If x is a scipp Variable, the unit of the Lorentzian will be converted to match x. The
    intensity is given by

    $$ 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 half width at half maximum
    (HWHM).

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Lorentzian.

    Returns
    -------
    np.ndarray
        The intensity of the Lorentzian at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    normalization = self.width.value / np.pi
    denominator = (x - self.center.value) ** 2 + self.width.value**2

    return self.area.value * normalization / denominator

__repr__()

Return a string representation of the Lorentzian.

Returns:

Type	Description
str	A string representation of the Lorentzian.

Source code in src/easydynamics/sample_model/components/lorentzian.py

def __repr__(self) -> str:
    """
    Return a string representation of the Lorentzian.

    Returns
    -------
    str
        A string representation of the Lorentzian.
    """
    return (
        f'Lorentzian(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n'
        f'    area = {self.area},\n'
        f'    center = {self.center},\n'
        f'    width = {self.width})'
    )

Polynomial

Bases: ModelComponent

Polynomial function component.

The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ... + c_N x^N, $$ where \(C_i\) are the coefficients.

Source code in src/easydynamics/sample_model/components/polynomial.py

class Polynomial(ModelComponent):
    r"""
    Polynomial function component.

    The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ... + c_N x^N, $$ where $C_i$ are
    the coefficients.
    """

    def __init__(
        self,
        coefficients: Sequence[Numeric | Parameter] = (0.0,),
        unit: str | sc.Unit = 'meV',
        name: str = 'Polynomial',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Polynomial component.

        Parameters
        ----------
        coefficients : Sequence[Numeric | Parameter], default=(0.0,)
            Coefficients c0, c1, ..., cN.
        unit : str | sc.Unit, default='meV'
            Unit of the Polynomial component.
        name : str, default='Polynomial'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the Polynomial component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.

        Raises
        ------
        TypeError
            If coefficients is not a sequence of numbers or Parameters or if any item in
            coefficients is not a number or Parameter.
        ValueError
            If coefficients is an empty sequence.
        """

        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        if not isinstance(coefficients, (list, tuple, np.ndarray)):
            raise TypeError(
                'coefficients must be a sequence (list/tuple/ndarray) \
                    of numbers or Parameter objects.'
            )

        if len(coefficients) == 0:
            raise ValueError('At least one coefficient must be provided.')

        # Internal storage of Parameter objects
        self._coefficients: list[Parameter] = []

        # Coefficients are treated as dimensionless Parameters
        for i, coef in enumerate(coefficients):
            if isinstance(coef, Parameter):
                param = coef
            elif isinstance(coef, Numeric):
                param = Parameter(name=f'{name}_c{i}', value=float(coef))
            else:
                raise TypeError('Each coefficient must be either a numeric value or a Parameter.')
            self._coefficients.append(param)

        # Helper scipp scalar to track unit conversions
        # (value initialized to 1 with provided unit)
        self._unit_conversion_helper = sc.scalar(value=1.0, unit=unit)

    @property
    def coefficients(self) -> list[Parameter]:
        """
        Get the coefficients of the polynomial as a list of Parameters.

        Returns
        -------
        list[Parameter]
            The coefficients of the polynomial.
        """
        return list(self._coefficients)

    @coefficients.setter
    def coefficients(self, coeffs: Sequence[Numeric | Parameter]) -> None:
        """
        Set the coefficients of the polynomial.

        Length must match current number of coefficients.

        Parameters
        ----------
        coeffs : Sequence[Numeric | Parameter]
            New coefficients as a sequence of numbers or Parameters.

        Raises
        ------
        TypeError
            If coeffs is not a sequence of numbers or Parameters or if any item in coeffs is not a
            number or Parameter.
        ValueError
            If the length of coeffs does not match the existing number of coefficients.
        """
        if not isinstance(coeffs, (list, tuple, np.ndarray)):
            raise TypeError(
                'coefficients must be a sequence (list/tuple/ndarray) of numbers or Parameter .'
            )
        if len(coeffs) != len(self._coefficients):
            raise ValueError(
                'Number of coefficients must match the existing number of coefficients.'
            )
        for i, coef in enumerate(coeffs):
            if isinstance(coef, Parameter):
                # replace parameter
                self._coefficients[i] = coef
            elif isinstance(coef, Numeric):
                self._coefficients[i].value = float(coef)
            else:
                raise TypeError('Each coefficient must be either a numeric value or a Parameter.')

    def coefficient_values(self) -> list[float]:
        """
        Get the coefficients of the polynomial as a list.

        Returns
        -------
        list[float]
            The coefficient values of the polynomial.
        """
        return [param.value for param in self._coefficients]

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        r"""
        Evaluate the Polynomial at the given x values.

        The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ...
        + c_N x^N, $$ where $C_i$ are the coefficients.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Polynomial.

        Returns
        -------
        np.ndarray
            The evaluated Polynomial at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        result = np.zeros_like(x, dtype=float)
        for i, param in enumerate(self._coefficients):
            result += param.value * np.power(x, i)

        if any(result < 0):
            warnings.warn(
                f'The Polynomial with unique_name {self.unique_name} has negative values, '
                'which may not be physically meaningful.',
                UserWarning,
                stacklevel=2,
            )
        return result

    @property
    def degree(self) -> int:
        """
        Get the degree of the polynomial.

        Returns
        -------
        int
            The degree of the polynomial.
        """
        return len(self._coefficients) - 1

    @degree.setter
    def degree(self, _value: int) -> None:
        """
        The degree is determined by the number of coefficients and cannot be set directly.

        Parameters
        ----------
        _value : int
            The new degree of the polynomial.

        Raises
        ------
        AttributeError
            Always raised since degree cannot be set directly.
        """
        raise AttributeError(
            'The degree of the polynomial is determined by the number of coefficients '
            'and cannot be set directly.'
        )

    def get_all_variables(self) -> list[DescriptorBase]:
        """
        Get all variables from the model component.

        Returns
        -------
        list[DescriptorBase]
            List of variables in the component.
        """
        return list(self._coefficients)

    def convert_unit(self, unit: str | sc.Unit) -> None:
        """
        Convert the unit of the polynomial.

        Parameters
        ----------
        unit : str | sc.Unit
            The target unit to convert to.

        Raises
        ------
        UnitError
            If the provided unit is not a string or sc.Unit.
        """

        if not isinstance(unit, (str, sc.Unit)):
            raise UnitError('unit must be a string or a scipp unit.')

        # Find out how much the unit changes
        # by converting a helper variable
        conversion_value_before = self._unit_conversion_helper.value
        self._unit_conversion_helper = sc.to_unit(self._unit_conversion_helper, unit=unit)
        conversion_value_after = self._unit_conversion_helper.value
        for i, param in enumerate(self._coefficients):
            param.value *= (
                conversion_value_before / conversion_value_after
            ) ** i  # set the values directly to the appropriate power

        self._unit = unit

    def __repr__(self) -> str:
        """
        Return a string representation of the Polynomial.

        Returns
        -------
        str
            A string representation of the Polynomial.
        """

        coeffs_str = ', '.join(f'{param.name}={param.value}' for param in self._coefficients)
        return (
            f'Polynomial(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n'
            f'    coefficients = [{coeffs_str}])'
        )

coefficients property writable

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

Returns:

Type	Description
list[Parameter]	The coefficients of the polynomial.

degree property writable

Get the degree of the polynomial.

Returns:

Type	Description
int	The degree of the polynomial.

__init__(coefficients=(0.0,), unit='meV', name='Polynomial', display_name=None, unique_name=None)

Initialize the Polynomial component.

Parameters:

Name	Type	Description	Default
coefficients	Sequence[Numeric | Parameter]	Coefficients c0, c1, ..., cN.	(0.0,)
unit	str | sc.Unit	Unit of the Polynomial component.	'meV'
name	str	Name of the component for indexing.	'Polynomial'
display_name	str | None	Display name of the Polynomial component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Raises:

Type	Description
TypeError	If coefficients is not a sequence of numbers or Parameters or if any item in coefficients is not a number or Parameter.
ValueError	If coefficients is an empty sequence.

Source code in src/easydynamics/sample_model/components/polynomial.py

def __init__(
    self,
    coefficients: Sequence[Numeric | Parameter] = (0.0,),
    unit: str | sc.Unit = 'meV',
    name: str = 'Polynomial',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Polynomial component.

    Parameters
    ----------
    coefficients : Sequence[Numeric | Parameter], default=(0.0,)
        Coefficients c0, c1, ..., cN.
    unit : str | sc.Unit, default='meV'
        Unit of the Polynomial component.
    name : str, default='Polynomial'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the Polynomial component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.

    Raises
    ------
    TypeError
        If coefficients is not a sequence of numbers or Parameters or if any item in
        coefficients is not a number or Parameter.
    ValueError
        If coefficients is an empty sequence.
    """

    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    if not isinstance(coefficients, (list, tuple, np.ndarray)):
        raise TypeError(
            'coefficients must be a sequence (list/tuple/ndarray) \
                of numbers or Parameter objects.'
        )

    if len(coefficients) == 0:
        raise ValueError('At least one coefficient must be provided.')

    # Internal storage of Parameter objects
    self._coefficients: list[Parameter] = []

    # Coefficients are treated as dimensionless Parameters
    for i, coef in enumerate(coefficients):
        if isinstance(coef, Parameter):
            param = coef
        elif isinstance(coef, Numeric):
            param = Parameter(name=f'{name}_c{i}', value=float(coef))
        else:
            raise TypeError('Each coefficient must be either a numeric value or a Parameter.')
        self._coefficients.append(param)

    # Helper scipp scalar to track unit conversions
    # (value initialized to 1 with provided unit)
    self._unit_conversion_helper = sc.scalar(value=1.0, unit=unit)

coefficient_values()

Get the coefficients of the polynomial as a list.

Returns:

Type	Description
list[float]	The coefficient values of the polynomial.

Source code in src/easydynamics/sample_model/components/polynomial.py

def coefficient_values(self) -> list[float]:
    """
    Get the coefficients of the polynomial as a list.

    Returns
    -------
    list[float]
        The coefficient values of the polynomial.
    """
    return [param.value for param in self._coefficients]

evaluate(x)

Evaluate the Polynomial at the given x values.

The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ... + c_N x^N, $$ where \(C_i\) are the coefficients.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Polynomial.	required

Returns:

Type	Description
np.ndarray	The evaluated Polynomial at the given x values.

Source code in src/easydynamics/sample_model/components/polynomial.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    r"""
    Evaluate the Polynomial at the given x values.

    The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ...
    + c_N x^N, $$ where $C_i$ are the coefficients.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Polynomial.

    Returns
    -------
    np.ndarray
        The evaluated Polynomial at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    result = np.zeros_like(x, dtype=float)
    for i, param in enumerate(self._coefficients):
        result += param.value * np.power(x, i)

    if any(result < 0):
        warnings.warn(
            f'The Polynomial with unique_name {self.unique_name} has negative values, '
            'which may not be physically meaningful.',
            UserWarning,
            stacklevel=2,
        )
    return result

get_all_variables()

Get all variables from the model component.

Returns:

Type	Description
list[DescriptorBase]	List of variables in the component.

Source code in src/easydynamics/sample_model/components/polynomial.py

def get_all_variables(self) -> list[DescriptorBase]:
    """
    Get all variables from the model component.

    Returns
    -------
    list[DescriptorBase]
        List of variables in the component.
    """
    return list(self._coefficients)

convert_unit(unit)

Convert the unit of the polynomial.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The target unit to convert to.	required

Raises:

Type	Description
UnitError	If the provided unit is not a string or sc.Unit.

Source code in src/easydynamics/sample_model/components/polynomial.py

def convert_unit(self, unit: str | sc.Unit) -> None:
    """
    Convert the unit of the polynomial.

    Parameters
    ----------
    unit : str | sc.Unit
        The target unit to convert to.

    Raises
    ------
    UnitError
        If the provided unit is not a string or sc.Unit.
    """

    if not isinstance(unit, (str, sc.Unit)):
        raise UnitError('unit must be a string or a scipp unit.')

    # Find out how much the unit changes
    # by converting a helper variable
    conversion_value_before = self._unit_conversion_helper.value
    self._unit_conversion_helper = sc.to_unit(self._unit_conversion_helper, unit=unit)
    conversion_value_after = self._unit_conversion_helper.value
    for i, param in enumerate(self._coefficients):
        param.value *= (
            conversion_value_before / conversion_value_after
        ) ** i  # set the values directly to the appropriate power

    self._unit = unit

__repr__()

Return a string representation of the Polynomial.

Returns:

Type	Description
str	A string representation of the Polynomial.

Source code in src/easydynamics/sample_model/components/polynomial.py

def __repr__(self) -> str:
    """
    Return a string representation of the Polynomial.

    Returns
    -------
    str
        A string representation of the Polynomial.
    """

    coeffs_str = ', '.join(f'{param.name}={param.value}' for param in self._coefficients)
    return (
        f'Polynomial(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n'
        f'    coefficients = [{coeffs_str}])'
    )

Voigt

Bases: CreateParametersMixin, ModelComponent

Voigt profile, a convolution of Gaussian and Lorentzian.

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

Use scipy.special.voigt_profile to evaluate the Voigt profile.

Source code in src/easydynamics/sample_model/components/voigt.py

class Voigt(CreateParametersMixin, ModelComponent):
    r"""
    Voigt profile, a convolution of Gaussian and Lorentzian.

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

    Use scipy.special.voigt_profile to evaluate the Voigt profile.
    """

    def __init__(
        self,
        area: Numeric | Parameter = 1.0,
        center: Numeric | Parameter | None = None,
        gaussian_width: Numeric | Parameter = 1.0,
        lorentzian_width: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'Voigt',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize a Voigt component.

        Parameters
        ----------
        area : Numeric | Parameter, default=1.0
            Total area under the curve.
        center : Numeric | Parameter | None, default=None
            Center of the Voigt profile.
        gaussian_width : Numeric | Parameter, default=1.0
            Standard deviation of the Gaussian part.
        lorentzian_width : Numeric | Parameter, default=1.0
            Half width at half max (HWHM) of the Lorentzian part.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='Voigt'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.
        """

        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )
        gaussian_width = self._create_width_parameter(
            width=gaussian_width,
            name=name,
            param_name='gaussian_width',
            unit=self._unit,
        )
        lorentzian_width = self._create_width_parameter(
            width=lorentzian_width,
            name=name,
            param_name='lorentzian_width',
            unit=self._unit,
        )

        self._area = area
        self._center = center
        self._gaussian_width = gaussian_width
        self._lorentzian_width = lorentzian_width

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """
        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """
        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the value of the center parameter.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter. If None, defaults to 0 and is fixed.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if value is None:
            value = 0.0
            self._center.fixed = True
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    @property
    def gaussian_width(self) -> Parameter:
        """
        Get the Gaussian width parameter.

        Returns
        -------
        Parameter
            The Gaussian width parameter.
        """
        return self._gaussian_width

    @gaussian_width.setter
    def gaussian_width(self, value: Numeric) -> None:
        """
        Set the width parameter value.

        Parameters
        ----------
        value : Numeric
            The new value for the width parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('gaussian_width must be a number')
        if float(value) <= 0:
            raise ValueError('gaussian_width must be positive')
        self._gaussian_width.value = value

    @property
    def lorentzian_width(self) -> Parameter:
        """
        Get the Lorentzian width parameter (HWHM).

        Returns
        -------
        Parameter
            The Lorentzian width parameter.
        """
        return self._lorentzian_width

    @lorentzian_width.setter
    def lorentzian_width(self, value: Numeric) -> None:
        """
        Set the value of the Lorentzian width parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the Lorentzian width parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('lorentzian_width must be a number')
        if float(value) <= 0:
            raise ValueError('lorentzian_width must be positive')
        self._lorentzian_width.value = value

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        r"""
        Evaluate the Voigt at the given x values.

        If x is a scipp Variable, the unit of the Voigt will be converted to match x. The Voigt
        evaluates to the convolution of a Gaussian with sigma gaussian_width and a Lorentzian with
        half width at half max lorentzian_width, centered at center, with area equal to area.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Voigt.

        Returns
        -------
        np.ndarray
            The intensity of the Voigt at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        return self.area.value * voigt_profile(
            x - self.center.value,
            self.gaussian_width.value,
            self.lorentzian_width.value,
        )

    def __repr__(self) -> str:
        """
        Return a string representation of the Voigt.

        Returns
        -------
        str
            A string representation of the Voigt.
        """

        return (
            f'Voigt(name = {self.name}, display_name = {self.display_name}, unit = {self._unit},\n'
            f'    area = {self.area},\n'
            f'    center = {self.center},\n'
            f'    gaussian_width = {self.gaussian_width},\n'
            f'    lorentzian_width = {self.lorentzian_width})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

gaussian_width property writable

Get the Gaussian width parameter.

Returns:

Type	Description
Parameter	The Gaussian width parameter.

lorentzian_width property writable

Get the Lorentzian width parameter (HWHM).

Returns:

Type	Description
Parameter	The Lorentzian width parameter.

__init__(area=1.0, center=None, gaussian_width=1.0, lorentzian_width=1.0, unit='meV', name='Voigt', display_name=None, unique_name=None)

Initialize a Voigt component.

Parameters:

Name	Type	Description	Default
area	Numeric | Parameter	Total area under the curve.	1.0
center	Numeric | Parameter | None	Center of the Voigt profile.	None
gaussian_width	Numeric | Parameter	Standard deviation of the Gaussian part.	1.0
lorentzian_width	Numeric | Parameter	Half width at half max (HWHM) of the Lorentzian part.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'Voigt'
display_name	str | None	Display name of the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/voigt.py

def __init__(
    self,
    area: Numeric | Parameter = 1.0,
    center: Numeric | Parameter | None = None,
    gaussian_width: Numeric | Parameter = 1.0,
    lorentzian_width: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'Voigt',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize a Voigt component.

    Parameters
    ----------
    area : Numeric | Parameter, default=1.0
        Total area under the curve.
    center : Numeric | Parameter | None, default=None
        Center of the Voigt profile.
    gaussian_width : Numeric | Parameter, default=1.0
        Standard deviation of the Gaussian part.
    lorentzian_width : Numeric | Parameter, default=1.0
        Half width at half max (HWHM) of the Lorentzian part.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='Voigt'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.
    """

    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )
    gaussian_width = self._create_width_parameter(
        width=gaussian_width,
        name=name,
        param_name='gaussian_width',
        unit=self._unit,
    )
    lorentzian_width = self._create_width_parameter(
        width=lorentzian_width,
        name=name,
        param_name='lorentzian_width',
        unit=self._unit,
    )

    self._area = area
    self._center = center
    self._gaussian_width = gaussian_width
    self._lorentzian_width = lorentzian_width

evaluate(x)

Evaluate the Voigt at the given x values.

If x is a scipp Variable, the unit of the Voigt will be converted to match x. The Voigt evaluates to the convolution of a Gaussian with sigma gaussian_width and a Lorentzian with half width at half max lorentzian_width, centered at center, with area equal to area.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Voigt.	required

Returns:

Type	Description
np.ndarray	The intensity of the Voigt at the given x values.

Source code in src/easydynamics/sample_model/components/voigt.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    r"""
    Evaluate the Voigt at the given x values.

    If x is a scipp Variable, the unit of the Voigt will be converted to match x. The Voigt
    evaluates to the convolution of a Gaussian with sigma gaussian_width and a Lorentzian with
    half width at half max lorentzian_width, centered at center, with area equal to area.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Voigt.

    Returns
    -------
    np.ndarray
        The intensity of the Voigt at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    return self.area.value * voigt_profile(
        x - self.center.value,
        self.gaussian_width.value,
        self.lorentzian_width.value,
    )

__repr__()

Return a string representation of the Voigt.

Returns:

Type	Description
str	A string representation of the Voigt.

Source code in src/easydynamics/sample_model/components/voigt.py

def __repr__(self) -> str:
    """
    Return a string representation of the Voigt.

    Returns
    -------
    str
        A string representation of the Voigt.
    """

    return (
        f'Voigt(name = {self.name}, display_name = {self.display_name}, unit = {self._unit},\n'
        f'    area = {self.area},\n'
        f'    center = {self.center},\n'
        f'    gaussian_width = {self.gaussian_width},\n'
        f'    lorentzian_width = {self.lorentzian_width})'
    )

BrownianTranslationalDiffusion

Bases: DiffusionModelBase

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:

>>> Q=np.linspace(0.5,2,7) >>>energy=np.linspace(-2, 2, 501)
>>> scale = 1.0
>>> diffusion_coefficient = 2.4e-9  # m^2/s
>>> diffusion_model=BrownianTranslationalDiffusion(name="DiffusionModel",
>>> scale=scale, diffusion_coefficient= diffusion_coefficient,)
>>> component_collections = diffusion_model.create_component_collections(Q)

See also the tutorials.

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

class BrownianTranslationalDiffusion(DiffusionModelBase):
    r"""
    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
    --------
    >>> Q=np.linspace(0.5,2,7) >>>energy=np.linspace(-2, 2, 501)
    >>> scale = 1.0
    >>> diffusion_coefficient = 2.4e-9  # m^2/s
    >>> diffusion_model=BrownianTranslationalDiffusion(name="DiffusionModel",
    >>> scale=scale, diffusion_coefficient= diffusion_coefficient,)
    >>> component_collections = diffusion_model.create_component_collections(Q)

    See also the tutorials.
    """

    def __init__(
        self,
        scale: Numeric = 1.0,
        diffusion_coefficient: Numeric = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'BrownianTranslationalDiffusion',
        display_name: str | None = 'BrownianTranslationalDiffusion',
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize a new BrownianTranslationalDiffusion model.

        Parameters
        ----------
        scale : Numeric, default=1.0
            Scale factor for the diffusion model. Must be a non-negative number.
        diffusion_coefficient : Numeric, default=1.0
            Diffusion coefficient D in m^2/s.
        unit : str | sc.Unit, default='meV'
            Unit of the diffusion model. Must be convertible to meV.
        name : str, default='BrownianTranslationalDiffusion'
            Name of the diffusion model.
        display_name : str | None, default='BrownianTranslationalDiffusion'
            Display name of the diffusion model.
        unique_name : str | None, default=None
            Unique name of the diffusion model. If None, a unique name will be generated. By
            default, None.

        Raises
        ------
        TypeError
            If scale or diffusion_coefficient is not a number.
        """
        if not isinstance(scale, Numeric):
            raise TypeError('scale must be a number.')

        if not isinstance(diffusion_coefficient, Numeric):
            raise TypeError('diffusion_coefficient must be a number.')

        diffusion_coefficient = Parameter(
            name='diffusion_coefficient',
            value=float(diffusion_coefficient),
            fixed=False,
            unit='m**2/s',
            min=0.0,
        )
        super().__init__(
            unit=unit,
            scale=scale,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )
        self._hbar = hbar
        self._angstrom = angstrom
        self._diffusion_coefficient = diffusion_coefficient

    # ------------------------------------------------------------------
    # Properties
    # ------------------------------------------------------------------

    @property
    def diffusion_coefficient(self) -> Parameter:
        """
        Get the diffusion coefficient parameter D.

        Returns
        -------
        Parameter
            Diffusion coefficient D in m^2/s.
        """
        return self._diffusion_coefficient

    @diffusion_coefficient.setter
    def diffusion_coefficient(self, diffusion_coefficient: Numeric) -> None:
        """
        Set the diffusion coefficient parameter D.

        Parameters
        ----------
        diffusion_coefficient : Numeric
            The new value for the diffusion coefficient D in m^2/s.

        Raises
        ------
        TypeError
            If diffusion_coefficient is not a number.
        ValueError
            If diffusion_coefficient is negative.
        """
        if not isinstance(diffusion_coefficient, Numeric):
            raise TypeError('diffusion_coefficient must be a number.')

        if float(diffusion_coefficient) < 0:
            raise ValueError('diffusion_coefficient must be non-negative.')
        self._diffusion_coefficient.value = float(diffusion_coefficient)

    # ------------------------------------------------------------------
    # Other methods
    # ------------------------------------------------------------------

    def calculate_width(self, Q: Q_type) -> np.ndarray:
        """
        Calculate the half-width at half-maximum (HWHM) for the diffusion model.

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom.

        Returns
        -------
        np.ndarray
            HWHM values in the unit of the model (e.g., meV).
        """

        Q = _validate_and_convert_Q(Q)

        unit_conversion_factor = self._hbar * self.diffusion_coefficient / (self._angstrom**2)
        unit_conversion_factor.convert_unit(self.unit)
        return Q**2 * unit_conversion_factor.value

    def calculate_EISF(self, Q: Q_type) -> np.ndarray:
        """
        Calculate the Elastic Incoherent Structure Factor (EISF) for the Brownian translational
        diffusion model.

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom.

        Returns
        -------
        np.ndarray
            EISF values (dimensionless).
        """
        Q = _validate_and_convert_Q(Q)
        return np.zeros_like(Q)

    def calculate_QISF(self, Q: Q_type) -> np.ndarray:
        """
        Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom.

        Returns
        -------
        np.ndarray
            QISF values (dimensionless).
        """

        Q = _validate_and_convert_Q(Q)
        return np.ones_like(Q)

    def create_component_collections(
        self,
        Q: Q_type,
        component_name: str = 'Brownian diffusion',
        component_display_name: str | None = None,
    ) -> list[ComponentCollection]:
        r"""
        Create ComponentCollection components for the Brownian translational diffusion model at
        given Q values.

        Parameters
        ----------
        Q : Q_type
            Scattering vector values.
        component_name : str, default='Brownian diffusion'
            Name of the Brownian diffusion component.
        component_display_name : str | None, default=None
            Display name of the Brownian diffusion component.

        Raises
        ------
        TypeError
            If component_display_name is not a string. If component_name is not a string.

        Returns
        -------
        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).
        """
        Q = _validate_and_convert_Q(Q)

        if not isinstance(component_name, str):
            raise TypeError('component_name must be a string.')

        if component_display_name is None:
            component_display_name = component_name

        if not isinstance(component_display_name, str):
            raise TypeError('component_display_name must be a string.')

        component_collection_list = [None] * len(Q)
        # In more complex models, this is used to scale the area of the
        # Lorentzians and the delta function.
        QISF = self.calculate_QISF(Q)

        # Create a Lorentzian component for each Q-value, with
        # width D*Q^2 and area equal to scale.
        # No delta function, as the EISF is 0.
        for i, Q_value in enumerate(Q):
            component_collection_list[i] = ComponentCollection(
                name=f'{self.name}_Q{Q_value:.2f}',
                display_name=f'{self.display_name}_Q{Q_value:.2f}',
                unit=self.unit,
            )

            lorentzian_component = Lorentzian(
                name=component_name,
                display_name=component_display_name,
                unit=self.unit,
            )

            # Make the width dependent on Q
            dependency_expression = self._write_width_dependency_expression(Q[i])
            dependency_map = self._write_width_dependency_map_expression()

            lorentzian_component.width.make_dependent_on(
                dependency_expression=dependency_expression,
                dependency_map=dependency_map,
                desired_unit=self.unit,
            )

            # Make the area dependent on Q
            area_dependency_map = self._write_area_dependency_map_expression()
            lorentzian_component.area.make_dependent_on(
                dependency_expression=self._write_area_dependency_expression(QISF[i]),
                dependency_map=area_dependency_map,
            )

            component_collection_list[i].append_component(lorentzian_component)

        return component_collection_list

    # ------------------------------------------------------------------
    # Private methods
    # ------------------------------------------------------------------

    def _write_width_dependency_expression(self, Q: float) -> str:
        """
        Write the dependency expression for the width as a function of Q to make dependent
        Parameters.

        Parameters
        ----------
        Q : float
            Scattering vector in 1/angstrom.

        Raises
        ------
        TypeError
            If Q is not a float.

        Returns
        -------
        str
            Dependency expression for the width.
        """
        if not isinstance(Q, (float)):
            raise TypeError('Q must be a float.')

        # Q is given as a float, so we need to add the units
        return f'hbar * D* {Q} **2*1/(angstrom**2)'

    def _write_width_dependency_map_expression(self) -> dict[str, DescriptorNumber]:
        """
        Write the dependency map expression to make dependent Parameters.

        Returns
        -------
        dict[str, DescriptorNumber]
            Dependency map for the width.
        """
        return {
            'D': self.diffusion_coefficient,
            'hbar': self._hbar,
            'angstrom': self._angstrom,
        }

    def _write_area_dependency_expression(self, QISF: float) -> str:
        """
        Write the dependency expression for the area to make dependent Parameters.

        Parameters
        ----------
        QISF : float
            Quasielastic Incoherent Scattering Function.

        Raises
        ------
        TypeError
            If QISF is not a float.

        Returns
        -------
        str
            Dependency expression for the area.
        """
        if not isinstance(QISF, (float)):
            raise TypeError('QISF must be a float.')

        return f'{QISF} * scale'

    def _write_area_dependency_map_expression(self) -> dict[str, DescriptorNumber]:
        """
        Write the dependency map expression to make dependent Parameters.

        Returns
        -------
        dict[str, DescriptorNumber]
            Dependency map for the area.
        """
        return {
            'scale': self.scale,
        }

    # ------------------------------------------------------------------
    # dunder methods
    # ------------------------------------------------------------------

    def __repr__(self) -> str:
        """
        String representation of the BrownianTranslationalDiffusion model.

        Returns
        -------
        str
            String representation of the BrownianTranslationalDiffusion model.
        """
        return (
            f'BrownianTranslationalDiffusion(name={self.name}, '
            f'display_name={self.display_name}, \n'
            f'    diffusion_coefficient={self.diffusion_coefficient}, \n'
            f'    scale={self.scale})'
        )

diffusion_coefficient property writable

Get the diffusion coefficient parameter D.

Returns:

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

__init__(scale=1.0, diffusion_coefficient=1.0, unit='meV', name='BrownianTranslationalDiffusion', display_name='BrownianTranslationalDiffusion', unique_name=None)

Initialize a new BrownianTranslationalDiffusion model.

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
unit	str | sc.Unit	Unit of the diffusion model. Must be convertible to meV.	'meV'
name	str	Name of the diffusion model.	'BrownianTranslationalDiffusion'
display_name	str | None	Display name of the diffusion model.	'BrownianTranslationalDiffusion'
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.

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def __init__(
    self,
    scale: Numeric = 1.0,
    diffusion_coefficient: Numeric = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'BrownianTranslationalDiffusion',
    display_name: str | None = 'BrownianTranslationalDiffusion',
    unique_name: str | None = None,
) -> None:
    """
    Initialize a new BrownianTranslationalDiffusion model.

    Parameters
    ----------
    scale : Numeric, default=1.0
        Scale factor for the diffusion model. Must be a non-negative number.
    diffusion_coefficient : Numeric, default=1.0
        Diffusion coefficient D in m^2/s.
    unit : str | sc.Unit, default='meV'
        Unit of the diffusion model. Must be convertible to meV.
    name : str, default='BrownianTranslationalDiffusion'
        Name of the diffusion model.
    display_name : str | None, default='BrownianTranslationalDiffusion'
        Display name of the diffusion model.
    unique_name : str | None, default=None
        Unique name of the diffusion model. If None, a unique name will be generated. By
        default, None.

    Raises
    ------
    TypeError
        If scale or diffusion_coefficient is not a number.
    """
    if not isinstance(scale, Numeric):
        raise TypeError('scale must be a number.')

    if not isinstance(diffusion_coefficient, Numeric):
        raise TypeError('diffusion_coefficient must be a number.')

    diffusion_coefficient = Parameter(
        name='diffusion_coefficient',
        value=float(diffusion_coefficient),
        fixed=False,
        unit='m**2/s',
        min=0.0,
    )
    super().__init__(
        unit=unit,
        scale=scale,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )
    self._hbar = hbar
    self._angstrom = angstrom
    self._diffusion_coefficient = diffusion_coefficient

calculate_width(Q)

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

Parameters:

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

Returns:

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

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def calculate_width(self, Q: Q_type) -> np.ndarray:
    """
    Calculate the half-width at half-maximum (HWHM) for the diffusion model.

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom.

    Returns
    -------
    np.ndarray
        HWHM values in the unit of the model (e.g., meV).
    """

    Q = _validate_and_convert_Q(Q)

    unit_conversion_factor = self._hbar * self.diffusion_coefficient / (self._angstrom**2)
    unit_conversion_factor.convert_unit(self.unit)
    return Q**2 * unit_conversion_factor.value

calculate_EISF(Q)

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

Parameters:

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

Returns:

Type	Description
np.ndarray	EISF values (dimensionless).

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def calculate_EISF(self, Q: Q_type) -> np.ndarray:
    """
    Calculate the Elastic Incoherent Structure Factor (EISF) for the Brownian translational
    diffusion model.

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom.

    Returns
    -------
    np.ndarray
        EISF values (dimensionless).
    """
    Q = _validate_and_convert_Q(Q)
    return np.zeros_like(Q)

calculate_QISF(Q)

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

Parameters:

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

Returns:

Type	Description
np.ndarray	QISF values (dimensionless).

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def calculate_QISF(self, Q: Q_type) -> np.ndarray:
    """
    Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom.

    Returns
    -------
    np.ndarray
        QISF values (dimensionless).
    """

    Q = _validate_and_convert_Q(Q)
    return np.ones_like(Q)

create_component_collections(Q, component_name='Brownian diffusion', component_display_name=None)

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

Parameters:

Name	Type	Description	Default
Q	Q_type	Scattering vector values.	required
component_name	str	Name of the Brownian diffusion component.	'Brownian diffusion'
component_display_name	str | None	Display name of the Brownian diffusion component.	None

Raises:

Type	Description
TypeError	If component_display_name is not a string. If component_name is not a string.

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).

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def create_component_collections(
    self,
    Q: Q_type,
    component_name: str = 'Brownian diffusion',
    component_display_name: str | None = None,
) -> list[ComponentCollection]:
    r"""
    Create ComponentCollection components for the Brownian translational diffusion model at
    given Q values.

    Parameters
    ----------
    Q : Q_type
        Scattering vector values.
    component_name : str, default='Brownian diffusion'
        Name of the Brownian diffusion component.
    component_display_name : str | None, default=None
        Display name of the Brownian diffusion component.

    Raises
    ------
    TypeError
        If component_display_name is not a string. If component_name is not a string.

    Returns
    -------
    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).
    """
    Q = _validate_and_convert_Q(Q)

    if not isinstance(component_name, str):
        raise TypeError('component_name must be a string.')

    if component_display_name is None:
        component_display_name = component_name

    if not isinstance(component_display_name, str):
        raise TypeError('component_display_name must be a string.')

    component_collection_list = [None] * len(Q)
    # In more complex models, this is used to scale the area of the
    # Lorentzians and the delta function.
    QISF = self.calculate_QISF(Q)

    # Create a Lorentzian component for each Q-value, with
    # width D*Q^2 and area equal to scale.
    # No delta function, as the EISF is 0.
    for i, Q_value in enumerate(Q):
        component_collection_list[i] = ComponentCollection(
            name=f'{self.name}_Q{Q_value:.2f}',
            display_name=f'{self.display_name}_Q{Q_value:.2f}',
            unit=self.unit,
        )

        lorentzian_component = Lorentzian(
            name=component_name,
            display_name=component_display_name,
            unit=self.unit,
        )

        # Make the width dependent on Q
        dependency_expression = self._write_width_dependency_expression(Q[i])
        dependency_map = self._write_width_dependency_map_expression()

        lorentzian_component.width.make_dependent_on(
            dependency_expression=dependency_expression,
            dependency_map=dependency_map,
            desired_unit=self.unit,
        )

        # Make the area dependent on Q
        area_dependency_map = self._write_area_dependency_map_expression()
        lorentzian_component.area.make_dependent_on(
            dependency_expression=self._write_area_dependency_expression(QISF[i]),
            dependency_map=area_dependency_map,
        )

        component_collection_list[i].append_component(lorentzian_component)

    return component_collection_list

__repr__()

String representation of the BrownianTranslationalDiffusion model.

Returns:

Type	Description
str	String representation of the BrownianTranslationalDiffusion model.

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def __repr__(self) -> str:
    """
    String representation of the BrownianTranslationalDiffusion model.

    Returns
    -------
    str
        String representation of the BrownianTranslationalDiffusion model.
    """
    return (
        f'BrownianTranslationalDiffusion(name={self.name}, '
        f'display_name={self.display_name}, \n'
        f'    diffusion_coefficient={self.diffusion_coefficient}, \n'
        f'    scale={self.scale})'
    )

InstrumentModel

Bases: NewBase

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.

Source code in src/easydynamics/sample_model/instrument_model.py

class InstrumentModel(NewBase):
    """
    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.
    """

    def __init__(
        self,
        display_name: str = 'MyInstrumentModel',
        unique_name: str | None = None,
        Q: Q_type | None = None,
        resolution_model: ResolutionModel | None = None,
        background_model: BackgroundModel | None = None,
        energy_offset: Numeric | None = None,
        unit: str | sc.Unit = 'meV',
    ) -> None:
        """
        Initialize an InstrumentModel.

        Parameters
        ----------
        display_name : str, default='MyInstrumentModel'
            The display name of the InstrumentModel.
        unique_name : str | None, default=None
            The unique name of the InstrumentModel.
        Q : Q_type | None, default=None
            The Q values where the instrument is modelled.
        resolution_model : ResolutionModel | None, default=None
            The resolution model of the instrument. If None, an empty resolution model is created
            and no resolution convolution is carried out.
        background_model : BackgroundModel | None, default=None
            The background model of the instrument. If None, an empty background model is created,
            and the background evaluates to 0.
        energy_offset : Numeric | None, default=None
            Template energy offset of the instrument. Will be copied to each Q value. If None, the
            energy offset will be 0.
        unit : str | sc.Unit, default='meV'
            The unit of the energy axis.

        Raises
        ------
        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.
        """
        super().__init__(
            display_name=display_name,
            unique_name=unique_name,
        )

        self._unit = _validate_unit(unit)

        if resolution_model is None:
            self._resolution_model = ResolutionModel()
        else:
            if not isinstance(resolution_model, ResolutionModel):
                raise TypeError(
                    f'resolution_model must be a ResolutionModel or None, '
                    f'got {type(resolution_model).__name__}'
                )
            self._resolution_model = resolution_model

        if background_model is None:
            self._background_model = BackgroundModel()
        else:
            if not isinstance(background_model, BackgroundModel):
                raise TypeError(
                    f'background_model must be a BackgroundModel or None, '
                    f'got {type(background_model).__name__}'
                )
            self._background_model = background_model

        if energy_offset is None:
            energy_offset = 0.0

        if not isinstance(energy_offset, Numeric):
            raise TypeError('energy_offset must be a number or None')

        self._energy_offset = Parameter(
            name='energy_offset',
            value=float(energy_offset),
            unit=self.unit,
            fixed=False,
        )
        self._Q = _validate_and_convert_Q(Q)
        self._on_Q_change()

    # -------------------------------------------------------------
    # Properties
    # -------------------------------------------------------------

    @property
    def resolution_model(self) -> ResolutionModel:
        """
        Get the resolution model of the instrument.

        Returns
        -------
        ResolutionModel
            The resolution model of the instrument.
        """
        return self._resolution_model

    @resolution_model.setter
    def resolution_model(self, value: ResolutionModel) -> None:
        """
        Set the resolution model of the instrument.

        Parameters
        ----------
        value : ResolutionModel
            The new resolution model of the instrument.

        Raises
        ------
        TypeError
            If value is not a ResolutionModel.
        """
        if not isinstance(value, ResolutionModel):
            raise TypeError(
                f'resolution_model must be a ResolutionModel, got {type(value).__name__}'
            )
        self._resolution_model = value
        self._on_resolution_model_change()

    @property
    def background_model(self) -> BackgroundModel:
        """
        Get the background model of the instrument.

        Returns
        -------
        BackgroundModel
            The background model of the instrument.
        """

        return self._background_model

    @background_model.setter
    def background_model(self, value: BackgroundModel) -> None:
        """
        Set the background model of the instrument.

        Parameters
        ----------
        value : BackgroundModel
            The new background model of the instrument.

        Raises
        ------
        TypeError
            If value is not a BackgroundModel.
        """

        if not isinstance(value, BackgroundModel):
            raise TypeError(
                f'background_model must be a BackgroundModel, got {type(value).__name__}'
            )
        self._background_model = value
        self._on_background_model_change()

    @property
    def Q(self) -> np.ndarray | None:
        """
        Get the Q values of the InstrumentModel.

        Returns
        -------
        np.ndarray | None
            The Q values of the InstrumentModel, or None if not set.
        """
        return self._Q

    @Q.setter
    def Q(self, value: Q_type | None) -> None:
        """
        Set the Q values of the InstrumentModel.

        If Q is already set, it raises an error if the new Q values are not similar to the old ones
        to prevent accidental changes to the background and resolution models. To change Q values,
        first run clear_Q().

        Parameters
        ----------
        value : Q_type | None
            The new Q values to set. If None, Q values are not changed.

        Raises
        ------
        ValueError
            If the new Q values are not similar to the old ones when Q is not None.
        """
        if value is None:
            return
        old_Q = self._Q
        new_Q = _validate_and_convert_Q(value)

        if old_Q is None:
            self._Q = new_Q
            self._on_Q_change()
            return

        if len(old_Q) != len(new_Q) or not np.allclose(old_Q, new_Q):
            raise ValueError(
                'New Q values are not similar to the old ones. '
                'To change Q values, first run clear_Q().'
            )

    @property
    def unit(self) -> str | sc.Unit:
        """
        Get the unit of the InstrumentModel.

        Returns
        -------
        str | sc.Unit
            The unit of the InstrumentModel.
        """
        return self._unit

    @unit.setter
    def unit(self, _unit_str: str) -> None:
        """
        Set the unit of the InstrumentModel.

        The unit is read-only and cannot be set directly. Use convert_unit to change the unit
        between allowed types or create a new InstrumentModel with the desired unit.

        Parameters
        ----------
        _unit_str : str
            The new unit for the InstrumentModel (ignored).

        Raises
        ------
        AttributeError
            Always, as the unit is read-only.
        """
        raise AttributeError(
            f'Unit is read-only. Use convert_unit to change the unit between allowed types '
            f'or create a new {self.__class__.__name__} with the desired unit.'
        )

    @property
    def energy_offset(self) -> Parameter:
        """
        Get the energy offset template parameter of the instrument model.

        Returns
        -------
        Parameter
            The energy offset template parameter of the instrument model.
        """
        return self._energy_offset

    @energy_offset.setter
    def energy_offset(self, value: Numeric) -> None:
        """
        Set the offset parameter of the instrument model.

        Parameters
        ----------
        value : Numeric
            The new value for the energy offset parameter. Will be copied to all Q values.

        Raises
        ------
        TypeError
            If value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError(f'energy_offset must be a number, got {type(value).__name__}')
        self._energy_offset.value = value

        self._on_energy_offset_change()

    # --------------------------------------------------------------
    # Other methods
    # --------------------------------------------------------------

    def clear_Q(self, confirm: bool = False) -> None:
        """
        Clear the Q values of the InstrumentModel and any associated ResolutionModel and
        BackgroundModel, removing all component collections and their associated Parameters.

        Parameters
        ----------
        confirm : bool, default=False
            Confirmation to clear Q values.

        Raises
        ------
        ValueError
            If confirm is not True.
        """
        if not confirm:
            raise ValueError(
                'Clearing Q values requires confirmation. Set confirm=True to proceed.'
            )
        self._Q = None
        self.background_model.clear_Q(confirm=True)
        self.resolution_model.clear_Q(confirm=True)
        self._on_Q_change()

    def convert_unit(self, unit_str: str | sc.Unit) -> None:
        """
        Convert the unit of the InstrumentModel.

        Parameters
        ----------
        unit_str : str | sc.Unit
            The unit to convert to.

        Raises
        ------
        ValueError
            If unit_str is not a valid unit string or scipp Unit.
        """
        unit = _validate_unit(unit_str)
        if unit is None:
            raise ValueError('unit_str must be a valid unit string or scipp Unit')

        self._background_model.convert_unit(unit)
        self._resolution_model.convert_unit(unit)
        self._energy_offset.convert_unit(unit)
        for offset in self._energy_offsets:
            offset.convert_unit(unit)

        self._unit = unit

    def get_all_variables(self, Q_index: int | None = None) -> list[Parameter]:
        """
        Get all variables in the InstrumentModel.

        Parameters
        ----------
        Q_index : int | None, default=None
            The index of the Q value to get variables for. If None, get variables for all Q values.


        Raises
        ------
        TypeError
            If Q_index is not an int or None.
        IndexError
            If Q_index is out of bounds for the Q values in the InstrumentModel.

        Returns
        -------
        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.
        """
        if self._Q is None:
            return []

        if Q_index is None:
            variables = [self._energy_offsets[i] for i in range(len(self._Q))]
        else:
            if not isinstance(Q_index, int):
                raise TypeError(f'Q_index must be an int or None, got {type(Q_index).__name__}')
            if Q_index < 0 or Q_index >= len(self._Q):
                raise IndexError(
                    f'Q_index {Q_index} is out of bounds for Q of length {len(self._Q)}'
                )
            variables = [self._energy_offsets[Q_index]]

        variables.extend(self._background_model.get_all_variables(Q_index=Q_index))
        variables.extend(self._resolution_model.get_all_variables(Q_index=Q_index))

        return variables

    def fix_resolution_parameters(self) -> None:
        """Fix all parameters in the resolution model."""
        self.resolution_model.fix_all_parameters()

    def free_resolution_parameters(self) -> None:
        """Free all parameters in the resolution model."""
        self.resolution_model.free_all_parameters()

    def normalize_resolution(self) -> None:
        """Normalize the resolution model to have area 1."""
        self.resolution_model.normalize_area()

    def get_energy_offset(
        self,
        Q_index: int | None = None,
    ) -> Parameter | list[Parameter]:
        """
        Get the energy offset Parameter at a specific Q index.

        Parameters
        ----------
        Q_index : int | None, default=None
            The index of the Q value to get the energy offset for. If None, get the energy offset
            for all Q values.

        Raises
        ------
        ValueError
            If no Q values are set in the InstrumentModel.
        IndexError
            If Q_index is out of bounds.
        TypeError
            If Q_index is not an int or None.

        Returns
        -------
        Parameter | list[Parameter]
            The energy offset Parameter at the specified Q index, or a list of Parameters if
            Q_index is None.
        """
        if self._Q is None:
            raise ValueError('No Q values are set in the InstrumentModel.')

        if Q_index is None:
            return self._energy_offsets

        if not isinstance(Q_index, int):
            raise TypeError(f'Q_index must be an int or None, got {type(Q_index).__name__}')

        if Q_index < 0 or Q_index >= len(self._Q):
            raise IndexError(f'Q_index {Q_index} is out of bounds for Q of length {len(self._Q)}')

        return self._energy_offsets[Q_index]

    def fix_energy_offset(self, Q_index: int | None = None) -> 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
        ----------
        Q_index : int | None, default=None
            The index of the Q value to fix the energy offset for. If None, fix energy offsets for
            all Q values.
        """
        self._fix_or_free_energy_offset(Q_index, fixed=True)

    def free_energy_offset(self, Q_index: int | None = None) -> 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
        ----------
        Q_index : int | None, default=None
            The index of the Q value to free the energy offset for. If None, free energy offsets
            for all Q values.
        """
        self._fix_or_free_energy_offset(Q_index, fixed=False)

    # --------------------------------------------------------------
    # Private methods
    # --------------------------------------------------------------
    def _fix_or_free_energy_offset(self, Q_index: int | None = None, fixed: bool = True) -> None:
        """
        Fix or free energy offset parameters.

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

        Parameters
        ----------
        Q_index : int | None, default=None
            The index of the Q value to fix or free the energy offset for. If None, fix or free
            energy offsets for all Q values.
        fixed : bool, default=True
            Whether to fix (True) or free (False) the energy offset.

        Raises
        ------
        TypeError
            If Q_index is not an int or None.
        IndexError
            If Q_index is out of bounds for the Q values in the InstrumentModel.
        """

        if Q_index is None:
            for offset in self._energy_offsets:
                offset.fixed = fixed
        else:
            if not isinstance(Q_index, int):
                raise TypeError(f'Q_index must be an int or None, got {type(Q_index).__name__}')

            if Q_index < 0 or Q_index >= len(self._Q):
                raise IndexError(
                    f'Q_index {Q_index} is out of bounds for Q of length {len(self._Q)}'
                )
            self._energy_offsets[Q_index].fixed = fixed

    def _generate_energy_offsets(self) -> None:
        """Generate energy offset Parameters for each Q value."""
        if self._Q is None:
            self._energy_offsets = []
            return

        self._energy_offsets = [copy(self._energy_offset) for _ in self._Q]

    def _on_Q_change(self) -> None:
        """Handle changes to the Q values."""
        self._generate_energy_offsets()
        self.resolution_model.Q = self.Q
        self.background_model.Q = self.Q

    def _on_energy_offset_change(self) -> None:
        """Handle changes to the energy offset."""
        for offset in self._energy_offsets:
            offset.value = self._energy_offset.value

    def _on_resolution_model_change(self) -> None:
        """Handle changes to the resolution model."""
        self.resolution_model.Q = self.Q

    def _on_background_model_change(self) -> None:
        """Handle changes to the background model."""
        self.background_model.Q = self.Q

    # -------------------------------------------------------------
    # Dunder methods
    # -------------------------------------------------------------

    def __repr__(self) -> str:
        """
        Return a string representation of the InstrumentModel.

        Returns
        -------
        str
            A string representation of the InstrumentModel.
        """

        return (
            f'{self.__class__.__name__}('
            f'unique_name={self.unique_name!r}, '
            f'unit={self.unit}, '
            f'Q_len={None if self._Q is None else len(self._Q)}, '
            f'resolution_model={self._resolution_model!r}, '
            f'background_model={self._background_model!r}'
            f')'
        )

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
np.ndarray | None	The Q values of the InstrumentModel, or None if not set.

unit property writable

Get the unit of the InstrumentModel.

Returns:

Type	Description
str | sc.Unit	The unit of the InstrumentModel.

energy_offset property writable

Get the energy offset template parameter of the instrument model.

Returns:

Type	Description
Parameter	The energy offset template parameter of the instrument model.

__init__(display_name='MyInstrumentModel', unique_name=None, Q=None, resolution_model=None, background_model=None, energy_offset=None, unit='meV')

Initialize an InstrumentModel.

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 | None	The resolution model of the instrument. 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
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.

Source code in src/easydynamics/sample_model/instrument_model.py

def __init__(
    self,
    display_name: str = 'MyInstrumentModel',
    unique_name: str | None = None,
    Q: Q_type | None = None,
    resolution_model: ResolutionModel | None = None,
    background_model: BackgroundModel | None = None,
    energy_offset: Numeric | None = None,
    unit: str | sc.Unit = 'meV',
) -> None:
    """
    Initialize an InstrumentModel.

    Parameters
    ----------
    display_name : str, default='MyInstrumentModel'
        The display name of the InstrumentModel.
    unique_name : str | None, default=None
        The unique name of the InstrumentModel.
    Q : Q_type | None, default=None
        The Q values where the instrument is modelled.
    resolution_model : ResolutionModel | None, default=None
        The resolution model of the instrument. If None, an empty resolution model is created
        and no resolution convolution is carried out.
    background_model : BackgroundModel | None, default=None
        The background model of the instrument. If None, an empty background model is created,
        and the background evaluates to 0.
    energy_offset : Numeric | None, default=None
        Template energy offset of the instrument. Will be copied to each Q value. If None, the
        energy offset will be 0.
    unit : str | sc.Unit, default='meV'
        The unit of the energy axis.

    Raises
    ------
    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.
    """
    super().__init__(
        display_name=display_name,
        unique_name=unique_name,
    )

    self._unit = _validate_unit(unit)

    if resolution_model is None:
        self._resolution_model = ResolutionModel()
    else:
        if not isinstance(resolution_model, ResolutionModel):
            raise TypeError(
                f'resolution_model must be a ResolutionModel or None, '
                f'got {type(resolution_model).__name__}'
            )
        self._resolution_model = resolution_model

    if background_model is None:
        self._background_model = BackgroundModel()
    else:
        if not isinstance(background_model, BackgroundModel):
            raise TypeError(
                f'background_model must be a BackgroundModel or None, '
                f'got {type(background_model).__name__}'
            )
        self._background_model = background_model

    if energy_offset is None:
        energy_offset = 0.0

    if not isinstance(energy_offset, Numeric):
        raise TypeError('energy_offset must be a number or None')

    self._energy_offset = Parameter(
        name='energy_offset',
        value=float(energy_offset),
        unit=self.unit,
        fixed=False,
    )
    self._Q = _validate_and_convert_Q(Q)
    self._on_Q_change()

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.

Source code in src/easydynamics/sample_model/instrument_model.py

def clear_Q(self, confirm: bool = False) -> None:
    """
    Clear the Q values of the InstrumentModel and any associated ResolutionModel and
    BackgroundModel, removing all component collections and their associated Parameters.

    Parameters
    ----------
    confirm : bool, default=False
        Confirmation to clear Q values.

    Raises
    ------
    ValueError
        If confirm is not True.
    """
    if not confirm:
        raise ValueError(
            'Clearing Q values requires confirmation. Set confirm=True to proceed.'
        )
    self._Q = None
    self.background_model.clear_Q(confirm=True)
    self.resolution_model.clear_Q(confirm=True)
    self._on_Q_change()

convert_unit(unit_str)

Convert the unit of the InstrumentModel.

Parameters:

Name	Type	Description	Default
unit_str	str | sc.Unit	The unit to convert to.	required

Raises:

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

Source code in src/easydynamics/sample_model/instrument_model.py

def convert_unit(self, unit_str: str | sc.Unit) -> None:
    """
    Convert the unit of the InstrumentModel.

    Parameters
    ----------
    unit_str : str | sc.Unit
        The unit to convert to.

    Raises
    ------
    ValueError
        If unit_str is not a valid unit string or scipp Unit.
    """
    unit = _validate_unit(unit_str)
    if unit is None:
        raise ValueError('unit_str must be a valid unit string or scipp Unit')

    self._background_model.convert_unit(unit)
    self._resolution_model.convert_unit(unit)
    self._energy_offset.convert_unit(unit)
    for offset in self._energy_offsets:
        offset.convert_unit(unit)

    self._unit = 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

Raises:

Type	Description
TypeError	If Q_index is not an int or None.
IndexError	If Q_index is out of bounds for the Q values in the InstrumentModel.

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.

Source code in src/easydynamics/sample_model/instrument_model.py

def get_all_variables(self, Q_index: int | None = None) -> list[Parameter]:
    """
    Get all variables in the InstrumentModel.

    Parameters
    ----------
    Q_index : int | None, default=None
        The index of the Q value to get variables for. If None, get variables for all Q values.


    Raises
    ------
    TypeError
        If Q_index is not an int or None.
    IndexError
        If Q_index is out of bounds for the Q values in the InstrumentModel.

    Returns
    -------
    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.
    """
    if self._Q is None:
        return []

    if Q_index is None:
        variables = [self._energy_offsets[i] for i in range(len(self._Q))]
    else:
        if not isinstance(Q_index, int):
            raise TypeError(f'Q_index must be an int or None, got {type(Q_index).__name__}')
        if Q_index < 0 or Q_index >= len(self._Q):
            raise IndexError(
                f'Q_index {Q_index} is out of bounds for Q of length {len(self._Q)}'
            )
        variables = [self._energy_offsets[Q_index]]

    variables.extend(self._background_model.get_all_variables(Q_index=Q_index))
    variables.extend(self._resolution_model.get_all_variables(Q_index=Q_index))

    return variables

fix_resolution_parameters()

Fix all parameters in the resolution model.

Source code in src/easydynamics/sample_model/instrument_model.py

def fix_resolution_parameters(self) -> None:
    """Fix all parameters in the resolution model."""
    self.resolution_model.fix_all_parameters()

free_resolution_parameters()

Free all parameters in the resolution model.

Source code in src/easydynamics/sample_model/instrument_model.py

def free_resolution_parameters(self) -> None:
    """Free all parameters in the resolution model."""
    self.resolution_model.free_all_parameters()

normalize_resolution()

Normalize the resolution model to have area 1.

Source code in src/easydynamics/sample_model/instrument_model.py

def normalize_resolution(self) -> None:
    """Normalize the resolution model to have area 1."""
    self.resolution_model.normalize_area()

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.
IndexError	If Q_index is out of bounds.
TypeError	If Q_index is not an int or None.

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.

Source code in src/easydynamics/sample_model/instrument_model.py

def get_energy_offset(
    self,
    Q_index: int | None = None,
) -> Parameter | list[Parameter]:
    """
    Get the energy offset Parameter at a specific Q index.

    Parameters
    ----------
    Q_index : int | None, default=None
        The index of the Q value to get the energy offset for. If None, get the energy offset
        for all Q values.

    Raises
    ------
    ValueError
        If no Q values are set in the InstrumentModel.
    IndexError
        If Q_index is out of bounds.
    TypeError
        If Q_index is not an int or None.

    Returns
    -------
    Parameter | list[Parameter]
        The energy offset Parameter at the specified Q index, or a list of Parameters if
        Q_index is None.
    """
    if self._Q is None:
        raise ValueError('No Q values are set in the InstrumentModel.')

    if Q_index is None:
        return self._energy_offsets

    if not isinstance(Q_index, int):
        raise TypeError(f'Q_index must be an int or None, got {type(Q_index).__name__}')

    if Q_index < 0 or Q_index >= len(self._Q):
        raise IndexError(f'Q_index {Q_index} is out of bounds for Q of length {len(self._Q)}')

    return self._energy_offsets[Q_index]

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

Source code in src/easydynamics/sample_model/instrument_model.py

def fix_energy_offset(self, Q_index: int | None = None) -> 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
    ----------
    Q_index : int | None, default=None
        The index of the Q value to fix the energy offset for. If None, fix energy offsets for
        all Q values.
    """
    self._fix_or_free_energy_offset(Q_index, fixed=True)

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

Source code in src/easydynamics/sample_model/instrument_model.py

def free_energy_offset(self, Q_index: int | None = None) -> 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
    ----------
    Q_index : int | None, default=None
        The index of the Q value to free the energy offset for. If None, free energy offsets
        for all Q values.
    """
    self._fix_or_free_energy_offset(Q_index, fixed=False)

__repr__()

Return a string representation of the InstrumentModel.

Returns:

Type	Description
str	A string representation of the InstrumentModel.

Source code in src/easydynamics/sample_model/instrument_model.py

def __repr__(self) -> str:
    """
    Return a string representation of the InstrumentModel.

    Returns
    -------
    str
        A string representation of the InstrumentModel.
    """

    return (
        f'{self.__class__.__name__}('
        f'unique_name={self.unique_name!r}, '
        f'unit={self.unit}, '
        f'Q_len={None if self._Q is None else len(self._Q)}, '
        f'resolution_model={self._resolution_model!r}, '
        f'background_model={self._background_model!r}'
        f')'
    )

ResolutionModel

Bases: ModelBase

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

Source code in src/easydynamics/sample_model/resolution_model.py

class ResolutionModel(ModelBase):
    """
    ResolutionModel represents a model of the instrment resolution in an experiment at various Q.
    """

    def __init__(
        self,
        display_name: str = 'MyResolutionModel',
        unique_name: str | None = None,
        unit: str | sc.Unit = 'meV',
        components: ModelComponent | ComponentCollection | None = None,
        Q: Q_type | None = None,
    ) -> None:
        """
        Initialize a ResolutionModel.

        Parameters
        ----------
        display_name : str, default='MyResolutionModel'
            Display name of the model.
        unique_name : str | None, default=None
            Unique name of the model. If None, a unique name will be generated.
        unit : str | sc.Unit, default='meV'
            Unit of the model.
        components : ModelComponent | ComponentCollection | None, default=None
            Template components of the model. If None, no components are added. These components
            are copied into ComponentCollections for each Q value.
        Q : Q_type | None, default=None
            Q values for the model. If None, Q is not set.
        """

        super().__init__(
            display_name=display_name,
            unique_name=unique_name,
            unit=unit,
            components=components,
            Q=Q,
        )

    def append_component(self, component: ModelComponent | ComponentCollection) -> None:
        """
        Append a component to the ResolutionModel.

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

        Parameters
        ----------
        component : ModelComponent | ComponentCollection
            Component(s) to append.

        Raises
        ------
        TypeError
            If the component is a DeltaFunction or Polynomial.
        """
        components = component if isinstance(component, ComponentCollection) else (component,)

        for comp in components:
            if isinstance(comp, (DeltaFunction, Polynomial)):
                raise TypeError(
                    f'Component in ResolutionModel cannot be a {comp.__class__.__name__}'
                )

        super().append_component(component)

__init__(display_name='MyResolutionModel', unique_name=None, unit='meV', components=None, Q=None)

Initialize a ResolutionModel.

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
unit	str | sc.Unit	Unit of the model.	'meV'
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

Source code in src/easydynamics/sample_model/resolution_model.py

def __init__(
    self,
    display_name: str = 'MyResolutionModel',
    unique_name: str | None = None,
    unit: str | sc.Unit = 'meV',
    components: ModelComponent | ComponentCollection | None = None,
    Q: Q_type | None = None,
) -> None:
    """
    Initialize a ResolutionModel.

    Parameters
    ----------
    display_name : str, default='MyResolutionModel'
        Display name of the model.
    unique_name : str | None, default=None
        Unique name of the model. If None, a unique name will be generated.
    unit : str | sc.Unit, default='meV'
        Unit of the model.
    components : ModelComponent | ComponentCollection | None, default=None
        Template components of the model. If None, no components are added. These components
        are copied into ComponentCollections for each Q value.
    Q : Q_type | None, default=None
        Q values for the model. If None, Q is not set.
    """

    super().__init__(
        display_name=display_name,
        unique_name=unique_name,
        unit=unit,
        components=components,
        Q=Q,
    )

append_component(component)

Append a component to the ResolutionModel.

Does not allow DeltaFunction or Polynomial 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 or Polynomial.

Source code in src/easydynamics/sample_model/resolution_model.py

def append_component(self, component: ModelComponent | ComponentCollection) -> None:
    """
    Append a component to the ResolutionModel.

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

    Parameters
    ----------
    component : ModelComponent | ComponentCollection
        Component(s) to append.

    Raises
    ------
    TypeError
        If the component is a DeltaFunction or Polynomial.
    """
    components = component if isinstance(component, ComponentCollection) else (component,)

    for comp in components:
        if isinstance(comp, (DeltaFunction, Polynomial)):
            raise TypeError(
                f'Component in ResolutionModel cannot be a {comp.__class__.__name__}'
            )

    super().append_component(component)

SampleModel

Bases: ModelBase

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.

Source code in src/easydynamics/sample_model/sample_model.py

class SampleModel(ModelBase):
    """
    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.
    """

    def __init__(
        self,
        display_name: str = 'MySampleModel',
        unique_name: str | None = None,
        unit: str | sc.Unit = 'meV',
        components: ModelComponent | ComponentCollection | None = None,
        Q: Q_type | None = None,
        diffusion_models: DiffusionModelBase | list[DiffusionModelBase] | None = None,
        temperature: float | None = None,
        temperature_unit: str | sc.Unit = 'K',
        detailed_balance_settings: DetailedBalanceSettings | None = None,
    ) -> None:
        """
        Initialize the SampleModel.

        Parameters
        ----------
        display_name : str, default='MySampleModel'
            Display name of the model.
        unique_name : str | None, default=None
            Unique name of the model. If None, a unique name will be generated.
        unit : str | sc.Unit, default='meV'
            Unit of the model. If None,.
        components : ModelComponent | ComponentCollection | None, default=None
            Template components of the model. If None, no components are added. These components
            are copied into ComponentCollections for each Q value.
        Q : Q_type | None, default=None
            Q values for the model. If None, Q is not set.
        diffusion_models : DiffusionModelBase | list[DiffusionModelBase] | None, default=None
            Diffusion models to include in the SampleModel. If None, no diffusion models are added.
        temperature : float | None, default=None
            Temperature for detailed balancing. If None, no detailed balancing is applied. By
            default, None.
        temperature_unit : str | sc.Unit, default='K'
            Unit of the temperature.
        detailed_balance_settings : DetailedBalanceSettings | None, default=None
            Settings for detailed balancing.

        Raises
        ------
        TypeError
            If diffusion_models is not a DiffusionModelBase, a list of DiffusionModelBase, or None,
            or if temperature is not a number or None, or if detailed_balance_settings is not a
            DetailedBalanceSettings instance.
        ValueError
            If temperature is negative.
        """
        if diffusion_models is None:
            self._diffusion_models = []
        elif isinstance(diffusion_models, DiffusionModelBase):
            self._diffusion_models = [diffusion_models]
        else:
            if not isinstance(diffusion_models, list) or not all(
                isinstance(dm, DiffusionModelBase) for dm in diffusion_models
            ):
                raise TypeError(
                    'diffusion_models must be a DiffusionModelBase, '
                    'a list of DiffusionModelBase or None'
                )
            self._diffusion_models = diffusion_models

        super().__init__(
            display_name=display_name,
            unique_name=unique_name,
            unit=unit,
            components=components,
            Q=Q,
        )

        if temperature is None:
            self._temperature = None
        else:
            if not isinstance(temperature, Numeric):
                raise TypeError('temperature must be a number or None')

            if temperature < 0:
                raise ValueError('temperature must be non-negative')
            self._temperature = Parameter(
                name='Temperature',
                value=temperature,
                unit=temperature_unit,
                display_name='Temperature',
                fixed=True,
            )
        self._temperature_unit = temperature_unit

        if detailed_balance_settings is None:
            self._detailed_balance_settings = DetailedBalanceSettings()
        elif isinstance(detailed_balance_settings, DetailedBalanceSettings):
            self._detailed_balance_settings = detailed_balance_settings
        else:
            raise TypeError('detailed_balance_settings must be a DetailedBalanceSettings or None')

    # ------------------------------------------------------------------
    # Component management
    # ------------------------------------------------------------------

    def append_diffusion_model(self, diffusion_model: DiffusionModelBase) -> None:
        """
        Append a DiffusionModel to the SampleModel.

        Parameters
        ----------
        diffusion_model : DiffusionModelBase
            The DiffusionModel to append.

        Raises
        ------
        TypeError
            If the diffusion_model is not a DiffusionModelBase.
        """

        if not isinstance(diffusion_model, DiffusionModelBase):
            raise TypeError(
                f'diffusion_model must be a DiffusionModelBase, got {type(diffusion_model).__name__}'  # noqa: E501
            )

        self._diffusion_models.append(diffusion_model)
        self._generate_component_collections()

    def remove_diffusion_model(self, name: str) -> None:
        """
        Remove a DiffusionModel from the SampleModel by name.

        Parameters
        ----------
        name : str
            The name of the DiffusionModel to remove.

        Raises
        ------
        ValueError
            If no DiffusionModel with the given name is found.
        """
        for i, dm in enumerate(self._diffusion_models):
            if dm.name == name:
                del self._diffusion_models[i]
                self._generate_component_collections()
                return
        raise ValueError(
            f'No DiffusionModel with name {name} found. \n'
            f'The available names are: {[dm.name for dm in self._diffusion_models]}'
        )

    def clear_diffusion_models(self) -> None:
        """Clear all DiffusionModels from the SampleModel."""
        self._diffusion_models.clear()
        self._generate_component_collections()

    # ------------------------------------------------------------------
    # Properties
    # ------------------------------------------------------------------

    @property
    def diffusion_models(self) -> list[DiffusionModelBase]:
        """
        Get the diffusion models of the SampleModel.

        Returns
        -------
        list[DiffusionModelBase]
            The diffusion models of the SampleModel.
        """
        return self._diffusion_models

    @diffusion_models.setter
    def diffusion_models(
        self, value: DiffusionModelBase | list[DiffusionModelBase] | None
    ) -> None:
        """
        Set the diffusion models of the SampleModel.

        Parameters
        ----------
        value : DiffusionModelBase | list[DiffusionModelBase] | None
            The diffusion model(s) to set. Can be a single DiffusionModelBase, a list of
            DiffusionModelBase, or None to clear all diffusion models.

        Raises
        ------
        TypeError
            If value is not a DiffusionModelBase, a list of DiffusionModelBase, or None.
        """

        if value is None:
            self._diffusion_models = []
            return
        if isinstance(value, DiffusionModelBase):
            self._diffusion_models = [value]
            return
        if not isinstance(value, list) or not all(
            isinstance(dm, DiffusionModelBase) for dm in value
        ):
            raise TypeError(
                'diffusion_models must be a DiffusionModelBase, a list of DiffusionModelBase, '
                'or None'
            )
        self._diffusion_models = value
        self._on_diffusion_models_change()

    @property
    def temperature(self) -> Parameter | None:
        """
        Get the temperature of the SampleModel.

        Returns
        -------
        Parameter | None
            The temperature Parameter of the SampleModel, or None if not set.
        """
        return self._temperature

    @temperature.setter
    def temperature(self, value: Numeric | None) -> None:
        """
        Set the temperature of the SampleModel.

        Parameters
        ----------
        value : Numeric | None
            The temperature value to set. Can be a number or None to unset the temperature.

        Raises
        ------
        TypeError
            If value is not a number or None.
        ValueError
            If value is negative.
        """
        if value is None:
            self._temperature = None
            return

        if not isinstance(value, Numeric):
            raise TypeError('temperature must be a number or None')

        if value < 0:
            raise ValueError('temperature must be non-negative')

        if self._temperature is None:
            self._temperature = Parameter(
                name='Temperature',
                value=value,
                unit=self._temperature_unit,
                display_name='Temperature',
                fixed=True,
            )
        else:
            self._temperature.value = value

    @property
    def temperature_unit(self) -> str | sc.Unit:
        """
        Get the temperature unit of the SampleModel.

        Returns
        -------
        str | sc.Unit
            The unit of the temperature Parameter.
        """
        return self._temperature_unit

    @temperature_unit.setter
    def temperature_unit(self, _value: str | sc.Unit) -> None:
        """
        The temperature unit of the SampleModel is read-only.

        Parameters
        ----------
        _value : str | sc.Unit
            The unit to set for the temperature Parameter.

        Raises
        ------
        AttributeError
            Always, as temperature_unit is read-only.
        """

        raise AttributeError(
            f'Temperature_unit is read-only. Use convert_temperature_unit to change the unit between allowed types '  # noqa: E501
            f'or create a new {self.__class__.__name__} with the desired unit.'
        )

    def convert_temperature_unit(self, unit: str | sc.Unit) -> None:
        """
        Convert the unit of the temperature Parameter.

        Parameters
        ----------
        unit : str | sc.Unit
            The unit to convert the temperature Parameter to.

        Raises
        ------
        ValueError
            If temperature is not set or conversion fails.
        Exception
            If the provided unit is invalid or cannot be converted.
        """

        if self.temperature is None:
            raise ValueError('Temperature is not set, cannot convert unit.')

        old_unit = self.temperature.unit

        try:
            self.temperature.convert_unit(unit)
            self._temperature_unit = unit
        except Exception:
            # Attempt to rollback on failure
            with suppress(Exception):
                self.temperature.convert_unit(old_unit)
            raise

    @property
    def normalize_detailed_balance(self) -> bool:
        """
        Get whether to divide the detailed balance factor by temperature.

        Returns
        -------
        bool
            True if the detailed balance factor is divided by temperature, False otherwise.
        """
        return self.detailed_balance_settings.normalize_detailed_balance

    @normalize_detailed_balance.setter
    def normalize_detailed_balance(self, value: bool) -> None:
        """
        Set whether to divide the detailed balance factor by temperature.

        Parameters
        ----------
        value : bool
            True to divide the detailed balance factor by temperature, False otherwise.

        Raises
        ------
        TypeError
            If value is not a bool.
        """
        if not isinstance(value, bool):
            raise TypeError('normalize_detailed_balance must be True or False')
        self.detailed_balance_settings.normalize_detailed_balance = value

    @property
    def use_detailed_balance(self) -> bool:
        """
        Get whether to apply detailed balance to the model.

        Returns
        -------
        bool
            True if detailed balance is applied, False otherwise.
        """
        return self.detailed_balance_settings.use_detailed_balance

    @use_detailed_balance.setter
    def use_detailed_balance(self, value: bool) -> None:
        """
        Set whether to apply detailed balance to the model.

        Parameters
        ----------
        value : bool
            True to apply detailed balance, False otherwise.

        Raises
        ------
        TypeError
            If value is not a bool.
        """
        if not isinstance(value, bool):
            raise TypeError('use_detailed_balance must be True or False')
        self.detailed_balance_settings.use_detailed_balance = value

    @property
    def detailed_balance_settings(self) -> DetailedBalanceSettings:
        """
        Get the DetailedBalanceSettings of the SampleModel.

        Returns
        -------
        DetailedBalanceSettings
            The DetailedBalanceSettings of the SampleModel.
        """
        return self._detailed_balance_settings

    @detailed_balance_settings.setter
    def detailed_balance_settings(self, value: DetailedBalanceSettings) -> None:
        """
        Set the DetailedBalanceSettings of the SampleModel.

        Parameters
        ----------
        value : DetailedBalanceSettings
            The DetailedBalanceSettings to set.

        Raises
        ------
        TypeError
            If value is not a DetailedBalanceSettings.
        """
        if not isinstance(value, DetailedBalanceSettings):
            raise TypeError('detailed_balance_settings must be a DetailedBalanceSettings')
        self._detailed_balance_settings = value

    # ------------------------------------------------------------------
    # Other methods
    # ------------------------------------------------------------------

    def evaluate(
        self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray
    ) -> list[np.ndarray]:
        """
        Evaluate the sample model at all Q for the given x values.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values to evaluate the model at. Can be a number, list, numpy array, scipp
            Variable, or scipp DataArray.

        Returns
        -------
        list[np.ndarray]
            List of evaluated model values for each Q.
        """

        y = super().evaluate(x)

        if self.temperature is not None and self.detailed_balance_settings.use_detailed_balance:
            DBF = detailed_balance_factor(
                energy=x,
                temperature=self.temperature,
                divide_by_temperature=self.detailed_balance_settings.normalize_detailed_balance,
                energy_unit=self.unit,
            )
            y = [yi * DBF for yi in y]

        return y

    def get_all_variables(self, Q_index: int | None = None) -> list[Parameter]:
        """
        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
        ----------
        Q_index : int | None, default=None
            If specified, only get variables from the ComponentCollection at the given Q index. If
            None, get variables from all ComponentCollections.

        Returns
        -------
        list[Parameter]
            List of all Parameters and Descriptors, including temperature if set and all variables
            from diffusion models.
        """

        all_vars = super().get_all_variables(Q_index=Q_index)
        if self.temperature is not None:
            all_vars.append(self.temperature)

        for diffusion_model in self._diffusion_models:
            all_vars.extend(diffusion_model.get_all_variables())

        return all_vars

    # ------------------------------------------------------------------
    # Private methods
    # ------------------------------------------------------------------

    def _generate_component_collections(self) -> None:
        """
        Generate ComponentCollections from the DiffusionModels for each Q and add the components
        from self._components.
        """
        super()._generate_component_collections()

        if self.Q is None:
            return
        # Generate components from diffusion models
        # and add to component collections
        for diffusion_model in self._diffusion_models:
            diffusion_collections = diffusion_model.create_component_collections(
                Q=self.Q,
                component_name=diffusion_model.name,
            )
            for target, source in zip(
                self._component_collections,
                diffusion_collections,
                strict=True,
            ):
                for component in source:
                    target.append_component(component)

    def _on_diffusion_models_change(self) -> None:
        """Handle changes to the diffusion models."""
        self._generate_component_collections()

    # ------------------------------------------------------------------
    # dunder methods
    # ------------------------------------------------------------------

    def __repr__(self) -> str:
        """
        Return a string representation of the SampleModel.

        Returns
        -------
        str
            A string representation of the SampleModel.
        """

        return (
            f'{self.__class__.__name__}(unique_name={self.unique_name}, unit={self.unit}), '
            f'Q = {self.Q}, \n '
            f'components = {self.components}, diffusion_models = {self.diffusion_models}, '
            f'temperature = {self.temperature}, '
            f'detailed_balance_settings = {self.detailed_balance_settings}'
        )

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 of the SampleModel.

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 to apply detailed balance to the model.

Returns:

Type	Description
bool	True if detailed balance is applied, False otherwise.

detailed_balance_settings property writable

Get the DetailedBalanceSettings of the SampleModel.

Returns:

Type	Description
DetailedBalanceSettings	The DetailedBalanceSettings of the SampleModel.

__init__(display_name='MySampleModel', unique_name=None, unit='meV', components=None, Q=None, diffusion_models=None, temperature=None, temperature_unit='K', detailed_balance_settings=None)

Initialize the SampleModel.

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
unit	str | sc.Unit	Unit of the model. If None,.	'meV'
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
diffusion_models	DiffusionModelBase | list[DiffusionModelBase] | None	Diffusion models to include in the SampleModel. If None, no diffusion models are added.	None
temperature	float | None	Temperature for detailed balancing. If None, no detailed balancing is applied. By default, None.	None
temperature_unit	str | sc.Unit	Unit of the temperature.	'K'
detailed_balance_settings	DetailedBalanceSettings | None	Settings for detailed balancing.	None

Raises:

Type	Description
TypeError	If diffusion_models is not a DiffusionModelBase, a list of DiffusionModelBase, or None, or if temperature is not a number or None, or if detailed_balance_settings is not a DetailedBalanceSettings instance.
ValueError	If temperature is negative.

Source code in src/easydynamics/sample_model/sample_model.py

def __init__(
    self,
    display_name: str = 'MySampleModel',
    unique_name: str | None = None,
    unit: str | sc.Unit = 'meV',
    components: ModelComponent | ComponentCollection | None = None,
    Q: Q_type | None = None,
    diffusion_models: DiffusionModelBase | list[DiffusionModelBase] | None = None,
    temperature: float | None = None,
    temperature_unit: str | sc.Unit = 'K',
    detailed_balance_settings: DetailedBalanceSettings | None = None,
) -> None:
    """
    Initialize the SampleModel.

    Parameters
    ----------
    display_name : str, default='MySampleModel'
        Display name of the model.
    unique_name : str | None, default=None
        Unique name of the model. If None, a unique name will be generated.
    unit : str | sc.Unit, default='meV'
        Unit of the model. If None,.
    components : ModelComponent | ComponentCollection | None, default=None
        Template components of the model. If None, no components are added. These components
        are copied into ComponentCollections for each Q value.
    Q : Q_type | None, default=None
        Q values for the model. If None, Q is not set.
    diffusion_models : DiffusionModelBase | list[DiffusionModelBase] | None, default=None
        Diffusion models to include in the SampleModel. If None, no diffusion models are added.
    temperature : float | None, default=None
        Temperature for detailed balancing. If None, no detailed balancing is applied. By
        default, None.
    temperature_unit : str | sc.Unit, default='K'
        Unit of the temperature.
    detailed_balance_settings : DetailedBalanceSettings | None, default=None
        Settings for detailed balancing.

    Raises
    ------
    TypeError
        If diffusion_models is not a DiffusionModelBase, a list of DiffusionModelBase, or None,
        or if temperature is not a number or None, or if detailed_balance_settings is not a
        DetailedBalanceSettings instance.
    ValueError
        If temperature is negative.
    """
    if diffusion_models is None:
        self._diffusion_models = []
    elif isinstance(diffusion_models, DiffusionModelBase):
        self._diffusion_models = [diffusion_models]
    else:
        if not isinstance(diffusion_models, list) or not all(
            isinstance(dm, DiffusionModelBase) for dm in diffusion_models
        ):
            raise TypeError(
                'diffusion_models must be a DiffusionModelBase, '
                'a list of DiffusionModelBase or None'
            )
        self._diffusion_models = diffusion_models

    super().__init__(
        display_name=display_name,
        unique_name=unique_name,
        unit=unit,
        components=components,
        Q=Q,
    )

    if temperature is None:
        self._temperature = None
    else:
        if not isinstance(temperature, Numeric):
            raise TypeError('temperature must be a number or None')

        if temperature < 0:
            raise ValueError('temperature must be non-negative')
        self._temperature = Parameter(
            name='Temperature',
            value=temperature,
            unit=temperature_unit,
            display_name='Temperature',
            fixed=True,
        )
    self._temperature_unit = temperature_unit

    if detailed_balance_settings is None:
        self._detailed_balance_settings = DetailedBalanceSettings()
    elif isinstance(detailed_balance_settings, DetailedBalanceSettings):
        self._detailed_balance_settings = detailed_balance_settings
    else:
        raise TypeError('detailed_balance_settings must be a DetailedBalanceSettings or None')

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.

Source code in src/easydynamics/sample_model/sample_model.py

def append_diffusion_model(self, diffusion_model: DiffusionModelBase) -> None:
    """
    Append a DiffusionModel to the SampleModel.

    Parameters
    ----------
    diffusion_model : DiffusionModelBase
        The DiffusionModel to append.

    Raises
    ------
    TypeError
        If the diffusion_model is not a DiffusionModelBase.
    """

    if not isinstance(diffusion_model, DiffusionModelBase):
        raise TypeError(
            f'diffusion_model must be a DiffusionModelBase, got {type(diffusion_model).__name__}'  # noqa: E501
        )

    self._diffusion_models.append(diffusion_model)
    self._generate_component_collections()

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.

Source code in src/easydynamics/sample_model/sample_model.py

def remove_diffusion_model(self, name: str) -> None:
    """
    Remove a DiffusionModel from the SampleModel by name.

    Parameters
    ----------
    name : str
        The name of the DiffusionModel to remove.

    Raises
    ------
    ValueError
        If no DiffusionModel with the given name is found.
    """
    for i, dm in enumerate(self._diffusion_models):
        if dm.name == name:
            del self._diffusion_models[i]
            self._generate_component_collections()
            return
    raise ValueError(
        f'No DiffusionModel with name {name} found. \n'
        f'The available names are: {[dm.name for dm in self._diffusion_models]}'
    )

clear_diffusion_models()

Clear all DiffusionModels from the SampleModel.

Source code in src/easydynamics/sample_model/sample_model.py

def clear_diffusion_models(self) -> None:
    """Clear all DiffusionModels from the SampleModel."""
    self._diffusion_models.clear()
    self._generate_component_collections()

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.

Source code in src/easydynamics/sample_model/sample_model.py

def convert_temperature_unit(self, unit: str | sc.Unit) -> None:
    """
    Convert the unit of the temperature Parameter.

    Parameters
    ----------
    unit : str | sc.Unit
        The unit to convert the temperature Parameter to.

    Raises
    ------
    ValueError
        If temperature is not set or conversion fails.
    Exception
        If the provided unit is invalid or cannot be converted.
    """

    if self.temperature is None:
        raise ValueError('Temperature is not set, cannot convert unit.')

    old_unit = self.temperature.unit

    try:
        self.temperature.convert_unit(unit)
        self._temperature_unit = unit
    except Exception:
        # Attempt to rollback on failure
        with suppress(Exception):
            self.temperature.convert_unit(old_unit)
        raise

evaluate(x)

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. Can be a number, list, numpy array, scipp Variable, or scipp DataArray.	required

Returns:

Type	Description
list[np.ndarray]	List of evaluated model values for each Q.

Source code in src/easydynamics/sample_model/sample_model.py

def evaluate(
    self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray
) -> list[np.ndarray]:
    """
    Evaluate the sample model at all Q for the given x values.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values to evaluate the model at. Can be a number, list, numpy array, scipp
        Variable, or scipp DataArray.

    Returns
    -------
    list[np.ndarray]
        List of evaluated model values for each Q.
    """

    y = super().evaluate(x)

    if self.temperature is not None and self.detailed_balance_settings.use_detailed_balance:
        DBF = detailed_balance_factor(
            energy=x,
            temperature=self.temperature,
            divide_by_temperature=self.detailed_balance_settings.normalize_detailed_balance,
            energy_unit=self.unit,
        )
        y = [yi * DBF for yi in y]

    return y

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]	List of all Parameters and Descriptors, including temperature if set and all variables from diffusion models.

Source code in src/easydynamics/sample_model/sample_model.py

def get_all_variables(self, Q_index: int | None = None) -> list[Parameter]:
    """
    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
    ----------
    Q_index : int | None, default=None
        If specified, only get variables from the ComponentCollection at the given Q index. If
        None, get variables from all ComponentCollections.

    Returns
    -------
    list[Parameter]
        List of all Parameters and Descriptors, including temperature if set and all variables
        from diffusion models.
    """

    all_vars = super().get_all_variables(Q_index=Q_index)
    if self.temperature is not None:
        all_vars.append(self.temperature)

    for diffusion_model in self._diffusion_models:
        all_vars.extend(diffusion_model.get_all_variables())

    return all_vars

__repr__()

Return a string representation of the SampleModel.

Returns:

Type	Description
str	A string representation of the SampleModel.

Source code in src/easydynamics/sample_model/sample_model.py

def __repr__(self) -> str:
    """
    Return a string representation of the SampleModel.

    Returns
    -------
    str
        A string representation of the SampleModel.
    """

    return (
        f'{self.__class__.__name__}(unique_name={self.unique_name}, unit={self.unit}), '
        f'Q = {self.Q}, \n '
        f'components = {self.components}, diffusion_models = {self.diffusion_models}, '
        f'temperature = {self.temperature}, '
        f'detailed_balance_settings = {self.detailed_balance_settings}'
    )

background_model

BackgroundModel

Bases: ModelBase

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

Source code in src/easydynamics/sample_model/background_model.py

class BackgroundModel(ModelBase):
    """
    BackgroundModel represents a model of the background in an experiment at various Q.
    """

    def __init__(
        self,
        display_name: str | None = 'MyBackgroundModel',
        unique_name: str | None = None,
        unit: str | sc.Unit = 'meV',
        components: ModelComponent | ComponentCollection | None = None,
        Q: Q_type | None = None,
    ) -> None:
        """
        Initialize the BackgroundModel.

        Parameters
        ----------
        display_name : str | None, default='MyBackgroundModel'
            Display name of the model.
        unique_name : str | None, default=None
            Unique name of the model. If None, a unique name will be generated.
        unit : str | sc.Unit, default='meV'
            Unit of the model.
        components : ModelComponent | ComponentCollection | None, default=None
            Template components of the model. If None, no components are added. These components
            are copied into ComponentCollections for each Q value.
        Q : Q_type | None, default=None
            Q values for the model. If None, Q is not set.
        """
        super().__init__(
            display_name=display_name,
            unique_name=unique_name,
            unit=unit,
            components=components,
            Q=Q,
        )

__init__(display_name='MyBackgroundModel', unique_name=None, unit='meV', components=None, Q=None)

Initialize the BackgroundModel.

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
unit	str | sc.Unit	Unit of the model.	'meV'
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

Source code in src/easydynamics/sample_model/background_model.py

def __init__(
    self,
    display_name: str | None = 'MyBackgroundModel',
    unique_name: str | None = None,
    unit: str | sc.Unit = 'meV',
    components: ModelComponent | ComponentCollection | None = None,
    Q: Q_type | None = None,
) -> None:
    """
    Initialize the BackgroundModel.

    Parameters
    ----------
    display_name : str | None, default='MyBackgroundModel'
        Display name of the model.
    unique_name : str | None, default=None
        Unique name of the model. If None, a unique name will be generated.
    unit : str | sc.Unit, default='meV'
        Unit of the model.
    components : ModelComponent | ComponentCollection | None, default=None
        Template components of the model. If None, no components are added. These components
        are copied into ComponentCollections for each Q value.
    Q : Q_type | None, default=None
        Q values for the model. If None, Q is not set.
    """
    super().__init__(
        display_name=display_name,
        unique_name=unique_name,
        unit=unit,
        components=components,
        Q=Q,
    )

component_collection

ComponentCollection

Bases: EasyDynamicsList, EasyDynamicsModelBase

Collection of model components.

Examples:

Create a ComponentCollection with two components:

>>> 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])

Append a component to the collection:

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

Evaluate the collection at a given energy axis:

>>> import numpy as np
>>> x = np.linspace(-5, 5, 100)
>>> values = collection.evaluate(x)

Remove a component by name:

>>> collection.remove('Gaussian1')

List component names:

>>> collection.list_component_names()
['Lorentzian1', 'Gaussian2']

Source code in src/easydynamics/sample_model/component_collection.py

class ComponentCollection(EasyDynamicsList, EasyDynamicsModelBase):
    """
    Collection of model components.

    Examples
    --------
    Create a ComponentCollection with two components:
    >>> 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])

    Append a component to the collection:
    >>> component3 = sm.Gaussian(name='Gaussian2', area=0.5, width=0.8)
    >>> collection.append(component3)

    Evaluate the collection at a given energy axis:
    >>> import numpy as np
    >>> x = np.linspace(-5, 5, 100)
    >>> values = collection.evaluate(x)

    Remove a component by name:
    >>> collection.remove('Gaussian1')

    List component names:
    >>> collection.list_component_names()
    ['Lorentzian1', 'Gaussian2']
    """

    def __init__(
        self,
        components: ModelComponent | list[ModelComponent] | None = None,
        unit: str | sc.Unit = 'meV',
        name: str = 'ComponentCollection',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize a new ComponentCollection.

        Parameters
        ----------
        components : ModelComponent | list[ModelComponent] | None, default=None
            Initial model components to add to the ComponentCollection.
        unit : str | sc.Unit, default='meV'
            Unit of the collection.
        name : str, default='ComponentCollection'
            Name of the collection.
        display_name : str | None, default=None
            Display name of the collection.
        unique_name : str | None, default=None
            Unique name of the collection.

        Raises
        ------
        TypeError
            If unit is not a string or sc.Unit, or if components is not a list of ModelComponent.
        """
        if components is None:
            components = []
        if isinstance(components, ModelComponent):
            components = [components]
        elif not isinstance(components, list):
            raise TypeError(
                f'components must be a ModelComponent or a list of ModelComponent, got {type(components).__name__} instead.'  # noqa: E501
            )
        for comp in components:
            if not isinstance(comp, ModelComponent):
                raise TypeError(
                    f'All items in components must be instances of ModelComponent, got {type(comp).__name__} instead.'  # noqa: E501
                )

        EasyDynamicsList.__init__(
            self,
            *components,
            protected_types=ModelComponent,
        )

        EasyDynamicsModelBase.__init__(
            self,
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

    # ------------------------------------------------------------------
    # Properties
    # ------------------------------------------------------------------

    @property
    def is_empty(self) -> bool:
        """
        Check if the ComponentCollection has no components.

        Returns
        -------
        bool
            True if the collection has no components, False otherwise.
        """
        return not self

    @is_empty.setter
    def is_empty(self, _value: bool) -> None:
        """
        Is_empty is a read-only property that indicates whether the collection has components.

        Parameters
        ----------
        _value : bool
            The value to set (ignored).

        Raises
        ------
        AttributeError
            Always raised since is_empty is read-only.
        """
        raise AttributeError(
            'is_empty is a read-only property that indicates '
            'whether the collection has components.'
        )

    def convert_unit(self, unit: str | sc.Unit) -> None:
        """
        Convert the unit of the ComponentCollection and all its components.

        Parameters
        ----------
        unit : str | sc.Unit
            The target unit to convert to.

        Raises
        ------
        TypeError
            If unit is not a string or sc.Unit.
        Exception
            If any component cannot be converted to the specified unit.
        """

        if not isinstance(unit, (str, sc.Unit)):
            raise TypeError(f'Unit must be a string or sc.Unit, got {type(unit).__name__}')

        old_unit = self._unit

        try:
            for component in self:
                component.convert_unit(unit)
            self._unit = unit
        except Exception as e:
            # Attempt to rollback on failure
            try:
                for component in self:
                    component.convert_unit(old_unit)
            except Exception:  # noqa: S110
                pass  # Best effort rollback
            raise e

    # ------------------------------------------------------------------
    # Component management
    # ------------------------------------------------------------------

    def append_component(self, component: ModelComponent | ComponentCollection) -> None:
        """
        Append a model component or the components from another ComponentCollection to this
        ComponentCollection.

        Parameters
        ----------
        component : ModelComponent | ComponentCollection
            The component to append. If a ComponentCollection is provided, all of its components
            will be appended.
        """
        if isinstance(component, ComponentCollection):
            self.extend(component)
        else:
            self.append(component)

    def list_component_names(self) -> list[str]:
        """
        List the names of all components in the model.

        Returns
        -------
        list[str]
            List of names of the components in the collection.
        """

        return [component.name for component in self]

    def normalize_area(self) -> None:
        """
        Normalize the areas of all components so they sum to 1.

        This is useful for convolutions.

        Raises
        ------
        ValueError
            If there are no components in the model or if the total area is zero or not finite,
            which would prevent normalization.
        """
        if not self:
            raise ValueError('No components in the model to normalize.')

        area_params = []
        total_area = Parameter(name='total_area', value=0.0, unit=self._unit)

        for component in self:
            if hasattr(component, 'area'):
                area_params.append(component.area)
                total_area += component.area
            else:
                warnings.warn(
                    f"Component '{component.name}' does not have an 'area' attribute "
                    f'and will be skipped in normalization.',
                    UserWarning,
                    stacklevel=2,
                )

        if total_area.value == 0:
            raise ValueError('Total area is zero; cannot normalize.')

        if not np.isfinite(total_area.value):
            raise ValueError('Total area is not finite; cannot normalize.')

        for param in area_params:
            param.value /= total_area.value

    # ------------------------------------------------------------------
    # Other methods
    # ------------------------------------------------------------------

    def get_all_variables(self) -> list[DescriptorBase]:
        """
        Get all parameters from the model component.

        Returns
        -------
        list[DescriptorBase]
            List of parameters in the component.
        """

        return [var for component in self for var in component.get_all_variables()]

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        """
        Evaluate the sum of all components.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            Energy axis.

        Returns
        -------
        np.ndarray
            Evaluated model values.
        """

        if not self:
            return np.zeros_like(x)
        return sum(component.evaluate(x) for component in self)

    def evaluate_component(
        self,
        x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
        name: str,
    ) -> np.ndarray:
        """
        Evaluate a single component by name.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            Energy axis.
        name : str
            Component name.

        Raises
        ------
        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
        -------
        np.ndarray
            Evaluated values for the specified component.
        """
        if not self:
            raise ValueError('No components in the model to evaluate.')

        if not isinstance(name, str):
            raise TypeError(f'Component name must be a string, got {type(name)} instead.')

        matches = [comp for comp in self if comp.name == name]
        if not matches:
            raise KeyError(f"No component named '{name}' exists.")

        component = matches[0]

        return component.evaluate(x)

    def fix_all_parameters(self) -> None:
        """Fix all free parameters in the model."""
        for param in self.get_fittable_parameters():
            param.fixed = True

    def free_all_parameters(self) -> None:
        """Free all fixed parameters in the model."""
        for param in self.get_fittable_parameters():
            param.fixed = False

    # ------------------------------------------------------------------
    # Dunder methods
    # ------------------------------------------------------------------

    def __contains__(self, item: str | ModelComponent) -> bool:
        """
        Check if a component with the given name or instance exists in the ComponentCollection.

        Parameters
        ----------
        item : str | ModelComponent
            The component name or instance to check for.

        Returns
        -------
        bool
            True if the component exists, False otherwise.
        """

        if isinstance(item, str):
            # Check by component name
            return any(comp.name == item for comp in self)
        if isinstance(item, ModelComponent):
            # Check by component instance
            return any(comp is item for comp in self)
        return False

    def __repr__(self) -> str:
        """
        Return a string representation of the ComponentCollection.

        Returns
        -------
        str
            String representation of the ComponentCollection.
        """
        comp_names = ', '.join(c.name for c in self) or 'No components'

        return f"<ComponentCollection name='{self.name}' | Components: {comp_names}>"

    def to_dict(self) -> dict:
        return {
            '@module': self.__class__.__module__,
            '@class': self.__class__.__name__,
            'unit': str(self.unit),
            'name': self.name,
            'display_name': self.display_name,
            'components': [c.to_dict() for c in self._data],
        }

    @classmethod
    def from_dict(cls, obj_dict: dict) -> ComponentCollection:

        def deserialise_component(d: dict) -> ModelComponent:
            """
            Deserialise a component from its dictionary representation.
            Parameters
            ----------
            d : dict
                The dictionary representation of the component.
            Returns
            -------
            ModelComponent
                The deserialised component.
            """
            module = importlib.import_module(d['@module'])
            cls = getattr(module, d['@class'])
            return cls.from_dict(d)

        components = [deserialise_component(c) for c in obj_dict.get('components', [])]

        return cls(
            components=components,
            unit=obj_dict.get('unit', 'meV'),
            name=obj_dict.get('name', 'ComponentCollection'),
            display_name=obj_dict.get('display_name'),
        )

    def __copy__(self) -> ComponentCollection:
        """
        Create a deep copy of the ComponentCollection.

        Returns
        -------
        ComponentCollection
            A deep copy of the ComponentCollection.
        """

        return self.from_dict(self.to_dict())

is_empty property writable

Check if the ComponentCollection has no components.

Returns:

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

__init__(components=None, unit='meV', name='ComponentCollection', display_name=None, unique_name=None)

Initialize a new ComponentCollection.

Parameters:

Name	Type	Description	Default
components	ModelComponent | list[ModelComponent] | None	Initial model components to add to the ComponentCollection.	None
unit	str | sc.Unit	Unit of the collection.	'meV'
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 unit is not a string or sc.Unit, or if components is not a list of ModelComponent.

Source code in src/easydynamics/sample_model/component_collection.py

def __init__(
    self,
    components: ModelComponent | list[ModelComponent] | None = None,
    unit: str | sc.Unit = 'meV',
    name: str = 'ComponentCollection',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize a new ComponentCollection.

    Parameters
    ----------
    components : ModelComponent | list[ModelComponent] | None, default=None
        Initial model components to add to the ComponentCollection.
    unit : str | sc.Unit, default='meV'
        Unit of the collection.
    name : str, default='ComponentCollection'
        Name of the collection.
    display_name : str | None, default=None
        Display name of the collection.
    unique_name : str | None, default=None
        Unique name of the collection.

    Raises
    ------
    TypeError
        If unit is not a string or sc.Unit, or if components is not a list of ModelComponent.
    """
    if components is None:
        components = []
    if isinstance(components, ModelComponent):
        components = [components]
    elif not isinstance(components, list):
        raise TypeError(
            f'components must be a ModelComponent or a list of ModelComponent, got {type(components).__name__} instead.'  # noqa: E501
        )
    for comp in components:
        if not isinstance(comp, ModelComponent):
            raise TypeError(
                f'All items in components must be instances of ModelComponent, got {type(comp).__name__} instead.'  # noqa: E501
            )

    EasyDynamicsList.__init__(
        self,
        *components,
        protected_types=ModelComponent,
    )

    EasyDynamicsModelBase.__init__(
        self,
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

convert_unit(unit)

Convert the unit of the ComponentCollection and all its components.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The target unit to convert to.	required

Raises:

Type	Description
TypeError	If unit is not a string or sc.Unit.
Exception	If any component cannot be converted to the specified unit.

Source code in src/easydynamics/sample_model/component_collection.py

def convert_unit(self, unit: str | sc.Unit) -> None:
    """
    Convert the unit of the ComponentCollection and all its components.

    Parameters
    ----------
    unit : str | sc.Unit
        The target unit to convert to.

    Raises
    ------
    TypeError
        If unit is not a string or sc.Unit.
    Exception
        If any component cannot be converted to the specified unit.
    """

    if not isinstance(unit, (str, sc.Unit)):
        raise TypeError(f'Unit must be a string or sc.Unit, got {type(unit).__name__}')

    old_unit = self._unit

    try:
        for component in self:
            component.convert_unit(unit)
        self._unit = unit
    except Exception as e:
        # Attempt to rollback on failure
        try:
            for component in self:
                component.convert_unit(old_unit)
        except Exception:  # noqa: S110
            pass  # Best effort rollback
        raise e

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

Source code in src/easydynamics/sample_model/component_collection.py

def append_component(self, component: ModelComponent | ComponentCollection) -> None:
    """
    Append a model component or the components from another ComponentCollection to this
    ComponentCollection.

    Parameters
    ----------
    component : ModelComponent | ComponentCollection
        The component to append. If a ComponentCollection is provided, all of its components
        will be appended.
    """
    if isinstance(component, ComponentCollection):
        self.extend(component)
    else:
        self.append(component)

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.

Source code in src/easydynamics/sample_model/component_collection.py

def list_component_names(self) -> list[str]:
    """
    List the names of all components in the model.

    Returns
    -------
    list[str]
        List of names of the components in the collection.
    """

    return [component.name for component in self]

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.

Source code in src/easydynamics/sample_model/component_collection.py

def normalize_area(self) -> None:
    """
    Normalize the areas of all components so they sum to 1.

    This is useful for convolutions.

    Raises
    ------
    ValueError
        If there are no components in the model or if the total area is zero or not finite,
        which would prevent normalization.
    """
    if not self:
        raise ValueError('No components in the model to normalize.')

    area_params = []
    total_area = Parameter(name='total_area', value=0.0, unit=self._unit)

    for component in self:
        if hasattr(component, 'area'):
            area_params.append(component.area)
            total_area += component.area
        else:
            warnings.warn(
                f"Component '{component.name}' does not have an 'area' attribute "
                f'and will be skipped in normalization.',
                UserWarning,
                stacklevel=2,
            )

    if total_area.value == 0:
        raise ValueError('Total area is zero; cannot normalize.')

    if not np.isfinite(total_area.value):
        raise ValueError('Total area is not finite; cannot normalize.')

    for param in area_params:
        param.value /= total_area.value

get_all_variables()

Get all parameters from the model component.

Returns:

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

Source code in src/easydynamics/sample_model/component_collection.py

def get_all_variables(self) -> list[DescriptorBase]:
    """
    Get all parameters from the model component.

    Returns
    -------
    list[DescriptorBase]
        List of parameters in the component.
    """

    return [var for component in self for var in component.get_all_variables()]

evaluate(x)

Evaluate the sum of all components.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	Energy axis.	required

Returns:

Type	Description
np.ndarray	Evaluated model values.

Source code in src/easydynamics/sample_model/component_collection.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    """
    Evaluate the sum of all components.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        Energy axis.

    Returns
    -------
    np.ndarray
        Evaluated model values.
    """

    if not self:
        return np.zeros_like(x)
    return sum(component.evaluate(x) for component in self)

evaluate_component(x, name)

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

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	Evaluated values for the specified component.

Source code in src/easydynamics/sample_model/component_collection.py

def evaluate_component(
    self,
    x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
    name: str,
) -> np.ndarray:
    """
    Evaluate a single component by name.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        Energy axis.
    name : str
        Component name.

    Raises
    ------
    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
    -------
    np.ndarray
        Evaluated values for the specified component.
    """
    if not self:
        raise ValueError('No components in the model to evaluate.')

    if not isinstance(name, str):
        raise TypeError(f'Component name must be a string, got {type(name)} instead.')

    matches = [comp for comp in self if comp.name == name]
    if not matches:
        raise KeyError(f"No component named '{name}' exists.")

    component = matches[0]

    return component.evaluate(x)

fix_all_parameters()

Fix all free parameters in the model.

Source code in src/easydynamics/sample_model/component_collection.py

def fix_all_parameters(self) -> None:
    """Fix all free parameters in the model."""
    for param in self.get_fittable_parameters():
        param.fixed = True

free_all_parameters()

Free all fixed parameters in the model.

Source code in src/easydynamics/sample_model/component_collection.py

def free_all_parameters(self) -> None:
    """Free all fixed parameters in the model."""
    for param in self.get_fittable_parameters():
        param.fixed = False

__contains__(item)

Check if a component with the given name or instance exists in the ComponentCollection.

Parameters:

Name	Type	Description	Default
item	str | ModelComponent	The component name or instance to check for.	required

Returns:

Type	Description
bool	True if the component exists, False otherwise.

Source code in src/easydynamics/sample_model/component_collection.py

def __contains__(self, item: str | ModelComponent) -> bool:
    """
    Check if a component with the given name or instance exists in the ComponentCollection.

    Parameters
    ----------
    item : str | ModelComponent
        The component name or instance to check for.

    Returns
    -------
    bool
        True if the component exists, False otherwise.
    """

    if isinstance(item, str):
        # Check by component name
        return any(comp.name == item for comp in self)
    if isinstance(item, ModelComponent):
        # Check by component instance
        return any(comp is item for comp in self)
    return False

__repr__()

Return a string representation of the ComponentCollection.

Returns:

Type	Description
str	String representation of the ComponentCollection.

Source code in src/easydynamics/sample_model/component_collection.py

def __repr__(self) -> str:
    """
    Return a string representation of the ComponentCollection.

    Returns
    -------
    str
        String representation of the ComponentCollection.
    """
    comp_names = ', '.join(c.name for c in self) or 'No components'

    return f"<ComponentCollection name='{self.name}' | Components: {comp_names}>"

__copy__()

Create a deep copy of the ComponentCollection.

Returns:

Type	Description
ComponentCollection	A deep copy of the ComponentCollection.

Source code in src/easydynamics/sample_model/component_collection.py

def __copy__(self) -> ComponentCollection:
    """
    Create a deep copy of the ComponentCollection.

    Returns
    -------
    ComponentCollection
        A deep copy of the ComponentCollection.
    """

    return self.from_dict(self.to_dict())

components

DampedHarmonicOscillator

Bases: CreateParametersMixin, ModelComponent

Model of a Damped Harmonic Oscillator (DHO).

The intensity is given by $$ 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, \(x_0\) is the center, and \(\gamma\) is the width.

Source code in src/easydynamics/sample_model/components/damped_harmonic_oscillator.py

class DampedHarmonicOscillator(CreateParametersMixin, ModelComponent):
    r"""
    Model of a Damped Harmonic Oscillator (DHO).

    The intensity is given by $$ 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, $x_0$ is the center, and $\gamma$ is the width.
    """

    def __init__(
        self,
        area: Numeric | Parameter = 1.0,
        center: Numeric | Parameter = 1.0,
        width: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'DampedHarmonicOscillator',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Damped Harmonic Oscillator.

        Parameters
        ----------
        area : Numeric | Parameter, default=1.0
            Area under the curve.
        center : Numeric | Parameter, default=1.0
            Resonance frequency, approximately the peak position.
        width : Numeric | Parameter, default=1.0
            Damping constant, approximately the half width at half max (HWHM) of the peaks. By
            default, 1.0.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='DampedHarmonicOscillator'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.
        """

        super().__init__(
            name=name,
            display_name=display_name,
            unique_name=unique_name,
            unit=unit,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center,
            name=name,
            fix_if_none=False,
            unit=self._unit,
            enforce_minimum_center=True,
        )

        width = self._create_width_parameter(width=width, name=name, unit=self._unit)

        self._area = area
        self._center = center
        self._width = width

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """
        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """
        return self._center

    @center.setter
    def center(self, value: Numeric) -> None:
        """
        Set the value of the center parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the center parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')

        if float(value) <= 0:
            raise ValueError('center must be positive')
        self._center.value = value

    @property
    def width(self) -> Parameter:
        """
        Get the width parameter.

        Returns
        -------
        Parameter
            The width parameter.
        """
        return self._width

    @width.setter
    def width(self, value: Numeric) -> None:
        """
        Set the value of the width parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the width parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('width must be a number')

        if float(value) <= 0:
            raise ValueError('width must be positive')

        self._width.value = value

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        r"""
        Evaluate the Damped Harmonic Oscillator at the given x values.

        If x is a scipp Variable, the unit of the DHO will be converted to match x. The intensity
        is given by $$ 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, $x_0$ is the center, and $\gamma$ is the width.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the DHO.

        Returns
        -------
        np.ndarray
            The intensity of the DHO at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        normalization = 2 * self.center.value**2 * self.width.value / np.pi
        # No division by zero here, width>0 enforced in setter
        denominator = (x**2 - self.center.value**2) ** 2 + (2 * self.width.value * x) ** 2

        return self.area.value * normalization / (denominator)

    def __repr__(self) -> str:
        """
        Return a string representation of the Damped Harmonic Oscillator.

        Returns
        -------
        str
            A string representation of the Damped Harmonic Oscillator.
        """
        return (
            f'DampedHarmonicOscillator(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n '
            f'    area = {self.area},\n '
            f'    center = {self.center},\n '
            f'    width = {self.width})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

width property writable

Get the width parameter.

Returns:

Type	Description
Parameter	The width parameter.

__init__(area=1.0, center=1.0, width=1.0, unit='meV', name='DampedHarmonicOscillator', display_name=None, unique_name=None)

Initialize the Damped Harmonic Oscillator.

Parameters:

Name	Type	Description	Default
area	Numeric | Parameter	Area under the curve.	1.0
center	Numeric | Parameter	Resonance frequency, approximately the peak position.	1.0
width	Numeric | Parameter	Damping constant, approximately the half width at half max (HWHM) of the peaks. By default, 1.0.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'DampedHarmonicOscillator'
display_name	str | None	Display name of the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/damped_harmonic_oscillator.py

def __init__(
    self,
    area: Numeric | Parameter = 1.0,
    center: Numeric | Parameter = 1.0,
    width: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'DampedHarmonicOscillator',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Damped Harmonic Oscillator.

    Parameters
    ----------
    area : Numeric | Parameter, default=1.0
        Area under the curve.
    center : Numeric | Parameter, default=1.0
        Resonance frequency, approximately the peak position.
    width : Numeric | Parameter, default=1.0
        Damping constant, approximately the half width at half max (HWHM) of the peaks. By
        default, 1.0.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='DampedHarmonicOscillator'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.
    """

    super().__init__(
        name=name,
        display_name=display_name,
        unique_name=unique_name,
        unit=unit,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center,
        name=name,
        fix_if_none=False,
        unit=self._unit,
        enforce_minimum_center=True,
    )

    width = self._create_width_parameter(width=width, name=name, unit=self._unit)

    self._area = area
    self._center = center
    self._width = width

evaluate(x)

Evaluate the Damped Harmonic Oscillator at the given x values.

If x is a scipp Variable, the unit of the DHO will be converted to match x. The intensity is given by $$ 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, \(x_0\) is the center, and \(\gamma\) is the width.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the DHO.	required

Returns:

Type	Description
np.ndarray	The intensity of the DHO at the given x values.

Source code in src/easydynamics/sample_model/components/damped_harmonic_oscillator.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    r"""
    Evaluate the Damped Harmonic Oscillator at the given x values.

    If x is a scipp Variable, the unit of the DHO will be converted to match x. The intensity
    is given by $$ 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, $x_0$ is the center, and $\gamma$ is the width.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the DHO.

    Returns
    -------
    np.ndarray
        The intensity of the DHO at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    normalization = 2 * self.center.value**2 * self.width.value / np.pi
    # No division by zero here, width>0 enforced in setter
    denominator = (x**2 - self.center.value**2) ** 2 + (2 * self.width.value * x) ** 2

    return self.area.value * normalization / (denominator)

__repr__()

Return a string representation of the Damped Harmonic Oscillator.

Returns:

Type	Description
str	A string representation of the Damped Harmonic Oscillator.

Source code in src/easydynamics/sample_model/components/damped_harmonic_oscillator.py

def __repr__(self) -> str:
    """
    Return a string representation of the Damped Harmonic Oscillator.

    Returns
    -------
    str
        A string representation of the Damped Harmonic Oscillator.
    """
    return (
        f'DampedHarmonicOscillator(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n '
        f'    area = {self.area},\n '
        f'    center = {self.center},\n '
        f'    width = {self.width})'
    )

DeltaFunction

Bases: CreateParametersMixin, ModelComponent

Delta function.

Evaluates to zero everywhere, except in convolutions, where it acts as an identity. This is handled by the Convolution method. If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Source code in src/easydynamics/sample_model/components/delta_function.py

class DeltaFunction(CreateParametersMixin, ModelComponent):
    """
    Delta function.

    Evaluates to zero everywhere, except in convolutions, where it acts as an identity. This is
    handled by the Convolution method. If the center is not provided, it will be centered at 0 and
    fixed, which is typically what you want in QENS.
    """

    def __init__(
        self,
        center: Numeric | Parameter | None = None,
        area: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'DeltaFunction',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Delta function.

        Parameters
        ----------
        center : Numeric | Parameter | None, default=None
            Center of the delta function. If None, it will be centered at 0 and fixed.
        area : Numeric | Parameter, default=1.0
            Total area under the curve.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='DeltaFunction'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.
        """
        # Validate inputs and create Parameters if not given
        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )

        self._area = area
        self._center = center

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """

        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """

        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """

        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the center parameter value.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter. If None, defaults to 0 and is fixed.

        Raises
        ------
        TypeError
            If the value is not a number or None.
        """

        if value is None:
            value = 0.0
            self._center.fixed = True
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        """
        Evaluate the Delta function at the given x values.

        The Delta function evaluates to zero everywhere, except at the center. Its numerical
        integral is equal to the area. It acts as an identity in convolutions.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Delta function.

        Returns
        -------
        np.ndarray
            The evaluated Delta function at the given x values.
        """

        # x assumed sorted, 1D numpy array
        x = self._prepare_x_for_evaluate(x)
        model = np.zeros_like(x, dtype=float)
        center = self.center.value
        area = self.area.value

        if x.min() - EPSILON <= center <= x.max() + EPSILON:
            # nearest index
            i = np.argmin(np.abs(x - center))

            # left half-width
            if i == 0:  # noqa: SIM108
                left = x[1] - x[0] if x.size > 1 else 0.5
            else:
                left = x[i] - x[i - 1]

            # right half-width
            if i == x.size - 1:  # noqa: SIM108
                right = x[-1] - x[-2] if x.size > 1 else 0.5
            else:
                right = x[i + 1] - x[i]

            # effective bin width: half left + half right
            bin_width = 0.5 * (left + right)

            model[i] = area / bin_width

        return model

    def __repr__(self) -> str:
        """
        Return a string representation of the Delta function.

        Returns
        -------
        str
            A string representation of the Delta function.
        """

        return (
            f'DeltaFunction(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self.unit},\n'
            f'    area = {self.area},\n'
            f'    center = {self.center})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

__init__(center=None, area=1.0, unit='meV', name='DeltaFunction', display_name=None, unique_name=None)

Initialize the Delta function.

Parameters:

Name	Type	Description	Default
center	Numeric | Parameter | None	Center of the delta function. If None, it will be centered at 0 and fixed.	None
area	Numeric | Parameter	Total area under the curve.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'DeltaFunction'
display_name	str | None	Display name of the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/delta_function.py

def __init__(
    self,
    center: Numeric | Parameter | None = None,
    area: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'DeltaFunction',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Delta function.

    Parameters
    ----------
    center : Numeric | Parameter | None, default=None
        Center of the delta function. If None, it will be centered at 0 and fixed.
    area : Numeric | Parameter, default=1.0
        Total area under the curve.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='DeltaFunction'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.
    """
    # Validate inputs and create Parameters if not given
    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )

    self._area = area
    self._center = center

evaluate(x)

Evaluate the Delta function at the given x values.

The Delta function evaluates to zero everywhere, except at the center. Its numerical integral is equal to the area. It acts as an identity in convolutions.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Delta function.	required

Returns:

Type	Description
np.ndarray	The evaluated Delta function at the given x values.

Source code in src/easydynamics/sample_model/components/delta_function.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    """
    Evaluate the Delta function at the given x values.

    The Delta function evaluates to zero everywhere, except at the center. Its numerical
    integral is equal to the area. It acts as an identity in convolutions.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Delta function.

    Returns
    -------
    np.ndarray
        The evaluated Delta function at the given x values.
    """

    # x assumed sorted, 1D numpy array
    x = self._prepare_x_for_evaluate(x)
    model = np.zeros_like(x, dtype=float)
    center = self.center.value
    area = self.area.value

    if x.min() - EPSILON <= center <= x.max() + EPSILON:
        # nearest index
        i = np.argmin(np.abs(x - center))

        # left half-width
        if i == 0:  # noqa: SIM108
            left = x[1] - x[0] if x.size > 1 else 0.5
        else:
            left = x[i] - x[i - 1]

        # right half-width
        if i == x.size - 1:  # noqa: SIM108
            right = x[-1] - x[-2] if x.size > 1 else 0.5
        else:
            right = x[i + 1] - x[i]

        # effective bin width: half left + half right
        bin_width = 0.5 * (left + right)

        model[i] = area / bin_width

    return model

__repr__()

Return a string representation of the Delta function.

Returns:

Type	Description
str	A string representation of the Delta function.

Source code in src/easydynamics/sample_model/components/delta_function.py

def __repr__(self) -> str:
    """
    Return a string representation of the Delta function.

    Returns
    -------
    str
        A string representation of the Delta function.
    """

    return (
        f'DeltaFunction(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self.unit},\n'
        f'    area = {self.area},\n'
        f'    center = {self.center})'
    )

Exponential

Bases: CreateParametersMixin, ModelComponent

Model of an exponential function.

The intensity is given by

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

where \(A\) is the amplitude, \(x_0\) is the center, and \(B\) describes the rate of decay or growth.

Source code in src/easydynamics/sample_model/components/exponential.py

class Exponential(CreateParametersMixin, ModelComponent):
    r"""
    Model of an exponential function.

    The intensity is given by

    $$ I(x) = A e^{B (x-x_0)}, $$

    where $A$ is the amplitude, $x_0$ is the center, and $B$ describes the rate of decay or growth.
    """

    def __init__(
        self,
        amplitude: Numeric | Parameter = 1.0,
        center: Numeric | Parameter | None = None,
        rate: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'Exponential',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Exponential component.

        Parameters
        ----------
        amplitude : Numeric | Parameter, default=1.0
            Amplitude of the Exponential.
        center : Numeric | Parameter | None, default=None
            Center of the Exponential. If None, the center is fixed at 0.
        rate : Numeric | Parameter, default=1.0
            Decay or growth constant of the Exponential.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='Exponential'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.

        Raises
        ------
        TypeError
            If amplitude, center, or rate are not numbers or Parameters.
        ValueError
            If amplitude, center or rate are not finite numbers.
        """
        # Validate inputs and create Parameters if not given
        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        if not isinstance(amplitude, (Parameter, Numeric)):
            raise TypeError('amplitude must be a number or a Parameter.')

        if isinstance(amplitude, Numeric):
            if not np.isfinite(amplitude):
                raise ValueError('amplitude must be a finite number or a Parameter')

            amplitude = Parameter(name=name + ' amplitude', value=float(amplitude), unit=unit)

        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )

        if not isinstance(rate, (Parameter, Numeric)):
            raise TypeError('rate must be a number or a Parameter.')

        if isinstance(rate, Numeric):
            if not np.isfinite(rate):
                raise ValueError('rate must be a finite number or a Parameter')

            rate = Parameter(name=name + ' rate', value=float(rate), unit='1/' + str(unit))

        self._amplitude = amplitude
        self._center = center
        self._rate = rate

    @property
    def amplitude(self) -> Parameter:
        """
        Get the amplitude parameter.

        Returns
        -------
        Parameter
            The amplitude parameter.
        """

        return self._amplitude

    @amplitude.setter
    def amplitude(self, value: Numeric) -> None:
        """
        Set the value of the amplitude parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the amplitude parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """

        if not isinstance(value, Numeric):
            raise TypeError('amplitude must be a number')
        self._amplitude.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """

        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the center parameter value.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """

        if value is None:
            value = 0.0
            self._center.fixed = True

        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    @property
    def rate(self) -> Parameter:
        """
        Get the rate parameter.

        Returns
        -------
        Parameter
            The rate parameter.
        """
        return self._rate

    @rate.setter
    def rate(self, value: Numeric) -> None:
        """
        Set the rate parameter value.

        Parameters
        ----------
        value : Numeric
            The new value for the rate parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError('rate must be a number')

        self._rate.value = value

    def evaluate(
        self,
        x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
    ) -> np.ndarray:
        r"""
        Evaluate the Exponential at the given x values.

        If x is a scipp Variable, the unit of the Exponential will be converted to match x. The
        intensity is given by $$ I(x) = A \exp\left( r (x - x_0) \right) $$

        where $A$ is the amplitude, $x_0$ is the center, and $r$ is the rate.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Exponential.

        Returns
        -------
        np.ndarray
            The intensity of the Exponential at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)
        exponent = self.rate.value * (x - self.center.value)

        return self.amplitude.value * np.exp(exponent)

    def convert_unit(self, unit: str | sc.Unit) -> None:
        """
        Convert the unit of the Parameters in the component.

        Parameters
        ----------
        unit : str | sc.Unit
            The new unit to convert to.

        Raises
        ------
        TypeError
            If unit is not a string or sc.Unit.
        Exception
            If conversion fails for any parameter.
        """

        if not isinstance(unit, (str, sc.Unit)):
            raise TypeError('unit must be a string or sc.Unit')

        old_unit = self._unit
        pars = [self.amplitude, self.center]
        try:
            for p in pars:
                p.convert_unit(unit)
            self.rate.convert_unit('1/' + str(unit))
            self._unit = unit
        except Exception as e:
            # Attempt to rollback on failure
            try:
                for p in pars:
                    p.convert_unit(old_unit)
                self.rate.convert_unit('1/' + str(old_unit))
            except Exception:  # noqa: S110
                pass  # Best effort rollback
            raise e

    def __repr__(self) -> str:
        """
        Return a string representation of the Exponential.

        Returns
        -------
        str
            A string representation of the Exponential.
        """

        return (
            f'Exponential(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n '
            f'    amplitude = {self.amplitude},\n '
            f'    center = {self.center},\n '
            f'    rate = {self.rate})'
        )

amplitude property writable

Get the amplitude parameter.

Returns:

Type	Description
Parameter	The amplitude parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

rate property writable

Get the rate parameter.

Returns:

Type	Description
Parameter	The rate parameter.

__init__(amplitude=1.0, center=None, rate=1.0, unit='meV', name='Exponential', display_name=None, unique_name=None)

Initialize the Exponential component.

Parameters:

Name	Type	Description	Default
amplitude	Numeric | Parameter	Amplitude of the Exponential.	1.0
center	Numeric | Parameter | None	Center of the Exponential. If None, the center is fixed at 0.	None
rate	Numeric | Parameter	Decay or growth constant of the Exponential.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'Exponential'
display_name	str | None	Display name of the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Raises:

Type	Description
TypeError	If amplitude, center, or rate are not numbers or Parameters.
ValueError	If amplitude, center or rate are not finite numbers.

Source code in src/easydynamics/sample_model/components/exponential.py

def __init__(
    self,
    amplitude: Numeric | Parameter = 1.0,
    center: Numeric | Parameter | None = None,
    rate: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'Exponential',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Exponential component.

    Parameters
    ----------
    amplitude : Numeric | Parameter, default=1.0
        Amplitude of the Exponential.
    center : Numeric | Parameter | None, default=None
        Center of the Exponential. If None, the center is fixed at 0.
    rate : Numeric | Parameter, default=1.0
        Decay or growth constant of the Exponential.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='Exponential'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.

    Raises
    ------
    TypeError
        If amplitude, center, or rate are not numbers or Parameters.
    ValueError
        If amplitude, center or rate are not finite numbers.
    """
    # Validate inputs and create Parameters if not given
    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    if not isinstance(amplitude, (Parameter, Numeric)):
        raise TypeError('amplitude must be a number or a Parameter.')

    if isinstance(amplitude, Numeric):
        if not np.isfinite(amplitude):
            raise ValueError('amplitude must be a finite number or a Parameter')

        amplitude = Parameter(name=name + ' amplitude', value=float(amplitude), unit=unit)

    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )

    if not isinstance(rate, (Parameter, Numeric)):
        raise TypeError('rate must be a number or a Parameter.')

    if isinstance(rate, Numeric):
        if not np.isfinite(rate):
            raise ValueError('rate must be a finite number or a Parameter')

        rate = Parameter(name=name + ' rate', value=float(rate), unit='1/' + str(unit))

    self._amplitude = amplitude
    self._center = center
    self._rate = rate

evaluate(x)

Evaluate the Exponential at the given x values.

If x is a scipp Variable, the unit of the Exponential will be converted to match x. The intensity is given by $$ I(x) = A \exp\left( r (x - x_0) \right) $$

where \(A\) is the amplitude, \(x_0\) is the center, and \(r\) is the rate.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Exponential.	required

Returns:

Type	Description
np.ndarray	The intensity of the Exponential at the given x values.

Source code in src/easydynamics/sample_model/components/exponential.py

def evaluate(
    self,
    x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
) -> np.ndarray:
    r"""
    Evaluate the Exponential at the given x values.

    If x is a scipp Variable, the unit of the Exponential will be converted to match x. The
    intensity is given by $$ I(x) = A \exp\left( r (x - x_0) \right) $$

    where $A$ is the amplitude, $x_0$ is the center, and $r$ is the rate.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Exponential.

    Returns
    -------
    np.ndarray
        The intensity of the Exponential at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)
    exponent = self.rate.value * (x - self.center.value)

    return self.amplitude.value * np.exp(exponent)

convert_unit(unit)

Convert the unit of the Parameters in the component.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The new unit to convert to.	required

Raises:

Type	Description
TypeError	If unit is not a string or sc.Unit.
Exception	If conversion fails for any parameter.

Source code in src/easydynamics/sample_model/components/exponential.py

def convert_unit(self, unit: str | sc.Unit) -> None:
    """
    Convert the unit of the Parameters in the component.

    Parameters
    ----------
    unit : str | sc.Unit
        The new unit to convert to.

    Raises
    ------
    TypeError
        If unit is not a string or sc.Unit.
    Exception
        If conversion fails for any parameter.
    """

    if not isinstance(unit, (str, sc.Unit)):
        raise TypeError('unit must be a string or sc.Unit')

    old_unit = self._unit
    pars = [self.amplitude, self.center]
    try:
        for p in pars:
            p.convert_unit(unit)
        self.rate.convert_unit('1/' + str(unit))
        self._unit = unit
    except Exception as e:
        # Attempt to rollback on failure
        try:
            for p in pars:
                p.convert_unit(old_unit)
            self.rate.convert_unit('1/' + str(old_unit))
        except Exception:  # noqa: S110
            pass  # Best effort rollback
        raise e

__repr__()

Return a string representation of the Exponential.

Returns:

Type	Description
str	A string representation of the Exponential.

Source code in src/easydynamics/sample_model/components/exponential.py

def __repr__(self) -> str:
    """
    Return a string representation of the Exponential.

    Returns
    -------
    str
        A string representation of the Exponential.
    """

    return (
        f'Exponential(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n '
        f'    amplitude = {self.amplitude},\n '
        f'    center = {self.center},\n '
        f'    rate = {self.rate})'
    )

ExpressionComponent

Bases: ModelComponent

Model component defined by a symbolic expression.

Source code in src/easydynamics/sample_model/components/expression_component.py

class ExpressionComponent(ModelComponent):
    """
    Model component defined by a symbolic expression.
    """

    # -------------------------
    # Allowed symbolic functions
    # -------------------------
    _ALLOWED_FUNCS: ClassVar[dict[str, object]] = {
        # Exponentials & logs
        'exp': sp.exp,
        'log': sp.log,
        'ln': sp.log,
        'sqrt': sp.sqrt,
        # Trigonometric
        'sin': sp.sin,
        'cos': sp.cos,
        'tan': sp.tan,
        'sinc': sp.sinc,
        'cot': sp.cot,
        'sec': sp.sec,
        'csc': sp.csc,
        'asin': sp.asin,
        'acos': sp.acos,
        'atan': sp.atan,
        # Hyperbolic
        'sinh': sp.sinh,
        'cosh': sp.cosh,
        'tanh': sp.tanh,
        # Misc
        'abs': sp.Abs,
        'sign': sp.sign,
        'floor': sp.floor,
        'ceil': sp.ceiling,
        # Special functions
        'erf': sp.erf,
    }

    # -------------------------
    # Allowed constants
    # -------------------------
    _ALLOWED_CONSTANTS: ClassVar[dict[str, object]] = {
        'pi': sp.pi,
        'E': sp.E,
    }

    _RESERVED_NAMES: ClassVar[dict[str, object]] = {'x'}

    def __init__(
        self,
        expression: str,
        parameters: dict[str, Numeric] | None = None,
        unit: str | sc.Unit = 'meV',
        name: str = 'Expression',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the ExpressionComponent.

        Parameters
        ----------
        expression : str
            The symbolic expression as a string. Must contain 'x' as the independent variable.
        parameters : dict[str, Numeric] | None, default=None
            Dictionary of parameter names and their initial values.
        unit : str | sc.Unit, default='meV'
            Unit of the output.
        name : str, default='Expression'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name for the component.
        unique_name : str | None, default=None
            Unique name for the component.

        Raises
        ------
        ValueError
            If the expression is invalid or does not contain 'x'.
        TypeError
            If any parameter value is not numeric.

        Examples
        --------
        >>> expr = ExpressionComponent(
        ...     'A * exp(-(x - x0)**2 / (2*sigma**2))',
        ...     parameters={'A': 10, 'x0': 0, 'sigma': 1},
        ...     unit='meV',
        ...     display_name='Gaussian Peak',
        ... )

        >>> expr.A = 5
        >>> y = expr.evaluate(x)
        """
        super().__init__(unit=unit, name=name, display_name=display_name, unique_name=unique_name)

        if 'np.' in expression:
            raise ValueError(
                'NumPy syntax (np.*) is not supported. '
                "Use functions like 'exp', 'sin', etc. directly."
            )

        self._expression_str = expression

        locals_dict = {}
        locals_dict.update(self._ALLOWED_FUNCS)
        locals_dict.update(self._ALLOWED_CONSTANTS)

        try:
            self._expr = sp.sympify(expression, locals=locals_dict)
        except Exception as e:
            raise ValueError(f'Invalid expression: {expression}') from e

        # Extract symbols from the expression
        symbols = self._expr.free_symbols
        symbol_names = sorted(str(s) for s in symbols)

        if 'x' not in symbol_names:
            raise ValueError("Expression must contain 'x' as independent variable")

        # Reject unknown functions early so invalid expressions fail at init,
        # not later during numerical evaluation.
        allowed_function_names = set(self._ALLOWED_FUNCS) | {
            func.__name__ for func in self._ALLOWED_FUNCS.values()
        }

        # Walk all function-call nodes in the parsed expression (e.g. sin(x), foo(x)).
        # Keep only function names that are not in our allowlist.
        unknown_function_names: set[str] = set()
        function_atoms = self._expr.atoms(sp.Function)
        for function_atom in function_atoms:
            function_name = function_atom.func.__name__
            if function_name not in allowed_function_names:
                unknown_function_names.add(function_name)

        unknown_functions = sorted(unknown_function_names)

        if unknown_functions:
            raise ValueError(
                f'Unsupported function(s) in expression: {", ".join(unknown_functions)}'
            )

        # Create parameters
        if parameters is not None and not isinstance(parameters, dict):
            raise TypeError(
                f'Parameters must be None or a dictionary, got {type(parameters).__name__}'
            )

        if parameters is not None:
            for name, value in parameters.items():
                if not isinstance(value, (Numeric, Parameter, dict)):
                    raise TypeError(
                        f"Parameter '{name}' must be numeric, "
                        f'a Parameter instance, or a dictionary, got {type(value).__name__}'
                    )
        parameters = parameters or {}
        self._parameters: dict[str, Parameter] = {}

        self._symbol_names = symbol_names
        for name in self._symbol_names:
            if name in self._RESERVED_NAMES:
                continue

            value = parameters.get(name, 1.0)
            if isinstance(value, Parameter):
                self._parameters[name] = value

            elif isinstance(value, dict) and value.get('@class') == 'Parameter':
                self._parameters[name] = Parameter.from_dict(value)
            else:
                self._parameters[name] = Parameter(
                    name=name,
                    value=value,
                    unit=self._unit,
                )

        # Create numerical function
        ordered_symbols = [sp.Symbol(name) for name in self._symbol_names]

        self._func = sp.lambdify(
            ordered_symbols,
            self._expr,
            modules=[{'erf': erf}, 'numpy'],
        )

        # -------------------------
        # Properties
        # -------------------------

    @property
    def expression(self) -> str:
        """
        Return the original expression string.

        Returns
        -------
        str
             The original expression string provided at initialization.
        """
        return self._expression_str

    @expression.setter
    def expression(self, _new_expr: str) -> None:
        """
        Prevent changing the expression after initialization.

        Parameters
        ----------
        _new_expr : str
            New expression string (ignored).

        Raises
        ------
        AttributeError
            Always raised to prevent changing the expression.
        """
        raise AttributeError('Expression cannot be changed after initialization')

    def evaluate(
        self,
        x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
    ) -> np.ndarray:
        """
        Evaluate the expression for given x values.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            Input values for the independent variable.

        Returns
        -------
        np.ndarray
            Evaluated results.
        """
        x = self._prepare_x_for_evaluate(x)

        args = []
        for name in self._symbol_names:
            if name == 'x':
                args.append(x)
            else:
                args.append(self._parameters[name].value)

        return self._func(*args)

    def get_all_variables(self) -> list[Parameter]:
        """
        Return all parameters.

        Returns
        -------
        list[Parameter]
            List of all parameters in the expression.
        """
        return list(self._parameters.values())

    def convert_unit(self, _new_unit: str | sc.Unit) -> None:
        """
        Convert the unit of the expression.

        Unit conversion is not implemented for ExpressionComponent.

        Parameters
        ----------
        _new_unit : str | sc.Unit
            The new unit to convert to (ignored).

        Raises
        ------
        NotImplementedError
            Always raised to indicate unit conversion is not supported.
        """

        raise NotImplementedError('Unit conversion is not implemented for ExpressionComponent')

    # -------------------------
    # dunder methods
    # -------------------------

    def __getattr__(self, name: str) -> Parameter:
        """
        Allow access to parameters as attributes.

        Parameters
        ----------
        name : str
            Name of the parameter to access.

        Raises
        ------
        AttributeError
            If the parameter does not exist.

        Returns
        -------
        Parameter
            The parameter with the given name.
        """
        if '_parameters' in self.__dict__ and name in self._parameters:
            return self._parameters[name]
        raise AttributeError(f"{self.__class__.__name__} has no attribute '{name}'")

    def __setattr__(self, name: str, value: Numeric) -> None:
        """
        Allow setting parameter values as attributes.

        Parameters
        ----------
        name : str
            Name of the parameter to set.
        value : Numeric
            New value for the parameter.

        Raises
        ------
        TypeError
            If the value is not numeric.
        """
        if '_parameters' in self.__dict__ and name in self._parameters:
            param = self._parameters[name]

            if not isinstance(value, Numeric):
                raise TypeError(f'{name} must be numeric')

            param.value = value
        else:
            # For other attributes, use default behavior
            super().__setattr__(name, value)

    def __dir__(self) -> list[str]:
        """
        Include parameter names in dir() output for better IDE support.

        Returns
        -------
        list[str]
            List of attribute names, including parameters.
        """
        return super().__dir__() + list(self._parameters.keys())

    def __repr__(self) -> str:
        """
        Return a string representation of the ExpressionComponent.

        Returns
        -------
        str
            String representation of the ExpressionComponent.
        """
        param_str = ', '.join(f'{k}={v.value}' for k, v in self._parameters.items())
        return (
            f'ExpressionComponent(name={self.name}, display_name={self.display_name}, '
            f'unit={self._unit},\n'
            f"    expr='{self._expression_str}',\n"
            f'    parameters={{ {param_str} }} )'
        )

expression property writable

Return the original expression string.

Returns:

Type	Description
str	The original expression string provided at initialization.

__init__(expression, parameters=None, unit='meV', name='Expression', display_name=None, unique_name=None)

Initialize the ExpressionComponent.

Parameters:

Name	Type	Description	Default
expression	str	The symbolic expression as a string. Must contain 'x' as the independent variable.	required
parameters	dict[str, Numeric] | None	Dictionary of parameter names and their initial values.	None
unit	str | sc.Unit	Unit of the output.	'meV'
name	str	Name of the component for indexing.	'Expression'
display_name	str | None	Display name for the component.	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'.
TypeError	If any parameter value is not numeric.

Examples:

>>> expr = ExpressionComponent(
...     'A * exp(-(x - x0)**2 / (2*sigma**2))',
...     parameters={'A': 10, 'x0': 0, 'sigma': 1},
...     unit='meV',
...     display_name='Gaussian Peak',
... )

>>> expr.A = 5
>>> y = expr.evaluate(x)

Source code in src/easydynamics/sample_model/components/expression_component.py

def __init__(
    self,
    expression: str,
    parameters: dict[str, Numeric] | None = None,
    unit: str | sc.Unit = 'meV',
    name: str = 'Expression',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the ExpressionComponent.

    Parameters
    ----------
    expression : str
        The symbolic expression as a string. Must contain 'x' as the independent variable.
    parameters : dict[str, Numeric] | None, default=None
        Dictionary of parameter names and their initial values.
    unit : str | sc.Unit, default='meV'
        Unit of the output.
    name : str, default='Expression'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name for the component.
    unique_name : str | None, default=None
        Unique name for the component.

    Raises
    ------
    ValueError
        If the expression is invalid or does not contain 'x'.
    TypeError
        If any parameter value is not numeric.

    Examples
    --------
    >>> expr = ExpressionComponent(
    ...     'A * exp(-(x - x0)**2 / (2*sigma**2))',
    ...     parameters={'A': 10, 'x0': 0, 'sigma': 1},
    ...     unit='meV',
    ...     display_name='Gaussian Peak',
    ... )

    >>> expr.A = 5
    >>> y = expr.evaluate(x)
    """
    super().__init__(unit=unit, name=name, display_name=display_name, unique_name=unique_name)

    if 'np.' in expression:
        raise ValueError(
            'NumPy syntax (np.*) is not supported. '
            "Use functions like 'exp', 'sin', etc. directly."
        )

    self._expression_str = expression

    locals_dict = {}
    locals_dict.update(self._ALLOWED_FUNCS)
    locals_dict.update(self._ALLOWED_CONSTANTS)

    try:
        self._expr = sp.sympify(expression, locals=locals_dict)
    except Exception as e:
        raise ValueError(f'Invalid expression: {expression}') from e

    # Extract symbols from the expression
    symbols = self._expr.free_symbols
    symbol_names = sorted(str(s) for s in symbols)

    if 'x' not in symbol_names:
        raise ValueError("Expression must contain 'x' as independent variable")

    # Reject unknown functions early so invalid expressions fail at init,
    # not later during numerical evaluation.
    allowed_function_names = set(self._ALLOWED_FUNCS) | {
        func.__name__ for func in self._ALLOWED_FUNCS.values()
    }

    # Walk all function-call nodes in the parsed expression (e.g. sin(x), foo(x)).
    # Keep only function names that are not in our allowlist.
    unknown_function_names: set[str] = set()
    function_atoms = self._expr.atoms(sp.Function)
    for function_atom in function_atoms:
        function_name = function_atom.func.__name__
        if function_name not in allowed_function_names:
            unknown_function_names.add(function_name)

    unknown_functions = sorted(unknown_function_names)

    if unknown_functions:
        raise ValueError(
            f'Unsupported function(s) in expression: {", ".join(unknown_functions)}'
        )

    # Create parameters
    if parameters is not None and not isinstance(parameters, dict):
        raise TypeError(
            f'Parameters must be None or a dictionary, got {type(parameters).__name__}'
        )

    if parameters is not None:
        for name, value in parameters.items():
            if not isinstance(value, (Numeric, Parameter, dict)):
                raise TypeError(
                    f"Parameter '{name}' must be numeric, "
                    f'a Parameter instance, or a dictionary, got {type(value).__name__}'
                )
    parameters = parameters or {}
    self._parameters: dict[str, Parameter] = {}

    self._symbol_names = symbol_names
    for name in self._symbol_names:
        if name in self._RESERVED_NAMES:
            continue

        value = parameters.get(name, 1.0)
        if isinstance(value, Parameter):
            self._parameters[name] = value

        elif isinstance(value, dict) and value.get('@class') == 'Parameter':
            self._parameters[name] = Parameter.from_dict(value)
        else:
            self._parameters[name] = Parameter(
                name=name,
                value=value,
                unit=self._unit,
            )

    # Create numerical function
    ordered_symbols = [sp.Symbol(name) for name in self._symbol_names]

    self._func = sp.lambdify(
        ordered_symbols,
        self._expr,
        modules=[{'erf': erf}, 'numpy'],
    )

evaluate(x)

Evaluate the expression for given x values.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	Input values for the independent variable.	required

Returns:

Type	Description
np.ndarray	Evaluated results.

Source code in src/easydynamics/sample_model/components/expression_component.py

def evaluate(
    self,
    x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
) -> np.ndarray:
    """
    Evaluate the expression for given x values.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        Input values for the independent variable.

    Returns
    -------
    np.ndarray
        Evaluated results.
    """
    x = self._prepare_x_for_evaluate(x)

    args = []
    for name in self._symbol_names:
        if name == 'x':
            args.append(x)
        else:
            args.append(self._parameters[name].value)

    return self._func(*args)

get_all_variables()

Return all parameters.

Returns:

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

Source code in src/easydynamics/sample_model/components/expression_component.py

def get_all_variables(self) -> list[Parameter]:
    """
    Return all parameters.

    Returns
    -------
    list[Parameter]
        List of all parameters in the expression.
    """
    return list(self._parameters.values())

convert_unit(_new_unit)

Convert the unit of the expression.

Unit conversion is not implemented for ExpressionComponent.

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.

Source code in src/easydynamics/sample_model/components/expression_component.py

def convert_unit(self, _new_unit: str | sc.Unit) -> None:
    """
    Convert the unit of the expression.

    Unit conversion is not implemented for ExpressionComponent.

    Parameters
    ----------
    _new_unit : str | sc.Unit
        The new unit to convert to (ignored).

    Raises
    ------
    NotImplementedError
        Always raised to indicate unit conversion is not supported.
    """

    raise NotImplementedError('Unit conversion is not implemented for ExpressionComponent')

__getattr__(name)

Allow access to parameters as attributes.

Parameters:

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

Raises:

Type	Description
AttributeError	If the parameter does not exist.

Returns:

Type	Description
Parameter	The parameter with the given name.

Source code in src/easydynamics/sample_model/components/expression_component.py

def __getattr__(self, name: str) -> Parameter:
    """
    Allow access to parameters as attributes.

    Parameters
    ----------
    name : str
        Name of the parameter to access.

    Raises
    ------
    AttributeError
        If the parameter does not exist.

    Returns
    -------
    Parameter
        The parameter with the given name.
    """
    if '_parameters' in self.__dict__ and name in self._parameters:
        return self._parameters[name]
    raise AttributeError(f"{self.__class__.__name__} has no attribute '{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
TypeError	If the value is not numeric.

Source code in src/easydynamics/sample_model/components/expression_component.py

def __setattr__(self, name: str, value: Numeric) -> None:
    """
    Allow setting parameter values as attributes.

    Parameters
    ----------
    name : str
        Name of the parameter to set.
    value : Numeric
        New value for the parameter.

    Raises
    ------
    TypeError
        If the value is not numeric.
    """
    if '_parameters' in self.__dict__ and name in self._parameters:
        param = self._parameters[name]

        if not isinstance(value, Numeric):
            raise TypeError(f'{name} must be numeric')

        param.value = value
    else:
        # For other attributes, use default behavior
        super().__setattr__(name, value)

__dir__()

Include parameter names in dir() output for better IDE support.

Returns:

Type	Description
list[str]	List of attribute names, including parameters.

Source code in src/easydynamics/sample_model/components/expression_component.py

def __dir__(self) -> list[str]:
    """
    Include parameter names in dir() output for better IDE support.

    Returns
    -------
    list[str]
        List of attribute names, including parameters.
    """
    return super().__dir__() + list(self._parameters.keys())

__repr__()

Return a string representation of the ExpressionComponent.

Returns:

Type	Description
str	String representation of the ExpressionComponent.

Source code in src/easydynamics/sample_model/components/expression_component.py

def __repr__(self) -> str:
    """
    Return a string representation of the ExpressionComponent.

    Returns
    -------
    str
        String representation of the ExpressionComponent.
    """
    param_str = ', '.join(f'{k}={v.value}' for k, v in self._parameters.items())
    return (
        f'ExpressionComponent(name={self.name}, display_name={self.display_name}, '
        f'unit={self._unit},\n'
        f"    expr='{self._expression_str}',\n"
        f'    parameters={{ {param_str} }} )'
    )

Gaussian

Bases: CreateParametersMixin, ModelComponent

Model of a Gaussian function.

The intensity is given by

$$ 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.

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

Source code in src/easydynamics/sample_model/components/gaussian.py

class Gaussian(CreateParametersMixin, ModelComponent):
    r"""
    Model of a Gaussian function.

     The intensity is given by

     $$ 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.

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

    def __init__(
        self,
        area: Numeric | Parameter = 1.0,
        center: Numeric | Parameter | None = None,
        width: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'Gaussian',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Gaussian component.

        Parameters
        ----------
        area : Numeric | Parameter, default=1.0
            Area of the Gaussian.
        center : Numeric | Parameter | None, default=None
            Center of the Gaussian. If None.
        width : Numeric | Parameter, default=1.0
            Standard deviation.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='Gaussian'
            Name of the component for indexing.
        display_name : str | None, default=None
            Name of the component.
        unique_name : str | None, default=None
            Unique name of the component. if None, a unique_name is automatically generated. By
            default, None.
        """
        # Validate inputs and create Parameters if not given
        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )
        width = self._create_width_parameter(width=width, name=name, unit=self._unit)

        self._area = area
        self._center = center
        self._width = width

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """

        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """

        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """

        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the center parameter value.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter. If None, defaults to 0 and is fixed.

        Raises
        ------
        TypeError
            If the value is not a number or None.
        """

        if value is None:
            value = 0.0
            self._center.fixed = True
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    @property
    def width(self) -> Parameter:
        """
        Get the width parameter (standard deviation).

        Returns
        -------
        Parameter
            The width parameter.
        """
        return self._width

    @width.setter
    def width(self, value: Numeric) -> None:
        """
        Set the width parameter value.

        Parameters
        ----------
        value : Numeric
            The new value for the width parameter.

        Raises
        ------
        TypeError
            If the value is not a number or None.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('width must be a number')

        if float(value) <= 0:
            raise ValueError('width must be positive')

        self._width.value = value

    def evaluate(
        self,
        x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
    ) -> np.ndarray:
        r"""
        Evaluate the Gaussian at the given x values.

        If x is a scipp Variable, the unit of the Gaussian will be converted to match x. The
        intensity is given by $$ 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.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Gaussian.

        Returns
        -------
        np.ndarray
            The intensity of the Gaussian at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        normalization = 1 / (np.sqrt(2 * np.pi) * self.width.value)
        exponent = -0.5 * ((x - self.center.value) / self.width.value) ** 2

        return self.area.value * normalization * np.exp(exponent)

    def __repr__(self) -> str:
        """
        Return a string representation of the Gaussian.

        Returns
        -------
        str
            A string representation of the Gaussian.
        """

        return (
            f'Gaussian(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n'
            f'    area = {self.area},\n'
            f'    center = {self.center},\n'
            f'    width = {self.width})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

width property writable

Get the width parameter (standard deviation).

Returns:

Type	Description
Parameter	The width parameter.

__init__(area=1.0, center=None, width=1.0, unit='meV', name='Gaussian', display_name=None, unique_name=None)

Initialize the Gaussian component.

Parameters:

Name	Type	Description	Default
area	Numeric | Parameter	Area of the Gaussian.	1.0
center	Numeric | Parameter | None	Center of the Gaussian. If None.	None
width	Numeric | Parameter	Standard deviation.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'Gaussian'
display_name	str | None	Name of the component.	None
unique_name	str | None	Unique name of the component. if None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/gaussian.py

def __init__(
    self,
    area: Numeric | Parameter = 1.0,
    center: Numeric | Parameter | None = None,
    width: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'Gaussian',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Gaussian component.

    Parameters
    ----------
    area : Numeric | Parameter, default=1.0
        Area of the Gaussian.
    center : Numeric | Parameter | None, default=None
        Center of the Gaussian. If None.
    width : Numeric | Parameter, default=1.0
        Standard deviation.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='Gaussian'
        Name of the component for indexing.
    display_name : str | None, default=None
        Name of the component.
    unique_name : str | None, default=None
        Unique name of the component. if None, a unique_name is automatically generated. By
        default, None.
    """
    # Validate inputs and create Parameters if not given
    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )
    width = self._create_width_parameter(width=width, name=name, unit=self._unit)

    self._area = area
    self._center = center
    self._width = width

evaluate(x)

Evaluate the Gaussian at the given x values.

If x is a scipp Variable, the unit of the Gaussian will be converted to match x. The intensity is given by $$ 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.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Gaussian.	required

Returns:

Type	Description
np.ndarray	The intensity of the Gaussian at the given x values.

Source code in src/easydynamics/sample_model/components/gaussian.py

def evaluate(
    self,
    x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
) -> np.ndarray:
    r"""
    Evaluate the Gaussian at the given x values.

    If x is a scipp Variable, the unit of the Gaussian will be converted to match x. The
    intensity is given by $$ 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.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Gaussian.

    Returns
    -------
    np.ndarray
        The intensity of the Gaussian at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    normalization = 1 / (np.sqrt(2 * np.pi) * self.width.value)
    exponent = -0.5 * ((x - self.center.value) / self.width.value) ** 2

    return self.area.value * normalization * np.exp(exponent)

__repr__()

Return a string representation of the Gaussian.

Returns:

Type	Description
str	A string representation of the Gaussian.

Source code in src/easydynamics/sample_model/components/gaussian.py

def __repr__(self) -> str:
    """
    Return a string representation of the Gaussian.

    Returns
    -------
    str
        A string representation of the Gaussian.
    """

    return (
        f'Gaussian(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n'
        f'    area = {self.area},\n'
        f'    center = {self.center},\n'
        f'    width = {self.width})'
    )

Lorentzian

Bases: CreateParametersMixin, ModelComponent

Model of a Lorentzian function.

The intensity is given by $$ 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 half width at half maximum (HWHM).

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

Source code in src/easydynamics/sample_model/components/lorentzian.py

class Lorentzian(CreateParametersMixin, ModelComponent):
    r"""
    Model of a Lorentzian function.

    The intensity is given by $$ 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 half width at half maximum
    (HWHM).

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

    def __init__(
        self,
        area: Numeric | Parameter = 1.0,
        center: Numeric | Parameter | None = None,
        width: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'Lorentzian',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Lorentzian component.

        Parameters
        ----------
        area : Numeric | Parameter, default=1.0
            Area of the Lorentzian.
        center : Numeric | Parameter | None, default=None
            Center of the Lorentzian. If None, defaults to 0 and is fixed.
        width : Numeric | Parameter, default=1.0
            Half width at half maximum (HWHM).
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='Lorentzian'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name for the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.
        """

        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )
        width = self._create_width_parameter(width=width, name=name, unit=self._unit)

        self._area = area
        self._center = center
        self._width = width

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """
        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """
        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the value of the center parameter.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter. If None, defaults to 0 and is fixed.

        Raises
        ------
        TypeError
            If the value is not a number or None.
        """

        if value is None:
            value = 0.0
            self._center.fixed = True
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    @property
    def width(self) -> Parameter:
        """
        Get the width parameter (HWHM).

        Returns
        -------
        Parameter
            The width parameter.
        """
        return self._width

    @width.setter
    def width(self, value: Numeric) -> None:
        """
        Set the width parameter value (HWHM).

        Parameters
        ----------
        value : Numeric
            The new value for the width parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('width must be a number')

        if float(value) <= 0:
            raise ValueError('width must be positive')
        self._width.value = value

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        r"""
        Evaluate the Lorentzian at the given x values.

        If x is a scipp Variable, the unit of the Lorentzian will be converted to match x. The
        intensity is given by

        $$ 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 half width at half maximum
        (HWHM).

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Lorentzian.

        Returns
        -------
        np.ndarray
            The intensity of the Lorentzian at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        normalization = self.width.value / np.pi
        denominator = (x - self.center.value) ** 2 + self.width.value**2

        return self.area.value * normalization / denominator

    def __repr__(self) -> str:
        """
        Return a string representation of the Lorentzian.

        Returns
        -------
        str
            A string representation of the Lorentzian.
        """
        return (
            f'Lorentzian(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n'
            f'    area = {self.area},\n'
            f'    center = {self.center},\n'
            f'    width = {self.width})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

width property writable

Get the width parameter (HWHM).

Returns:

Type	Description
Parameter	The width parameter.

__init__(area=1.0, center=None, width=1.0, unit='meV', name='Lorentzian', display_name=None, unique_name=None)

Initialize the Lorentzian component.

Parameters:

Name	Type	Description	Default
area	Numeric | Parameter	Area of the Lorentzian.	1.0
center	Numeric | Parameter | None	Center of the Lorentzian. If None, defaults to 0 and is fixed.	None
width	Numeric | Parameter	Half width at half maximum (HWHM).	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'Lorentzian'
display_name	str | None	Display name for the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/lorentzian.py

def __init__(
    self,
    area: Numeric | Parameter = 1.0,
    center: Numeric | Parameter | None = None,
    width: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'Lorentzian',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Lorentzian component.

    Parameters
    ----------
    area : Numeric | Parameter, default=1.0
        Area of the Lorentzian.
    center : Numeric | Parameter | None, default=None
        Center of the Lorentzian. If None, defaults to 0 and is fixed.
    width : Numeric | Parameter, default=1.0
        Half width at half maximum (HWHM).
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='Lorentzian'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name for the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.
    """

    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )
    width = self._create_width_parameter(width=width, name=name, unit=self._unit)

    self._area = area
    self._center = center
    self._width = width

evaluate(x)

Evaluate the Lorentzian at the given x values.

If x is a scipp Variable, the unit of the Lorentzian will be converted to match x. The intensity is given by

\[ 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 half width at half maximum (HWHM).

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Lorentzian.	required

Returns:

Type	Description
np.ndarray	The intensity of the Lorentzian at the given x values.

Source code in src/easydynamics/sample_model/components/lorentzian.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    r"""
    Evaluate the Lorentzian at the given x values.

    If x is a scipp Variable, the unit of the Lorentzian will be converted to match x. The
    intensity is given by

    $$ 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 half width at half maximum
    (HWHM).

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Lorentzian.

    Returns
    -------
    np.ndarray
        The intensity of the Lorentzian at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    normalization = self.width.value / np.pi
    denominator = (x - self.center.value) ** 2 + self.width.value**2

    return self.area.value * normalization / denominator

__repr__()

Return a string representation of the Lorentzian.

Returns:

Type	Description
str	A string representation of the Lorentzian.

Source code in src/easydynamics/sample_model/components/lorentzian.py

def __repr__(self) -> str:
    """
    Return a string representation of the Lorentzian.

    Returns
    -------
    str
        A string representation of the Lorentzian.
    """
    return (
        f'Lorentzian(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n'
        f'    area = {self.area},\n'
        f'    center = {self.center},\n'
        f'    width = {self.width})'
    )

Polynomial

Bases: ModelComponent

Polynomial function component.

The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ... + c_N x^N, $$ where \(C_i\) are the coefficients.

Source code in src/easydynamics/sample_model/components/polynomial.py

class Polynomial(ModelComponent):
    r"""
    Polynomial function component.

    The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ... + c_N x^N, $$ where $C_i$ are
    the coefficients.
    """

    def __init__(
        self,
        coefficients: Sequence[Numeric | Parameter] = (0.0,),
        unit: str | sc.Unit = 'meV',
        name: str = 'Polynomial',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Polynomial component.

        Parameters
        ----------
        coefficients : Sequence[Numeric | Parameter], default=(0.0,)
            Coefficients c0, c1, ..., cN.
        unit : str | sc.Unit, default='meV'
            Unit of the Polynomial component.
        name : str, default='Polynomial'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the Polynomial component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.

        Raises
        ------
        TypeError
            If coefficients is not a sequence of numbers or Parameters or if any item in
            coefficients is not a number or Parameter.
        ValueError
            If coefficients is an empty sequence.
        """

        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        if not isinstance(coefficients, (list, tuple, np.ndarray)):
            raise TypeError(
                'coefficients must be a sequence (list/tuple/ndarray) \
                    of numbers or Parameter objects.'
            )

        if len(coefficients) == 0:
            raise ValueError('At least one coefficient must be provided.')

        # Internal storage of Parameter objects
        self._coefficients: list[Parameter] = []

        # Coefficients are treated as dimensionless Parameters
        for i, coef in enumerate(coefficients):
            if isinstance(coef, Parameter):
                param = coef
            elif isinstance(coef, Numeric):
                param = Parameter(name=f'{name}_c{i}', value=float(coef))
            else:
                raise TypeError('Each coefficient must be either a numeric value or a Parameter.')
            self._coefficients.append(param)

        # Helper scipp scalar to track unit conversions
        # (value initialized to 1 with provided unit)
        self._unit_conversion_helper = sc.scalar(value=1.0, unit=unit)

    @property
    def coefficients(self) -> list[Parameter]:
        """
        Get the coefficients of the polynomial as a list of Parameters.

        Returns
        -------
        list[Parameter]
            The coefficients of the polynomial.
        """
        return list(self._coefficients)

    @coefficients.setter
    def coefficients(self, coeffs: Sequence[Numeric | Parameter]) -> None:
        """
        Set the coefficients of the polynomial.

        Length must match current number of coefficients.

        Parameters
        ----------
        coeffs : Sequence[Numeric | Parameter]
            New coefficients as a sequence of numbers or Parameters.

        Raises
        ------
        TypeError
            If coeffs is not a sequence of numbers or Parameters or if any item in coeffs is not a
            number or Parameter.
        ValueError
            If the length of coeffs does not match the existing number of coefficients.
        """
        if not isinstance(coeffs, (list, tuple, np.ndarray)):
            raise TypeError(
                'coefficients must be a sequence (list/tuple/ndarray) of numbers or Parameter .'
            )
        if len(coeffs) != len(self._coefficients):
            raise ValueError(
                'Number of coefficients must match the existing number of coefficients.'
            )
        for i, coef in enumerate(coeffs):
            if isinstance(coef, Parameter):
                # replace parameter
                self._coefficients[i] = coef
            elif isinstance(coef, Numeric):
                self._coefficients[i].value = float(coef)
            else:
                raise TypeError('Each coefficient must be either a numeric value or a Parameter.')

    def coefficient_values(self) -> list[float]:
        """
        Get the coefficients of the polynomial as a list.

        Returns
        -------
        list[float]
            The coefficient values of the polynomial.
        """
        return [param.value for param in self._coefficients]

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        r"""
        Evaluate the Polynomial at the given x values.

        The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ...
        + c_N x^N, $$ where $C_i$ are the coefficients.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Polynomial.

        Returns
        -------
        np.ndarray
            The evaluated Polynomial at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        result = np.zeros_like(x, dtype=float)
        for i, param in enumerate(self._coefficients):
            result += param.value * np.power(x, i)

        if any(result < 0):
            warnings.warn(
                f'The Polynomial with unique_name {self.unique_name} has negative values, '
                'which may not be physically meaningful.',
                UserWarning,
                stacklevel=2,
            )
        return result

    @property
    def degree(self) -> int:
        """
        Get the degree of the polynomial.

        Returns
        -------
        int
            The degree of the polynomial.
        """
        return len(self._coefficients) - 1

    @degree.setter
    def degree(self, _value: int) -> None:
        """
        The degree is determined by the number of coefficients and cannot be set directly.

        Parameters
        ----------
        _value : int
            The new degree of the polynomial.

        Raises
        ------
        AttributeError
            Always raised since degree cannot be set directly.
        """
        raise AttributeError(
            'The degree of the polynomial is determined by the number of coefficients '
            'and cannot be set directly.'
        )

    def get_all_variables(self) -> list[DescriptorBase]:
        """
        Get all variables from the model component.

        Returns
        -------
        list[DescriptorBase]
            List of variables in the component.
        """
        return list(self._coefficients)

    def convert_unit(self, unit: str | sc.Unit) -> None:
        """
        Convert the unit of the polynomial.

        Parameters
        ----------
        unit : str | sc.Unit
            The target unit to convert to.

        Raises
        ------
        UnitError
            If the provided unit is not a string or sc.Unit.
        """

        if not isinstance(unit, (str, sc.Unit)):
            raise UnitError('unit must be a string or a scipp unit.')

        # Find out how much the unit changes
        # by converting a helper variable
        conversion_value_before = self._unit_conversion_helper.value
        self._unit_conversion_helper = sc.to_unit(self._unit_conversion_helper, unit=unit)
        conversion_value_after = self._unit_conversion_helper.value
        for i, param in enumerate(self._coefficients):
            param.value *= (
                conversion_value_before / conversion_value_after
            ) ** i  # set the values directly to the appropriate power

        self._unit = unit

    def __repr__(self) -> str:
        """
        Return a string representation of the Polynomial.

        Returns
        -------
        str
            A string representation of the Polynomial.
        """

        coeffs_str = ', '.join(f'{param.name}={param.value}' for param in self._coefficients)
        return (
            f'Polynomial(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n'
            f'    coefficients = [{coeffs_str}])'
        )

coefficients property writable

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

Returns:

Type	Description
list[Parameter]	The coefficients of the polynomial.

degree property writable

Get the degree of the polynomial.

Returns:

Type	Description
int	The degree of the polynomial.

__init__(coefficients=(0.0,), unit='meV', name='Polynomial', display_name=None, unique_name=None)

Initialize the Polynomial component.

Parameters:

Name	Type	Description	Default
coefficients	Sequence[Numeric | Parameter]	Coefficients c0, c1, ..., cN.	(0.0,)
unit	str | sc.Unit	Unit of the Polynomial component.	'meV'
name	str	Name of the component for indexing.	'Polynomial'
display_name	str | None	Display name of the Polynomial component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Raises:

Type	Description
TypeError	If coefficients is not a sequence of numbers or Parameters or if any item in coefficients is not a number or Parameter.
ValueError	If coefficients is an empty sequence.

Source code in src/easydynamics/sample_model/components/polynomial.py

def __init__(
    self,
    coefficients: Sequence[Numeric | Parameter] = (0.0,),
    unit: str | sc.Unit = 'meV',
    name: str = 'Polynomial',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Polynomial component.

    Parameters
    ----------
    coefficients : Sequence[Numeric | Parameter], default=(0.0,)
        Coefficients c0, c1, ..., cN.
    unit : str | sc.Unit, default='meV'
        Unit of the Polynomial component.
    name : str, default='Polynomial'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the Polynomial component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.

    Raises
    ------
    TypeError
        If coefficients is not a sequence of numbers or Parameters or if any item in
        coefficients is not a number or Parameter.
    ValueError
        If coefficients is an empty sequence.
    """

    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    if not isinstance(coefficients, (list, tuple, np.ndarray)):
        raise TypeError(
            'coefficients must be a sequence (list/tuple/ndarray) \
                of numbers or Parameter objects.'
        )

    if len(coefficients) == 0:
        raise ValueError('At least one coefficient must be provided.')

    # Internal storage of Parameter objects
    self._coefficients: list[Parameter] = []

    # Coefficients are treated as dimensionless Parameters
    for i, coef in enumerate(coefficients):
        if isinstance(coef, Parameter):
            param = coef
        elif isinstance(coef, Numeric):
            param = Parameter(name=f'{name}_c{i}', value=float(coef))
        else:
            raise TypeError('Each coefficient must be either a numeric value or a Parameter.')
        self._coefficients.append(param)

    # Helper scipp scalar to track unit conversions
    # (value initialized to 1 with provided unit)
    self._unit_conversion_helper = sc.scalar(value=1.0, unit=unit)

coefficient_values()

Get the coefficients of the polynomial as a list.

Returns:

Type	Description
list[float]	The coefficient values of the polynomial.

Source code in src/easydynamics/sample_model/components/polynomial.py

def coefficient_values(self) -> list[float]:
    """
    Get the coefficients of the polynomial as a list.

    Returns
    -------
    list[float]
        The coefficient values of the polynomial.
    """
    return [param.value for param in self._coefficients]

evaluate(x)

Evaluate the Polynomial at the given x values.

The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ... + c_N x^N, $$ where \(C_i\) are the coefficients.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Polynomial.	required

Returns:

Type	Description
np.ndarray	The evaluated Polynomial at the given x values.

Source code in src/easydynamics/sample_model/components/polynomial.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    r"""
    Evaluate the Polynomial at the given x values.

    The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ...
    + c_N x^N, $$ where $C_i$ are the coefficients.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Polynomial.

    Returns
    -------
    np.ndarray
        The evaluated Polynomial at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    result = np.zeros_like(x, dtype=float)
    for i, param in enumerate(self._coefficients):
        result += param.value * np.power(x, i)

    if any(result < 0):
        warnings.warn(
            f'The Polynomial with unique_name {self.unique_name} has negative values, '
            'which may not be physically meaningful.',
            UserWarning,
            stacklevel=2,
        )
    return result

get_all_variables()

Get all variables from the model component.

Returns:

Type	Description
list[DescriptorBase]	List of variables in the component.

Source code in src/easydynamics/sample_model/components/polynomial.py

def get_all_variables(self) -> list[DescriptorBase]:
    """
    Get all variables from the model component.

    Returns
    -------
    list[DescriptorBase]
        List of variables in the component.
    """
    return list(self._coefficients)

convert_unit(unit)

Convert the unit of the polynomial.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The target unit to convert to.	required

Raises:

Type	Description
UnitError	If the provided unit is not a string or sc.Unit.

Source code in src/easydynamics/sample_model/components/polynomial.py

def convert_unit(self, unit: str | sc.Unit) -> None:
    """
    Convert the unit of the polynomial.

    Parameters
    ----------
    unit : str | sc.Unit
        The target unit to convert to.

    Raises
    ------
    UnitError
        If the provided unit is not a string or sc.Unit.
    """

    if not isinstance(unit, (str, sc.Unit)):
        raise UnitError('unit must be a string or a scipp unit.')

    # Find out how much the unit changes
    # by converting a helper variable
    conversion_value_before = self._unit_conversion_helper.value
    self._unit_conversion_helper = sc.to_unit(self._unit_conversion_helper, unit=unit)
    conversion_value_after = self._unit_conversion_helper.value
    for i, param in enumerate(self._coefficients):
        param.value *= (
            conversion_value_before / conversion_value_after
        ) ** i  # set the values directly to the appropriate power

    self._unit = unit

__repr__()

Return a string representation of the Polynomial.

Returns:

Type	Description
str	A string representation of the Polynomial.

Source code in src/easydynamics/sample_model/components/polynomial.py

def __repr__(self) -> str:
    """
    Return a string representation of the Polynomial.

    Returns
    -------
    str
        A string representation of the Polynomial.
    """

    coeffs_str = ', '.join(f'{param.name}={param.value}' for param in self._coefficients)
    return (
        f'Polynomial(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n'
        f'    coefficients = [{coeffs_str}])'
    )

Voigt

Bases: CreateParametersMixin, ModelComponent

Voigt profile, a convolution of Gaussian and Lorentzian.

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

Use scipy.special.voigt_profile to evaluate the Voigt profile.

Source code in src/easydynamics/sample_model/components/voigt.py

class Voigt(CreateParametersMixin, ModelComponent):
    r"""
    Voigt profile, a convolution of Gaussian and Lorentzian.

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

    Use scipy.special.voigt_profile to evaluate the Voigt profile.
    """

    def __init__(
        self,
        area: Numeric | Parameter = 1.0,
        center: Numeric | Parameter | None = None,
        gaussian_width: Numeric | Parameter = 1.0,
        lorentzian_width: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'Voigt',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize a Voigt component.

        Parameters
        ----------
        area : Numeric | Parameter, default=1.0
            Total area under the curve.
        center : Numeric | Parameter | None, default=None
            Center of the Voigt profile.
        gaussian_width : Numeric | Parameter, default=1.0
            Standard deviation of the Gaussian part.
        lorentzian_width : Numeric | Parameter, default=1.0
            Half width at half max (HWHM) of the Lorentzian part.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='Voigt'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.
        """

        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )
        gaussian_width = self._create_width_parameter(
            width=gaussian_width,
            name=name,
            param_name='gaussian_width',
            unit=self._unit,
        )
        lorentzian_width = self._create_width_parameter(
            width=lorentzian_width,
            name=name,
            param_name='lorentzian_width',
            unit=self._unit,
        )

        self._area = area
        self._center = center
        self._gaussian_width = gaussian_width
        self._lorentzian_width = lorentzian_width

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """
        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """
        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the value of the center parameter.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter. If None, defaults to 0 and is fixed.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if value is None:
            value = 0.0
            self._center.fixed = True
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    @property
    def gaussian_width(self) -> Parameter:
        """
        Get the Gaussian width parameter.

        Returns
        -------
        Parameter
            The Gaussian width parameter.
        """
        return self._gaussian_width

    @gaussian_width.setter
    def gaussian_width(self, value: Numeric) -> None:
        """
        Set the width parameter value.

        Parameters
        ----------
        value : Numeric
            The new value for the width parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('gaussian_width must be a number')
        if float(value) <= 0:
            raise ValueError('gaussian_width must be positive')
        self._gaussian_width.value = value

    @property
    def lorentzian_width(self) -> Parameter:
        """
        Get the Lorentzian width parameter (HWHM).

        Returns
        -------
        Parameter
            The Lorentzian width parameter.
        """
        return self._lorentzian_width

    @lorentzian_width.setter
    def lorentzian_width(self, value: Numeric) -> None:
        """
        Set the value of the Lorentzian width parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the Lorentzian width parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('lorentzian_width must be a number')
        if float(value) <= 0:
            raise ValueError('lorentzian_width must be positive')
        self._lorentzian_width.value = value

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        r"""
        Evaluate the Voigt at the given x values.

        If x is a scipp Variable, the unit of the Voigt will be converted to match x. The Voigt
        evaluates to the convolution of a Gaussian with sigma gaussian_width and a Lorentzian with
        half width at half max lorentzian_width, centered at center, with area equal to area.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Voigt.

        Returns
        -------
        np.ndarray
            The intensity of the Voigt at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        return self.area.value * voigt_profile(
            x - self.center.value,
            self.gaussian_width.value,
            self.lorentzian_width.value,
        )

    def __repr__(self) -> str:
        """
        Return a string representation of the Voigt.

        Returns
        -------
        str
            A string representation of the Voigt.
        """

        return (
            f'Voigt(name = {self.name}, display_name = {self.display_name}, unit = {self._unit},\n'
            f'    area = {self.area},\n'
            f'    center = {self.center},\n'
            f'    gaussian_width = {self.gaussian_width},\n'
            f'    lorentzian_width = {self.lorentzian_width})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

gaussian_width property writable

Get the Gaussian width parameter.

Returns:

Type	Description
Parameter	The Gaussian width parameter.

lorentzian_width property writable

Get the Lorentzian width parameter (HWHM).

Returns:

Type	Description
Parameter	The Lorentzian width parameter.

__init__(area=1.0, center=None, gaussian_width=1.0, lorentzian_width=1.0, unit='meV', name='Voigt', display_name=None, unique_name=None)

Initialize a Voigt component.

Parameters:

Name	Type	Description	Default
area	Numeric | Parameter	Total area under the curve.	1.0
center	Numeric | Parameter | None	Center of the Voigt profile.	None
gaussian_width	Numeric | Parameter	Standard deviation of the Gaussian part.	1.0
lorentzian_width	Numeric | Parameter	Half width at half max (HWHM) of the Lorentzian part.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'Voigt'
display_name	str | None	Display name of the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/voigt.py

def __init__(
    self,
    area: Numeric | Parameter = 1.0,
    center: Numeric | Parameter | None = None,
    gaussian_width: Numeric | Parameter = 1.0,
    lorentzian_width: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'Voigt',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize a Voigt component.

    Parameters
    ----------
    area : Numeric | Parameter, default=1.0
        Total area under the curve.
    center : Numeric | Parameter | None, default=None
        Center of the Voigt profile.
    gaussian_width : Numeric | Parameter, default=1.0
        Standard deviation of the Gaussian part.
    lorentzian_width : Numeric | Parameter, default=1.0
        Half width at half max (HWHM) of the Lorentzian part.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='Voigt'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.
    """

    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )
    gaussian_width = self._create_width_parameter(
        width=gaussian_width,
        name=name,
        param_name='gaussian_width',
        unit=self._unit,
    )
    lorentzian_width = self._create_width_parameter(
        width=lorentzian_width,
        name=name,
        param_name='lorentzian_width',
        unit=self._unit,
    )

    self._area = area
    self._center = center
    self._gaussian_width = gaussian_width
    self._lorentzian_width = lorentzian_width

evaluate(x)

Evaluate the Voigt at the given x values.

If x is a scipp Variable, the unit of the Voigt will be converted to match x. The Voigt evaluates to the convolution of a Gaussian with sigma gaussian_width and a Lorentzian with half width at half max lorentzian_width, centered at center, with area equal to area.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Voigt.	required

Returns:

Type	Description
np.ndarray	The intensity of the Voigt at the given x values.

Source code in src/easydynamics/sample_model/components/voigt.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    r"""
    Evaluate the Voigt at the given x values.

    If x is a scipp Variable, the unit of the Voigt will be converted to match x. The Voigt
    evaluates to the convolution of a Gaussian with sigma gaussian_width and a Lorentzian with
    half width at half max lorentzian_width, centered at center, with area equal to area.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Voigt.

    Returns
    -------
    np.ndarray
        The intensity of the Voigt at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    return self.area.value * voigt_profile(
        x - self.center.value,
        self.gaussian_width.value,
        self.lorentzian_width.value,
    )

__repr__()

Return a string representation of the Voigt.

Returns:

Type	Description
str	A string representation of the Voigt.

Source code in src/easydynamics/sample_model/components/voigt.py

def __repr__(self) -> str:
    """
    Return a string representation of the Voigt.

    Returns
    -------
    str
        A string representation of the Voigt.
    """

    return (
        f'Voigt(name = {self.name}, display_name = {self.display_name}, unit = {self._unit},\n'
        f'    area = {self.area},\n'
        f'    center = {self.center},\n'
        f'    gaussian_width = {self.gaussian_width},\n'
        f'    lorentzian_width = {self.lorentzian_width})'
    )

damped_harmonic_oscillator

DampedHarmonicOscillator

Bases: CreateParametersMixin, ModelComponent

Model of a Damped Harmonic Oscillator (DHO).

The intensity is given by $$ 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, \(x_0\) is the center, and \(\gamma\) is the width.

Source code in src/easydynamics/sample_model/components/damped_harmonic_oscillator.py

class DampedHarmonicOscillator(CreateParametersMixin, ModelComponent):
    r"""
    Model of a Damped Harmonic Oscillator (DHO).

    The intensity is given by $$ 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, $x_0$ is the center, and $\gamma$ is the width.
    """

    def __init__(
        self,
        area: Numeric | Parameter = 1.0,
        center: Numeric | Parameter = 1.0,
        width: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'DampedHarmonicOscillator',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Damped Harmonic Oscillator.

        Parameters
        ----------
        area : Numeric | Parameter, default=1.0
            Area under the curve.
        center : Numeric | Parameter, default=1.0
            Resonance frequency, approximately the peak position.
        width : Numeric | Parameter, default=1.0
            Damping constant, approximately the half width at half max (HWHM) of the peaks. By
            default, 1.0.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='DampedHarmonicOscillator'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.
        """

        super().__init__(
            name=name,
            display_name=display_name,
            unique_name=unique_name,
            unit=unit,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center,
            name=name,
            fix_if_none=False,
            unit=self._unit,
            enforce_minimum_center=True,
        )

        width = self._create_width_parameter(width=width, name=name, unit=self._unit)

        self._area = area
        self._center = center
        self._width = width

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """
        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """
        return self._center

    @center.setter
    def center(self, value: Numeric) -> None:
        """
        Set the value of the center parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the center parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')

        if float(value) <= 0:
            raise ValueError('center must be positive')
        self._center.value = value

    @property
    def width(self) -> Parameter:
        """
        Get the width parameter.

        Returns
        -------
        Parameter
            The width parameter.
        """
        return self._width

    @width.setter
    def width(self, value: Numeric) -> None:
        """
        Set the value of the width parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the width parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('width must be a number')

        if float(value) <= 0:
            raise ValueError('width must be positive')

        self._width.value = value

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        r"""
        Evaluate the Damped Harmonic Oscillator at the given x values.

        If x is a scipp Variable, the unit of the DHO will be converted to match x. The intensity
        is given by $$ 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, $x_0$ is the center, and $\gamma$ is the width.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the DHO.

        Returns
        -------
        np.ndarray
            The intensity of the DHO at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        normalization = 2 * self.center.value**2 * self.width.value / np.pi
        # No division by zero here, width>0 enforced in setter
        denominator = (x**2 - self.center.value**2) ** 2 + (2 * self.width.value * x) ** 2

        return self.area.value * normalization / (denominator)

    def __repr__(self) -> str:
        """
        Return a string representation of the Damped Harmonic Oscillator.

        Returns
        -------
        str
            A string representation of the Damped Harmonic Oscillator.
        """
        return (
            f'DampedHarmonicOscillator(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n '
            f'    area = {self.area},\n '
            f'    center = {self.center},\n '
            f'    width = {self.width})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

width property writable

Get the width parameter.

Returns:

Type	Description
Parameter	The width parameter.

__init__(area=1.0, center=1.0, width=1.0, unit='meV', name='DampedHarmonicOscillator', display_name=None, unique_name=None)

Initialize the Damped Harmonic Oscillator.

Parameters:

Name	Type	Description	Default
area	Numeric | Parameter	Area under the curve.	1.0
center	Numeric | Parameter	Resonance frequency, approximately the peak position.	1.0
width	Numeric | Parameter	Damping constant, approximately the half width at half max (HWHM) of the peaks. By default, 1.0.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'DampedHarmonicOscillator'
display_name	str | None	Display name of the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/damped_harmonic_oscillator.py

def __init__(
    self,
    area: Numeric | Parameter = 1.0,
    center: Numeric | Parameter = 1.0,
    width: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'DampedHarmonicOscillator',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Damped Harmonic Oscillator.

    Parameters
    ----------
    area : Numeric | Parameter, default=1.0
        Area under the curve.
    center : Numeric | Parameter, default=1.0
        Resonance frequency, approximately the peak position.
    width : Numeric | Parameter, default=1.0
        Damping constant, approximately the half width at half max (HWHM) of the peaks. By
        default, 1.0.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='DampedHarmonicOscillator'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.
    """

    super().__init__(
        name=name,
        display_name=display_name,
        unique_name=unique_name,
        unit=unit,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center,
        name=name,
        fix_if_none=False,
        unit=self._unit,
        enforce_minimum_center=True,
    )

    width = self._create_width_parameter(width=width, name=name, unit=self._unit)

    self._area = area
    self._center = center
    self._width = width

evaluate(x)

Evaluate the Damped Harmonic Oscillator at the given x values.

If x is a scipp Variable, the unit of the DHO will be converted to match x. The intensity is given by $$ 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, \(x_0\) is the center, and \(\gamma\) is the width.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the DHO.	required

Returns:

Type	Description
np.ndarray	The intensity of the DHO at the given x values.

Source code in src/easydynamics/sample_model/components/damped_harmonic_oscillator.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    r"""
    Evaluate the Damped Harmonic Oscillator at the given x values.

    If x is a scipp Variable, the unit of the DHO will be converted to match x. The intensity
    is given by $$ 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, $x_0$ is the center, and $\gamma$ is the width.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the DHO.

    Returns
    -------
    np.ndarray
        The intensity of the DHO at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    normalization = 2 * self.center.value**2 * self.width.value / np.pi
    # No division by zero here, width>0 enforced in setter
    denominator = (x**2 - self.center.value**2) ** 2 + (2 * self.width.value * x) ** 2

    return self.area.value * normalization / (denominator)

__repr__()

Return a string representation of the Damped Harmonic Oscillator.

Returns:

Type	Description
str	A string representation of the Damped Harmonic Oscillator.

Source code in src/easydynamics/sample_model/components/damped_harmonic_oscillator.py

def __repr__(self) -> str:
    """
    Return a string representation of the Damped Harmonic Oscillator.

    Returns
    -------
    str
        A string representation of the Damped Harmonic Oscillator.
    """
    return (
        f'DampedHarmonicOscillator(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n '
        f'    area = {self.area},\n '
        f'    center = {self.center},\n '
        f'    width = {self.width})'
    )

delta_function

DeltaFunction

Bases: CreateParametersMixin, ModelComponent

Delta function.

Evaluates to zero everywhere, except in convolutions, where it acts as an identity. This is handled by the Convolution method. If the center is not provided, it will be centered at 0 and fixed, which is typically what you want in QENS.

Source code in src/easydynamics/sample_model/components/delta_function.py

class DeltaFunction(CreateParametersMixin, ModelComponent):
    """
    Delta function.

    Evaluates to zero everywhere, except in convolutions, where it acts as an identity. This is
    handled by the Convolution method. If the center is not provided, it will be centered at 0 and
    fixed, which is typically what you want in QENS.
    """

    def __init__(
        self,
        center: Numeric | Parameter | None = None,
        area: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'DeltaFunction',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Delta function.

        Parameters
        ----------
        center : Numeric | Parameter | None, default=None
            Center of the delta function. If None, it will be centered at 0 and fixed.
        area : Numeric | Parameter, default=1.0
            Total area under the curve.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='DeltaFunction'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.
        """
        # Validate inputs and create Parameters if not given
        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )

        self._area = area
        self._center = center

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """

        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """

        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """

        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the center parameter value.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter. If None, defaults to 0 and is fixed.

        Raises
        ------
        TypeError
            If the value is not a number or None.
        """

        if value is None:
            value = 0.0
            self._center.fixed = True
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        """
        Evaluate the Delta function at the given x values.

        The Delta function evaluates to zero everywhere, except at the center. Its numerical
        integral is equal to the area. It acts as an identity in convolutions.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Delta function.

        Returns
        -------
        np.ndarray
            The evaluated Delta function at the given x values.
        """

        # x assumed sorted, 1D numpy array
        x = self._prepare_x_for_evaluate(x)
        model = np.zeros_like(x, dtype=float)
        center = self.center.value
        area = self.area.value

        if x.min() - EPSILON <= center <= x.max() + EPSILON:
            # nearest index
            i = np.argmin(np.abs(x - center))

            # left half-width
            if i == 0:  # noqa: SIM108
                left = x[1] - x[0] if x.size > 1 else 0.5
            else:
                left = x[i] - x[i - 1]

            # right half-width
            if i == x.size - 1:  # noqa: SIM108
                right = x[-1] - x[-2] if x.size > 1 else 0.5
            else:
                right = x[i + 1] - x[i]

            # effective bin width: half left + half right
            bin_width = 0.5 * (left + right)

            model[i] = area / bin_width

        return model

    def __repr__(self) -> str:
        """
        Return a string representation of the Delta function.

        Returns
        -------
        str
            A string representation of the Delta function.
        """

        return (
            f'DeltaFunction(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self.unit},\n'
            f'    area = {self.area},\n'
            f'    center = {self.center})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

__init__(center=None, area=1.0, unit='meV', name='DeltaFunction', display_name=None, unique_name=None)

Initialize the Delta function.

Parameters:

Name	Type	Description	Default
center	Numeric | Parameter | None	Center of the delta function. If None, it will be centered at 0 and fixed.	None
area	Numeric | Parameter	Total area under the curve.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'DeltaFunction'
display_name	str | None	Display name of the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/delta_function.py

def __init__(
    self,
    center: Numeric | Parameter | None = None,
    area: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'DeltaFunction',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Delta function.

    Parameters
    ----------
    center : Numeric | Parameter | None, default=None
        Center of the delta function. If None, it will be centered at 0 and fixed.
    area : Numeric | Parameter, default=1.0
        Total area under the curve.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='DeltaFunction'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.
    """
    # Validate inputs and create Parameters if not given
    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )

    self._area = area
    self._center = center

evaluate(x)

Evaluate the Delta function at the given x values.

The Delta function evaluates to zero everywhere, except at the center. Its numerical integral is equal to the area. It acts as an identity in convolutions.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Delta function.	required

Returns:

Type	Description
np.ndarray	The evaluated Delta function at the given x values.

Source code in src/easydynamics/sample_model/components/delta_function.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    """
    Evaluate the Delta function at the given x values.

    The Delta function evaluates to zero everywhere, except at the center. Its numerical
    integral is equal to the area. It acts as an identity in convolutions.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Delta function.

    Returns
    -------
    np.ndarray
        The evaluated Delta function at the given x values.
    """

    # x assumed sorted, 1D numpy array
    x = self._prepare_x_for_evaluate(x)
    model = np.zeros_like(x, dtype=float)
    center = self.center.value
    area = self.area.value

    if x.min() - EPSILON <= center <= x.max() + EPSILON:
        # nearest index
        i = np.argmin(np.abs(x - center))

        # left half-width
        if i == 0:  # noqa: SIM108
            left = x[1] - x[0] if x.size > 1 else 0.5
        else:
            left = x[i] - x[i - 1]

        # right half-width
        if i == x.size - 1:  # noqa: SIM108
            right = x[-1] - x[-2] if x.size > 1 else 0.5
        else:
            right = x[i + 1] - x[i]

        # effective bin width: half left + half right
        bin_width = 0.5 * (left + right)

        model[i] = area / bin_width

    return model

__repr__()

Return a string representation of the Delta function.

Returns:

Type	Description
str	A string representation of the Delta function.

Source code in src/easydynamics/sample_model/components/delta_function.py

def __repr__(self) -> str:
    """
    Return a string representation of the Delta function.

    Returns
    -------
    str
        A string representation of the Delta function.
    """

    return (
        f'DeltaFunction(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self.unit},\n'
        f'    area = {self.area},\n'
        f'    center = {self.center})'
    )

exponential

Exponential

Bases: CreateParametersMixin, ModelComponent

Model of an exponential function.

The intensity is given by

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

where \(A\) is the amplitude, \(x_0\) is the center, and \(B\) describes the rate of decay or growth.

Source code in src/easydynamics/sample_model/components/exponential.py

class Exponential(CreateParametersMixin, ModelComponent):
    r"""
    Model of an exponential function.

    The intensity is given by

    $$ I(x) = A e^{B (x-x_0)}, $$

    where $A$ is the amplitude, $x_0$ is the center, and $B$ describes the rate of decay or growth.
    """

    def __init__(
        self,
        amplitude: Numeric | Parameter = 1.0,
        center: Numeric | Parameter | None = None,
        rate: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'Exponential',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Exponential component.

        Parameters
        ----------
        amplitude : Numeric | Parameter, default=1.0
            Amplitude of the Exponential.
        center : Numeric | Parameter | None, default=None
            Center of the Exponential. If None, the center is fixed at 0.
        rate : Numeric | Parameter, default=1.0
            Decay or growth constant of the Exponential.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='Exponential'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.

        Raises
        ------
        TypeError
            If amplitude, center, or rate are not numbers or Parameters.
        ValueError
            If amplitude, center or rate are not finite numbers.
        """
        # Validate inputs and create Parameters if not given
        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        if not isinstance(amplitude, (Parameter, Numeric)):
            raise TypeError('amplitude must be a number or a Parameter.')

        if isinstance(amplitude, Numeric):
            if not np.isfinite(amplitude):
                raise ValueError('amplitude must be a finite number or a Parameter')

            amplitude = Parameter(name=name + ' amplitude', value=float(amplitude), unit=unit)

        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )

        if not isinstance(rate, (Parameter, Numeric)):
            raise TypeError('rate must be a number or a Parameter.')

        if isinstance(rate, Numeric):
            if not np.isfinite(rate):
                raise ValueError('rate must be a finite number or a Parameter')

            rate = Parameter(name=name + ' rate', value=float(rate), unit='1/' + str(unit))

        self._amplitude = amplitude
        self._center = center
        self._rate = rate

    @property
    def amplitude(self) -> Parameter:
        """
        Get the amplitude parameter.

        Returns
        -------
        Parameter
            The amplitude parameter.
        """

        return self._amplitude

    @amplitude.setter
    def amplitude(self, value: Numeric) -> None:
        """
        Set the value of the amplitude parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the amplitude parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """

        if not isinstance(value, Numeric):
            raise TypeError('amplitude must be a number')
        self._amplitude.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """

        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the center parameter value.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """

        if value is None:
            value = 0.0
            self._center.fixed = True

        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    @property
    def rate(self) -> Parameter:
        """
        Get the rate parameter.

        Returns
        -------
        Parameter
            The rate parameter.
        """
        return self._rate

    @rate.setter
    def rate(self, value: Numeric) -> None:
        """
        Set the rate parameter value.

        Parameters
        ----------
        value : Numeric
            The new value for the rate parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError('rate must be a number')

        self._rate.value = value

    def evaluate(
        self,
        x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
    ) -> np.ndarray:
        r"""
        Evaluate the Exponential at the given x values.

        If x is a scipp Variable, the unit of the Exponential will be converted to match x. The
        intensity is given by $$ I(x) = A \exp\left( r (x - x_0) \right) $$

        where $A$ is the amplitude, $x_0$ is the center, and $r$ is the rate.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Exponential.

        Returns
        -------
        np.ndarray
            The intensity of the Exponential at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)
        exponent = self.rate.value * (x - self.center.value)

        return self.amplitude.value * np.exp(exponent)

    def convert_unit(self, unit: str | sc.Unit) -> None:
        """
        Convert the unit of the Parameters in the component.

        Parameters
        ----------
        unit : str | sc.Unit
            The new unit to convert to.

        Raises
        ------
        TypeError
            If unit is not a string or sc.Unit.
        Exception
            If conversion fails for any parameter.
        """

        if not isinstance(unit, (str, sc.Unit)):
            raise TypeError('unit must be a string or sc.Unit')

        old_unit = self._unit
        pars = [self.amplitude, self.center]
        try:
            for p in pars:
                p.convert_unit(unit)
            self.rate.convert_unit('1/' + str(unit))
            self._unit = unit
        except Exception as e:
            # Attempt to rollback on failure
            try:
                for p in pars:
                    p.convert_unit(old_unit)
                self.rate.convert_unit('1/' + str(old_unit))
            except Exception:  # noqa: S110
                pass  # Best effort rollback
            raise e

    def __repr__(self) -> str:
        """
        Return a string representation of the Exponential.

        Returns
        -------
        str
            A string representation of the Exponential.
        """

        return (
            f'Exponential(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n '
            f'    amplitude = {self.amplitude},\n '
            f'    center = {self.center},\n '
            f'    rate = {self.rate})'
        )

amplitude property writable

Get the amplitude parameter.

Returns:

Type	Description
Parameter	The amplitude parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

rate property writable

Get the rate parameter.

Returns:

Type	Description
Parameter	The rate parameter.

__init__(amplitude=1.0, center=None, rate=1.0, unit='meV', name='Exponential', display_name=None, unique_name=None)

Initialize the Exponential component.

Parameters:

Name	Type	Description	Default
amplitude	Numeric | Parameter	Amplitude of the Exponential.	1.0
center	Numeric | Parameter | None	Center of the Exponential. If None, the center is fixed at 0.	None
rate	Numeric | Parameter	Decay or growth constant of the Exponential.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'Exponential'
display_name	str | None	Display name of the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Raises:

Type	Description
TypeError	If amplitude, center, or rate are not numbers or Parameters.
ValueError	If amplitude, center or rate are not finite numbers.

Source code in src/easydynamics/sample_model/components/exponential.py

def __init__(
    self,
    amplitude: Numeric | Parameter = 1.0,
    center: Numeric | Parameter | None = None,
    rate: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'Exponential',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Exponential component.

    Parameters
    ----------
    amplitude : Numeric | Parameter, default=1.0
        Amplitude of the Exponential.
    center : Numeric | Parameter | None, default=None
        Center of the Exponential. If None, the center is fixed at 0.
    rate : Numeric | Parameter, default=1.0
        Decay or growth constant of the Exponential.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='Exponential'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.

    Raises
    ------
    TypeError
        If amplitude, center, or rate are not numbers or Parameters.
    ValueError
        If amplitude, center or rate are not finite numbers.
    """
    # Validate inputs and create Parameters if not given
    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    if not isinstance(amplitude, (Parameter, Numeric)):
        raise TypeError('amplitude must be a number or a Parameter.')

    if isinstance(amplitude, Numeric):
        if not np.isfinite(amplitude):
            raise ValueError('amplitude must be a finite number or a Parameter')

        amplitude = Parameter(name=name + ' amplitude', value=float(amplitude), unit=unit)

    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )

    if not isinstance(rate, (Parameter, Numeric)):
        raise TypeError('rate must be a number or a Parameter.')

    if isinstance(rate, Numeric):
        if not np.isfinite(rate):
            raise ValueError('rate must be a finite number or a Parameter')

        rate = Parameter(name=name + ' rate', value=float(rate), unit='1/' + str(unit))

    self._amplitude = amplitude
    self._center = center
    self._rate = rate

evaluate(x)

Evaluate the Exponential at the given x values.

If x is a scipp Variable, the unit of the Exponential will be converted to match x. The intensity is given by $$ I(x) = A \exp\left( r (x - x_0) \right) $$

where \(A\) is the amplitude, \(x_0\) is the center, and \(r\) is the rate.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Exponential.	required

Returns:

Type	Description
np.ndarray	The intensity of the Exponential at the given x values.

Source code in src/easydynamics/sample_model/components/exponential.py

def evaluate(
    self,
    x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
) -> np.ndarray:
    r"""
    Evaluate the Exponential at the given x values.

    If x is a scipp Variable, the unit of the Exponential will be converted to match x. The
    intensity is given by $$ I(x) = A \exp\left( r (x - x_0) \right) $$

    where $A$ is the amplitude, $x_0$ is the center, and $r$ is the rate.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Exponential.

    Returns
    -------
    np.ndarray
        The intensity of the Exponential at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)
    exponent = self.rate.value * (x - self.center.value)

    return self.amplitude.value * np.exp(exponent)

convert_unit(unit)

Convert the unit of the Parameters in the component.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The new unit to convert to.	required

Raises:

Type	Description
TypeError	If unit is not a string or sc.Unit.
Exception	If conversion fails for any parameter.

Source code in src/easydynamics/sample_model/components/exponential.py

def convert_unit(self, unit: str | sc.Unit) -> None:
    """
    Convert the unit of the Parameters in the component.

    Parameters
    ----------
    unit : str | sc.Unit
        The new unit to convert to.

    Raises
    ------
    TypeError
        If unit is not a string or sc.Unit.
    Exception
        If conversion fails for any parameter.
    """

    if not isinstance(unit, (str, sc.Unit)):
        raise TypeError('unit must be a string or sc.Unit')

    old_unit = self._unit
    pars = [self.amplitude, self.center]
    try:
        for p in pars:
            p.convert_unit(unit)
        self.rate.convert_unit('1/' + str(unit))
        self._unit = unit
    except Exception as e:
        # Attempt to rollback on failure
        try:
            for p in pars:
                p.convert_unit(old_unit)
            self.rate.convert_unit('1/' + str(old_unit))
        except Exception:  # noqa: S110
            pass  # Best effort rollback
        raise e

__repr__()

Return a string representation of the Exponential.

Returns:

Type	Description
str	A string representation of the Exponential.

Source code in src/easydynamics/sample_model/components/exponential.py

def __repr__(self) -> str:
    """
    Return a string representation of the Exponential.

    Returns
    -------
    str
        A string representation of the Exponential.
    """

    return (
        f'Exponential(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n '
        f'    amplitude = {self.amplitude},\n '
        f'    center = {self.center},\n '
        f'    rate = {self.rate})'
    )

expression_component

ExpressionComponent

Bases: ModelComponent

Model component defined by a symbolic expression.

Source code in src/easydynamics/sample_model/components/expression_component.py

class ExpressionComponent(ModelComponent):
    """
    Model component defined by a symbolic expression.
    """

    # -------------------------
    # Allowed symbolic functions
    # -------------------------
    _ALLOWED_FUNCS: ClassVar[dict[str, object]] = {
        # Exponentials & logs
        'exp': sp.exp,
        'log': sp.log,
        'ln': sp.log,
        'sqrt': sp.sqrt,
        # Trigonometric
        'sin': sp.sin,
        'cos': sp.cos,
        'tan': sp.tan,
        'sinc': sp.sinc,
        'cot': sp.cot,
        'sec': sp.sec,
        'csc': sp.csc,
        'asin': sp.asin,
        'acos': sp.acos,
        'atan': sp.atan,
        # Hyperbolic
        'sinh': sp.sinh,
        'cosh': sp.cosh,
        'tanh': sp.tanh,
        # Misc
        'abs': sp.Abs,
        'sign': sp.sign,
        'floor': sp.floor,
        'ceil': sp.ceiling,
        # Special functions
        'erf': sp.erf,
    }

    # -------------------------
    # Allowed constants
    # -------------------------
    _ALLOWED_CONSTANTS: ClassVar[dict[str, object]] = {
        'pi': sp.pi,
        'E': sp.E,
    }

    _RESERVED_NAMES: ClassVar[dict[str, object]] = {'x'}

    def __init__(
        self,
        expression: str,
        parameters: dict[str, Numeric] | None = None,
        unit: str | sc.Unit = 'meV',
        name: str = 'Expression',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the ExpressionComponent.

        Parameters
        ----------
        expression : str
            The symbolic expression as a string. Must contain 'x' as the independent variable.
        parameters : dict[str, Numeric] | None, default=None
            Dictionary of parameter names and their initial values.
        unit : str | sc.Unit, default='meV'
            Unit of the output.
        name : str, default='Expression'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name for the component.
        unique_name : str | None, default=None
            Unique name for the component.

        Raises
        ------
        ValueError
            If the expression is invalid or does not contain 'x'.
        TypeError
            If any parameter value is not numeric.

        Examples
        --------
        >>> expr = ExpressionComponent(
        ...     'A * exp(-(x - x0)**2 / (2*sigma**2))',
        ...     parameters={'A': 10, 'x0': 0, 'sigma': 1},
        ...     unit='meV',
        ...     display_name='Gaussian Peak',
        ... )

        >>> expr.A = 5
        >>> y = expr.evaluate(x)
        """
        super().__init__(unit=unit, name=name, display_name=display_name, unique_name=unique_name)

        if 'np.' in expression:
            raise ValueError(
                'NumPy syntax (np.*) is not supported. '
                "Use functions like 'exp', 'sin', etc. directly."
            )

        self._expression_str = expression

        locals_dict = {}
        locals_dict.update(self._ALLOWED_FUNCS)
        locals_dict.update(self._ALLOWED_CONSTANTS)

        try:
            self._expr = sp.sympify(expression, locals=locals_dict)
        except Exception as e:
            raise ValueError(f'Invalid expression: {expression}') from e

        # Extract symbols from the expression
        symbols = self._expr.free_symbols
        symbol_names = sorted(str(s) for s in symbols)

        if 'x' not in symbol_names:
            raise ValueError("Expression must contain 'x' as independent variable")

        # Reject unknown functions early so invalid expressions fail at init,
        # not later during numerical evaluation.
        allowed_function_names = set(self._ALLOWED_FUNCS) | {
            func.__name__ for func in self._ALLOWED_FUNCS.values()
        }

        # Walk all function-call nodes in the parsed expression (e.g. sin(x), foo(x)).
        # Keep only function names that are not in our allowlist.
        unknown_function_names: set[str] = set()
        function_atoms = self._expr.atoms(sp.Function)
        for function_atom in function_atoms:
            function_name = function_atom.func.__name__
            if function_name not in allowed_function_names:
                unknown_function_names.add(function_name)

        unknown_functions = sorted(unknown_function_names)

        if unknown_functions:
            raise ValueError(
                f'Unsupported function(s) in expression: {", ".join(unknown_functions)}'
            )

        # Create parameters
        if parameters is not None and not isinstance(parameters, dict):
            raise TypeError(
                f'Parameters must be None or a dictionary, got {type(parameters).__name__}'
            )

        if parameters is not None:
            for name, value in parameters.items():
                if not isinstance(value, (Numeric, Parameter, dict)):
                    raise TypeError(
                        f"Parameter '{name}' must be numeric, "
                        f'a Parameter instance, or a dictionary, got {type(value).__name__}'
                    )
        parameters = parameters or {}
        self._parameters: dict[str, Parameter] = {}

        self._symbol_names = symbol_names
        for name in self._symbol_names:
            if name in self._RESERVED_NAMES:
                continue

            value = parameters.get(name, 1.0)
            if isinstance(value, Parameter):
                self._parameters[name] = value

            elif isinstance(value, dict) and value.get('@class') == 'Parameter':
                self._parameters[name] = Parameter.from_dict(value)
            else:
                self._parameters[name] = Parameter(
                    name=name,
                    value=value,
                    unit=self._unit,
                )

        # Create numerical function
        ordered_symbols = [sp.Symbol(name) for name in self._symbol_names]

        self._func = sp.lambdify(
            ordered_symbols,
            self._expr,
            modules=[{'erf': erf}, 'numpy'],
        )

        # -------------------------
        # Properties
        # -------------------------

    @property
    def expression(self) -> str:
        """
        Return the original expression string.

        Returns
        -------
        str
             The original expression string provided at initialization.
        """
        return self._expression_str

    @expression.setter
    def expression(self, _new_expr: str) -> None:
        """
        Prevent changing the expression after initialization.

        Parameters
        ----------
        _new_expr : str
            New expression string (ignored).

        Raises
        ------
        AttributeError
            Always raised to prevent changing the expression.
        """
        raise AttributeError('Expression cannot be changed after initialization')

    def evaluate(
        self,
        x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
    ) -> np.ndarray:
        """
        Evaluate the expression for given x values.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            Input values for the independent variable.

        Returns
        -------
        np.ndarray
            Evaluated results.
        """
        x = self._prepare_x_for_evaluate(x)

        args = []
        for name in self._symbol_names:
            if name == 'x':
                args.append(x)
            else:
                args.append(self._parameters[name].value)

        return self._func(*args)

    def get_all_variables(self) -> list[Parameter]:
        """
        Return all parameters.

        Returns
        -------
        list[Parameter]
            List of all parameters in the expression.
        """
        return list(self._parameters.values())

    def convert_unit(self, _new_unit: str | sc.Unit) -> None:
        """
        Convert the unit of the expression.

        Unit conversion is not implemented for ExpressionComponent.

        Parameters
        ----------
        _new_unit : str | sc.Unit
            The new unit to convert to (ignored).

        Raises
        ------
        NotImplementedError
            Always raised to indicate unit conversion is not supported.
        """

        raise NotImplementedError('Unit conversion is not implemented for ExpressionComponent')

    # -------------------------
    # dunder methods
    # -------------------------

    def __getattr__(self, name: str) -> Parameter:
        """
        Allow access to parameters as attributes.

        Parameters
        ----------
        name : str
            Name of the parameter to access.

        Raises
        ------
        AttributeError
            If the parameter does not exist.

        Returns
        -------
        Parameter
            The parameter with the given name.
        """
        if '_parameters' in self.__dict__ and name in self._parameters:
            return self._parameters[name]
        raise AttributeError(f"{self.__class__.__name__} has no attribute '{name}'")

    def __setattr__(self, name: str, value: Numeric) -> None:
        """
        Allow setting parameter values as attributes.

        Parameters
        ----------
        name : str
            Name of the parameter to set.
        value : Numeric
            New value for the parameter.

        Raises
        ------
        TypeError
            If the value is not numeric.
        """
        if '_parameters' in self.__dict__ and name in self._parameters:
            param = self._parameters[name]

            if not isinstance(value, Numeric):
                raise TypeError(f'{name} must be numeric')

            param.value = value
        else:
            # For other attributes, use default behavior
            super().__setattr__(name, value)

    def __dir__(self) -> list[str]:
        """
        Include parameter names in dir() output for better IDE support.

        Returns
        -------
        list[str]
            List of attribute names, including parameters.
        """
        return super().__dir__() + list(self._parameters.keys())

    def __repr__(self) -> str:
        """
        Return a string representation of the ExpressionComponent.

        Returns
        -------
        str
            String representation of the ExpressionComponent.
        """
        param_str = ', '.join(f'{k}={v.value}' for k, v in self._parameters.items())
        return (
            f'ExpressionComponent(name={self.name}, display_name={self.display_name}, '
            f'unit={self._unit},\n'
            f"    expr='{self._expression_str}',\n"
            f'    parameters={{ {param_str} }} )'
        )

expression property writable

Return the original expression string.

Returns:

Type	Description
str	The original expression string provided at initialization.

__init__(expression, parameters=None, unit='meV', name='Expression', display_name=None, unique_name=None)

Initialize the ExpressionComponent.

Parameters:

Name	Type	Description	Default
expression	str	The symbolic expression as a string. Must contain 'x' as the independent variable.	required
parameters	dict[str, Numeric] | None	Dictionary of parameter names and their initial values.	None
unit	str | sc.Unit	Unit of the output.	'meV'
name	str	Name of the component for indexing.	'Expression'
display_name	str | None	Display name for the component.	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'.
TypeError	If any parameter value is not numeric.

Examples:

>>> expr = ExpressionComponent(
...     'A * exp(-(x - x0)**2 / (2*sigma**2))',
...     parameters={'A': 10, 'x0': 0, 'sigma': 1},
...     unit='meV',
...     display_name='Gaussian Peak',
... )

>>> expr.A = 5
>>> y = expr.evaluate(x)

Source code in src/easydynamics/sample_model/components/expression_component.py

def __init__(
    self,
    expression: str,
    parameters: dict[str, Numeric] | None = None,
    unit: str | sc.Unit = 'meV',
    name: str = 'Expression',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the ExpressionComponent.

    Parameters
    ----------
    expression : str
        The symbolic expression as a string. Must contain 'x' as the independent variable.
    parameters : dict[str, Numeric] | None, default=None
        Dictionary of parameter names and their initial values.
    unit : str | sc.Unit, default='meV'
        Unit of the output.
    name : str, default='Expression'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name for the component.
    unique_name : str | None, default=None
        Unique name for the component.

    Raises
    ------
    ValueError
        If the expression is invalid or does not contain 'x'.
    TypeError
        If any parameter value is not numeric.

    Examples
    --------
    >>> expr = ExpressionComponent(
    ...     'A * exp(-(x - x0)**2 / (2*sigma**2))',
    ...     parameters={'A': 10, 'x0': 0, 'sigma': 1},
    ...     unit='meV',
    ...     display_name='Gaussian Peak',
    ... )

    >>> expr.A = 5
    >>> y = expr.evaluate(x)
    """
    super().__init__(unit=unit, name=name, display_name=display_name, unique_name=unique_name)

    if 'np.' in expression:
        raise ValueError(
            'NumPy syntax (np.*) is not supported. '
            "Use functions like 'exp', 'sin', etc. directly."
        )

    self._expression_str = expression

    locals_dict = {}
    locals_dict.update(self._ALLOWED_FUNCS)
    locals_dict.update(self._ALLOWED_CONSTANTS)

    try:
        self._expr = sp.sympify(expression, locals=locals_dict)
    except Exception as e:
        raise ValueError(f'Invalid expression: {expression}') from e

    # Extract symbols from the expression
    symbols = self._expr.free_symbols
    symbol_names = sorted(str(s) for s in symbols)

    if 'x' not in symbol_names:
        raise ValueError("Expression must contain 'x' as independent variable")

    # Reject unknown functions early so invalid expressions fail at init,
    # not later during numerical evaluation.
    allowed_function_names = set(self._ALLOWED_FUNCS) | {
        func.__name__ for func in self._ALLOWED_FUNCS.values()
    }

    # Walk all function-call nodes in the parsed expression (e.g. sin(x), foo(x)).
    # Keep only function names that are not in our allowlist.
    unknown_function_names: set[str] = set()
    function_atoms = self._expr.atoms(sp.Function)
    for function_atom in function_atoms:
        function_name = function_atom.func.__name__
        if function_name not in allowed_function_names:
            unknown_function_names.add(function_name)

    unknown_functions = sorted(unknown_function_names)

    if unknown_functions:
        raise ValueError(
            f'Unsupported function(s) in expression: {", ".join(unknown_functions)}'
        )

    # Create parameters
    if parameters is not None and not isinstance(parameters, dict):
        raise TypeError(
            f'Parameters must be None or a dictionary, got {type(parameters).__name__}'
        )

    if parameters is not None:
        for name, value in parameters.items():
            if not isinstance(value, (Numeric, Parameter, dict)):
                raise TypeError(
                    f"Parameter '{name}' must be numeric, "
                    f'a Parameter instance, or a dictionary, got {type(value).__name__}'
                )
    parameters = parameters or {}
    self._parameters: dict[str, Parameter] = {}

    self._symbol_names = symbol_names
    for name in self._symbol_names:
        if name in self._RESERVED_NAMES:
            continue

        value = parameters.get(name, 1.0)
        if isinstance(value, Parameter):
            self._parameters[name] = value

        elif isinstance(value, dict) and value.get('@class') == 'Parameter':
            self._parameters[name] = Parameter.from_dict(value)
        else:
            self._parameters[name] = Parameter(
                name=name,
                value=value,
                unit=self._unit,
            )

    # Create numerical function
    ordered_symbols = [sp.Symbol(name) for name in self._symbol_names]

    self._func = sp.lambdify(
        ordered_symbols,
        self._expr,
        modules=[{'erf': erf}, 'numpy'],
    )

evaluate(x)

Evaluate the expression for given x values.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	Input values for the independent variable.	required

Returns:

Type	Description
np.ndarray	Evaluated results.

Source code in src/easydynamics/sample_model/components/expression_component.py

def evaluate(
    self,
    x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
) -> np.ndarray:
    """
    Evaluate the expression for given x values.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        Input values for the independent variable.

    Returns
    -------
    np.ndarray
        Evaluated results.
    """
    x = self._prepare_x_for_evaluate(x)

    args = []
    for name in self._symbol_names:
        if name == 'x':
            args.append(x)
        else:
            args.append(self._parameters[name].value)

    return self._func(*args)

get_all_variables()

Return all parameters.

Returns:

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

Source code in src/easydynamics/sample_model/components/expression_component.py

def get_all_variables(self) -> list[Parameter]:
    """
    Return all parameters.

    Returns
    -------
    list[Parameter]
        List of all parameters in the expression.
    """
    return list(self._parameters.values())

convert_unit(_new_unit)

Convert the unit of the expression.

Unit conversion is not implemented for ExpressionComponent.

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.

Source code in src/easydynamics/sample_model/components/expression_component.py

def convert_unit(self, _new_unit: str | sc.Unit) -> None:
    """
    Convert the unit of the expression.

    Unit conversion is not implemented for ExpressionComponent.

    Parameters
    ----------
    _new_unit : str | sc.Unit
        The new unit to convert to (ignored).

    Raises
    ------
    NotImplementedError
        Always raised to indicate unit conversion is not supported.
    """

    raise NotImplementedError('Unit conversion is not implemented for ExpressionComponent')

__getattr__(name)

Allow access to parameters as attributes.

Parameters:

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

Raises:

Type	Description
AttributeError	If the parameter does not exist.

Returns:

Type	Description
Parameter	The parameter with the given name.

Source code in src/easydynamics/sample_model/components/expression_component.py

def __getattr__(self, name: str) -> Parameter:
    """
    Allow access to parameters as attributes.

    Parameters
    ----------
    name : str
        Name of the parameter to access.

    Raises
    ------
    AttributeError
        If the parameter does not exist.

    Returns
    -------
    Parameter
        The parameter with the given name.
    """
    if '_parameters' in self.__dict__ and name in self._parameters:
        return self._parameters[name]
    raise AttributeError(f"{self.__class__.__name__} has no attribute '{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
TypeError	If the value is not numeric.

Source code in src/easydynamics/sample_model/components/expression_component.py

def __setattr__(self, name: str, value: Numeric) -> None:
    """
    Allow setting parameter values as attributes.

    Parameters
    ----------
    name : str
        Name of the parameter to set.
    value : Numeric
        New value for the parameter.

    Raises
    ------
    TypeError
        If the value is not numeric.
    """
    if '_parameters' in self.__dict__ and name in self._parameters:
        param = self._parameters[name]

        if not isinstance(value, Numeric):
            raise TypeError(f'{name} must be numeric')

        param.value = value
    else:
        # For other attributes, use default behavior
        super().__setattr__(name, value)

__dir__()

Include parameter names in dir() output for better IDE support.

Returns:

Type	Description
list[str]	List of attribute names, including parameters.

Source code in src/easydynamics/sample_model/components/expression_component.py

def __dir__(self) -> list[str]:
    """
    Include parameter names in dir() output for better IDE support.

    Returns
    -------
    list[str]
        List of attribute names, including parameters.
    """
    return super().__dir__() + list(self._parameters.keys())

__repr__()

Return a string representation of the ExpressionComponent.

Returns:

Type	Description
str	String representation of the ExpressionComponent.

Source code in src/easydynamics/sample_model/components/expression_component.py

def __repr__(self) -> str:
    """
    Return a string representation of the ExpressionComponent.

    Returns
    -------
    str
        String representation of the ExpressionComponent.
    """
    param_str = ', '.join(f'{k}={v.value}' for k, v in self._parameters.items())
    return (
        f'ExpressionComponent(name={self.name}, display_name={self.display_name}, '
        f'unit={self._unit},\n'
        f"    expr='{self._expression_str}',\n"
        f'    parameters={{ {param_str} }} )'
    )

gaussian

Gaussian

Bases: CreateParametersMixin, ModelComponent

Model of a Gaussian function.

The intensity is given by

$$ 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.

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

Source code in src/easydynamics/sample_model/components/gaussian.py

class Gaussian(CreateParametersMixin, ModelComponent):
    r"""
    Model of a Gaussian function.

     The intensity is given by

     $$ 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.

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

    def __init__(
        self,
        area: Numeric | Parameter = 1.0,
        center: Numeric | Parameter | None = None,
        width: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'Gaussian',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Gaussian component.

        Parameters
        ----------
        area : Numeric | Parameter, default=1.0
            Area of the Gaussian.
        center : Numeric | Parameter | None, default=None
            Center of the Gaussian. If None.
        width : Numeric | Parameter, default=1.0
            Standard deviation.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='Gaussian'
            Name of the component for indexing.
        display_name : str | None, default=None
            Name of the component.
        unique_name : str | None, default=None
            Unique name of the component. if None, a unique_name is automatically generated. By
            default, None.
        """
        # Validate inputs and create Parameters if not given
        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )
        width = self._create_width_parameter(width=width, name=name, unit=self._unit)

        self._area = area
        self._center = center
        self._width = width

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """

        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """

        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """

        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the center parameter value.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter. If None, defaults to 0 and is fixed.

        Raises
        ------
        TypeError
            If the value is not a number or None.
        """

        if value is None:
            value = 0.0
            self._center.fixed = True
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    @property
    def width(self) -> Parameter:
        """
        Get the width parameter (standard deviation).

        Returns
        -------
        Parameter
            The width parameter.
        """
        return self._width

    @width.setter
    def width(self, value: Numeric) -> None:
        """
        Set the width parameter value.

        Parameters
        ----------
        value : Numeric
            The new value for the width parameter.

        Raises
        ------
        TypeError
            If the value is not a number or None.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('width must be a number')

        if float(value) <= 0:
            raise ValueError('width must be positive')

        self._width.value = value

    def evaluate(
        self,
        x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
    ) -> np.ndarray:
        r"""
        Evaluate the Gaussian at the given x values.

        If x is a scipp Variable, the unit of the Gaussian will be converted to match x. The
        intensity is given by $$ 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.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Gaussian.

        Returns
        -------
        np.ndarray
            The intensity of the Gaussian at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        normalization = 1 / (np.sqrt(2 * np.pi) * self.width.value)
        exponent = -0.5 * ((x - self.center.value) / self.width.value) ** 2

        return self.area.value * normalization * np.exp(exponent)

    def __repr__(self) -> str:
        """
        Return a string representation of the Gaussian.

        Returns
        -------
        str
            A string representation of the Gaussian.
        """

        return (
            f'Gaussian(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n'
            f'    area = {self.area},\n'
            f'    center = {self.center},\n'
            f'    width = {self.width})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

width property writable

Get the width parameter (standard deviation).

Returns:

Type	Description
Parameter	The width parameter.

__init__(area=1.0, center=None, width=1.0, unit='meV', name='Gaussian', display_name=None, unique_name=None)

Initialize the Gaussian component.

Parameters:

Name	Type	Description	Default
area	Numeric | Parameter	Area of the Gaussian.	1.0
center	Numeric | Parameter | None	Center of the Gaussian. If None.	None
width	Numeric | Parameter	Standard deviation.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'Gaussian'
display_name	str | None	Name of the component.	None
unique_name	str | None	Unique name of the component. if None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/gaussian.py

def __init__(
    self,
    area: Numeric | Parameter = 1.0,
    center: Numeric | Parameter | None = None,
    width: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'Gaussian',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Gaussian component.

    Parameters
    ----------
    area : Numeric | Parameter, default=1.0
        Area of the Gaussian.
    center : Numeric | Parameter | None, default=None
        Center of the Gaussian. If None.
    width : Numeric | Parameter, default=1.0
        Standard deviation.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='Gaussian'
        Name of the component for indexing.
    display_name : str | None, default=None
        Name of the component.
    unique_name : str | None, default=None
        Unique name of the component. if None, a unique_name is automatically generated. By
        default, None.
    """
    # Validate inputs and create Parameters if not given
    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )
    width = self._create_width_parameter(width=width, name=name, unit=self._unit)

    self._area = area
    self._center = center
    self._width = width

evaluate(x)

Evaluate the Gaussian at the given x values.

If x is a scipp Variable, the unit of the Gaussian will be converted to match x. The intensity is given by $$ 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.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Gaussian.	required

Returns:

Type	Description
np.ndarray	The intensity of the Gaussian at the given x values.

Source code in src/easydynamics/sample_model/components/gaussian.py

def evaluate(
    self,
    x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
) -> np.ndarray:
    r"""
    Evaluate the Gaussian at the given x values.

    If x is a scipp Variable, the unit of the Gaussian will be converted to match x. The
    intensity is given by $$ 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.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Gaussian.

    Returns
    -------
    np.ndarray
        The intensity of the Gaussian at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    normalization = 1 / (np.sqrt(2 * np.pi) * self.width.value)
    exponent = -0.5 * ((x - self.center.value) / self.width.value) ** 2

    return self.area.value * normalization * np.exp(exponent)

__repr__()

Return a string representation of the Gaussian.

Returns:

Type	Description
str	A string representation of the Gaussian.

Source code in src/easydynamics/sample_model/components/gaussian.py

def __repr__(self) -> str:
    """
    Return a string representation of the Gaussian.

    Returns
    -------
    str
        A string representation of the Gaussian.
    """

    return (
        f'Gaussian(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n'
        f'    area = {self.area},\n'
        f'    center = {self.center},\n'
        f'    width = {self.width})'
    )

lorentzian

Lorentzian

Bases: CreateParametersMixin, ModelComponent

Model of a Lorentzian function.

The intensity is given by $$ 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 half width at half maximum (HWHM).

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

Source code in src/easydynamics/sample_model/components/lorentzian.py

class Lorentzian(CreateParametersMixin, ModelComponent):
    r"""
    Model of a Lorentzian function.

    The intensity is given by $$ 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 half width at half maximum
    (HWHM).

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

    def __init__(
        self,
        area: Numeric | Parameter = 1.0,
        center: Numeric | Parameter | None = None,
        width: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'Lorentzian',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Lorentzian component.

        Parameters
        ----------
        area : Numeric | Parameter, default=1.0
            Area of the Lorentzian.
        center : Numeric | Parameter | None, default=None
            Center of the Lorentzian. If None, defaults to 0 and is fixed.
        width : Numeric | Parameter, default=1.0
            Half width at half maximum (HWHM).
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='Lorentzian'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name for the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.
        """

        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )
        width = self._create_width_parameter(width=width, name=name, unit=self._unit)

        self._area = area
        self._center = center
        self._width = width

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """
        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """
        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the value of the center parameter.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter. If None, defaults to 0 and is fixed.

        Raises
        ------
        TypeError
            If the value is not a number or None.
        """

        if value is None:
            value = 0.0
            self._center.fixed = True
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    @property
    def width(self) -> Parameter:
        """
        Get the width parameter (HWHM).

        Returns
        -------
        Parameter
            The width parameter.
        """
        return self._width

    @width.setter
    def width(self, value: Numeric) -> None:
        """
        Set the width parameter value (HWHM).

        Parameters
        ----------
        value : Numeric
            The new value for the width parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('width must be a number')

        if float(value) <= 0:
            raise ValueError('width must be positive')
        self._width.value = value

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        r"""
        Evaluate the Lorentzian at the given x values.

        If x is a scipp Variable, the unit of the Lorentzian will be converted to match x. The
        intensity is given by

        $$ 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 half width at half maximum
        (HWHM).

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Lorentzian.

        Returns
        -------
        np.ndarray
            The intensity of the Lorentzian at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        normalization = self.width.value / np.pi
        denominator = (x - self.center.value) ** 2 + self.width.value**2

        return self.area.value * normalization / denominator

    def __repr__(self) -> str:
        """
        Return a string representation of the Lorentzian.

        Returns
        -------
        str
            A string representation of the Lorentzian.
        """
        return (
            f'Lorentzian(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n'
            f'    area = {self.area},\n'
            f'    center = {self.center},\n'
            f'    width = {self.width})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

width property writable

Get the width parameter (HWHM).

Returns:

Type	Description
Parameter	The width parameter.

__init__(area=1.0, center=None, width=1.0, unit='meV', name='Lorentzian', display_name=None, unique_name=None)

Initialize the Lorentzian component.

Parameters:

Name	Type	Description	Default
area	Numeric | Parameter	Area of the Lorentzian.	1.0
center	Numeric | Parameter | None	Center of the Lorentzian. If None, defaults to 0 and is fixed.	None
width	Numeric | Parameter	Half width at half maximum (HWHM).	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'Lorentzian'
display_name	str | None	Display name for the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/lorentzian.py

def __init__(
    self,
    area: Numeric | Parameter = 1.0,
    center: Numeric | Parameter | None = None,
    width: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'Lorentzian',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Lorentzian component.

    Parameters
    ----------
    area : Numeric | Parameter, default=1.0
        Area of the Lorentzian.
    center : Numeric | Parameter | None, default=None
        Center of the Lorentzian. If None, defaults to 0 and is fixed.
    width : Numeric | Parameter, default=1.0
        Half width at half maximum (HWHM).
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='Lorentzian'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name for the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.
    """

    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )
    width = self._create_width_parameter(width=width, name=name, unit=self._unit)

    self._area = area
    self._center = center
    self._width = width

evaluate(x)

Evaluate the Lorentzian at the given x values.

If x is a scipp Variable, the unit of the Lorentzian will be converted to match x. The intensity is given by

\[ 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 half width at half maximum (HWHM).

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Lorentzian.	required

Returns:

Type	Description
np.ndarray	The intensity of the Lorentzian at the given x values.

Source code in src/easydynamics/sample_model/components/lorentzian.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    r"""
    Evaluate the Lorentzian at the given x values.

    If x is a scipp Variable, the unit of the Lorentzian will be converted to match x. The
    intensity is given by

    $$ 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 half width at half maximum
    (HWHM).

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Lorentzian.

    Returns
    -------
    np.ndarray
        The intensity of the Lorentzian at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    normalization = self.width.value / np.pi
    denominator = (x - self.center.value) ** 2 + self.width.value**2

    return self.area.value * normalization / denominator

__repr__()

Return a string representation of the Lorentzian.

Returns:

Type	Description
str	A string representation of the Lorentzian.

Source code in src/easydynamics/sample_model/components/lorentzian.py

def __repr__(self) -> str:
    """
    Return a string representation of the Lorentzian.

    Returns
    -------
    str
        A string representation of the Lorentzian.
    """
    return (
        f'Lorentzian(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n'
        f'    area = {self.area},\n'
        f'    center = {self.center},\n'
        f'    width = {self.width})'
    )

mixins

CreateParametersMixin

Provides parameter creation and validation methods for model components.

This mixin provides methods to create and validate common physics parameters (area, center, width) with appropriate bounds and type checking.

Source code in src/easydynamics/sample_model/components/mixins.py

class CreateParametersMixin:
    """
    Provides parameter creation and validation methods for model components.

    This mixin provides methods to create and validate common physics parameters (area, center,
    width) with appropriate bounds and type checking.
    """

    def _create_area_parameter(
        self,
        area: Numeric | Parameter,
        name: str,
        unit: str | sc.Unit = 'meV',
        minimum_area: float = MINIMUM_AREA,
    ) -> Parameter:
        """
        Validate and convert a number to a Parameter describing the area of a function.

        If the area is negative, a warning is raised. If the area is non-negative, its minimum is
        set to 0 to avoid it accidentally becoming negative during fitting.

        Parameters
        ----------
        area : Numeric | Parameter
            The area value or Parameter.
        name : str
            The name of the model component.
        unit : str | sc.Unit, default='meV'
            The unit of the area Parameter.
        minimum_area : float, default=MINIMUM_AREA
            The minimum allowed area.

        Raises
        ------
        TypeError
            If area is not a number or a Parameter.
        ValueError
            If area is not a finite number or if the area Parameter has a non-finite value.

        Returns
        -------
        Parameter
            The validated area Parameter.
        """
        if not isinstance(area, (Parameter, Numeric)):
            raise TypeError('area must be a number or a Parameter.')

        if isinstance(area, Numeric):
            if not np.isfinite(area):
                raise ValueError('area must be a finite number or a Parameter')

            area = Parameter(name=name + ' area', value=float(area), unit=unit)

        if area.value < 0:
            warnings.warn(
                f'The area of {name} is negative, which may not be physically meaningful.',
                UserWarning,
                stacklevel=3,
            )
        else:
            if area.min < minimum_area:
                area.min = minimum_area

        return area

    def _create_center_parameter(
        self,
        center: Numeric | Parameter | None,
        name: str,
        fix_if_none: bool,
        unit: str | sc.Unit = 'meV',
        enforce_minimum_center: bool = False,
    ) -> Parameter:
        """
        Validate and convert a number to a Parameter describing the center of a function.

        Parameters
        ----------
        center : Numeric | Parameter | None
            The center value or Parameter.
        name : str
            The name of the model component.
        fix_if_none : bool
            Whether to fix the center Parameter if center is None.
        unit : str | sc.Unit, default='meV'
            The unit of the center Parameter.
        enforce_minimum_center : bool, default=False
            Whether to enforce a minimum center value to avoid zero center in DHO.

        Raises
        ------
        TypeError
            If center is not None, a number, or a Parameter.
        ValueError
            If center is a number but not finite, or if center is a Parameter but has a non-finite
            value.

        Returns
        -------
        Parameter
            The validated center Parameter.
        """
        if center is not None and not isinstance(center, (Numeric, Parameter)):
            raise TypeError('center must be None, a number, or a Parameter.')

        if center is None:
            center = Parameter(
                name=name + ' center',
                value=0.0,
                unit=unit,
                fixed=fix_if_none,
            )
        elif isinstance(center, Numeric):
            if not np.isfinite(center):
                raise ValueError('center must be None, a finite number or a Parameter')

            center = Parameter(name=name + ' center', value=float(center), unit=unit)
        if enforce_minimum_center and center.min < DHO_MINIMUM_CENTER:
            center.min = DHO_MINIMUM_CENTER
        return center

    def _create_width_parameter(
        self,
        width: Numeric | Parameter,
        name: str,
        param_name: str = 'width',
        unit: str | sc.Unit = 'meV',
        minimum_width: float = MINIMUM_WIDTH,
    ) -> Parameter:
        """
        Validate and convert a number to a Parameter describing the width of a function.

        Parameters
        ----------
        width : Numeric | Parameter
            The width value or Parameter.
        name : str
            The name of the model component.
        param_name : str, default='width'
            The name of the width parameter.
        unit : str | sc.Unit, default='meV'
            The unit of the width Parameter.
        minimum_width : float, default=MINIMUM_WIDTH
            The minimum allowed width.

        Raises
        ------
        TypeError
            If width is not a number or a Parameter.
        ValueError
            If width is non-positive.

        Returns
        -------
        Parameter
            The validated width Parameter.
        """
        if not isinstance(width, (Numeric, Parameter)):
            raise TypeError(f'{param_name} must be a number or a Parameter.')

        if isinstance(width, Numeric):
            if not np.isfinite(width):
                raise ValueError(f'{param_name} must be a finite number or a Parameter')

            if float(width) < minimum_width:
                raise ValueError(
                    f'The {param_name} of a {self.__class__.__name__} must be greater than zero.'
                )
            width = Parameter(
                name=name + ' ' + param_name,
                value=float(width),
                unit=unit,
                min=minimum_width,
            )
        else:
            if width.value <= 0:
                raise ValueError(
                    f'The {param_name} of a {self.__class__.__name__} must be greater than zero.'
                )
            if width.min < minimum_width:
                width.min = minimum_width

        return width

model_component

ModelComponent

Bases: EasyDynamicsModelBase

Abstract base class for all model components.

Source code in src/easydynamics/sample_model/components/model_component.py

class ModelComponent(EasyDynamicsModelBase):
    """Abstract base class for all model components."""

    def __init__(
        self,
        unit: str | sc.Unit = 'meV',
        name: str = 'ModelComponent',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the ModelComponent.

        Parameters
        ----------
        unit : str | sc.Unit, default='meV'
            The unit of the model component.
        name : str, default='ModelComponent'
            The name of the model component for indexing.
        display_name : str | None, default=None
            A human-readable name for the component.
        unique_name : str | None, default=None
            A unique identifier for the component.
        """
        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

    @property
    def unit(self) -> str:
        """
        Get the unit.

        Returns
        -------
        str
            The unit of the model component.
        """
        return str(self._unit)

    @unit.setter
    def unit(self, _unit_str: str) -> None:
        """
        Unit is read-only.

        Use convert_unit to change the unit between allowed types or create a new ModelComponent
        with the desired unit.

        Parameters
        ----------
        _unit_str : str
            The new unit to set.

        Raises
        ------
        AttributeError
            Always raised since unit is read-only.
        """
        raise AttributeError(
            f'Unit is read-only. Use convert_unit to change the unit between allowed types '
            f'or create a new {self.__class__.__name__} with the desired unit.'
        )

    def fix_all_parameters(self) -> None:
        """Fix all parameters in the model component."""

        pars = self.get_fittable_parameters()
        for p in pars:
            p.fixed = True

    def free_all_parameters(self) -> None:
        """Free all parameters in the model component."""
        for p in self.get_fittable_parameters():
            p.fixed = False

    def _prepare_x_for_evaluate(
        self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray
    ) -> np.ndarray:
        """
        Prepare the input x for evaluation by handling units and converting to a numpy array.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The input data to prepare.

        Raises
        ------
        ValueError
            If x contains NaN or infinite values, or if a sc.DataArray has more than one
            coordinate.
        UnitError
            If x has incompatible units that cannot be converted to the component's unit.

        Returns
        -------
        np.ndarray
            The prepared input data as a numpy array.
        """

        # Handle units
        if isinstance(x, sc.DataArray):
            # Check that there's exactly one coordinate
            coords = dict(x.coords)
            ncoords = len(coords)
            if ncoords != 1:
                coord_names = ', '.join(coords.keys())
                raise ValueError(
                    f'scipp.DataArray must have exactly one coordinate to be used as input `x`. '
                    f'Found {ncoords} coordinates: {coord_names}.'
                )
            # get the coordinate, it's a sc.Variable
            _, coord_obj = next(iter(coords.items()))
            x = coord_obj
        if isinstance(x, sc.Variable):
            # Need to check if the units are consistent,
            # and convert if not.
            x_in = x.value if x.sizes == {} else x.values
            if self._unit is not None and x.unit != self._unit:
                self_unit_for_warning = self._unit
                try:
                    self.convert_unit(x.unit.name)
                except Exception as e:
                    raise UnitError(
                        f'Input x has unit {x.unit}, but {self.__class__.__name__} component \
                            has unit {self._unit}. \
                                Failed to convert {self.__class__.__name__} to {x.unit}.'
                    ) from e

                warnings.warn(
                    f'Input x has unit {x.unit}, but {self.__class__.__name__} component \
                        has unit {self_unit_for_warning}. \
                            Converting {self.__class__.__name__} to {x.unit}.',
                    UserWarning,
                    stacklevel=3,
                )
        else:
            x_in = x

        if isinstance(x_in, Numeric):
            x_in = np.array([x_in])
        elif isinstance(x_in, list):
            x_in = np.array(x_in)

        if any(np.isnan(x_in)):
            raise ValueError('Input x contains NaN values.')

        if any(np.isinf(x_in)):
            raise ValueError('Input x contains infinite values.')

        return np.sort(x_in)

    def convert_unit(self, unit: str | sc.Unit) -> None:
        """
        Convert the unit of the Parameters in the component.

        Parameters
        ----------
        unit : str | sc.Unit
            The new unit to convert to.

        Raises
        ------
        TypeError
            If the provided unit is not a str or sc.Unit.
        Exception
            If the provided unit is invalid or incompatible with the component's parameters.
        """
        if not isinstance(unit, (str, sc.Unit)):
            raise TypeError(f'Unit must be a string or sc.Unit, got {type(unit).__name__}')

        old_unit = self._unit
        pars = self.get_all_parameters()
        try:
            for p in pars:
                p.convert_unit(unit)
            self._unit = unit
        except Exception as e:
            # Attempt to rollback on failure
            try:
                for p in pars:
                    if hasattr(p, 'convert_unit'):
                        p.convert_unit(old_unit)
            except Exception:  # noqa: S110
                pass  # Best effort rollback
            raise e

    @abstractmethod
    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        """
        Abstract method to evaluate the model component at input x.

        Must be implemented by subclasses.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the component.

        Returns
        -------
        np.ndarray
            Evaluated function values.
        """

    def __repr__(self) -> str:
        """
        Return a string representation of the ModelComponent.

        Returns
        -------
        str
            A string representation of the ModelComponent.
        """

        return f'{self.__class__.__name__}(unique_name={self.unique_name}, unit={self._unit})'

unit property writable

Get the unit.

Returns:

Type	Description
str	The unit of the model component.

__init__(unit='meV', name='ModelComponent', display_name=None, unique_name=None)

Initialize the ModelComponent.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The unit of the model component.	'meV'
name	str	The name of the model component for indexing.	'ModelComponent'
display_name	str | None	A human-readable name for the component.	None
unique_name	str | None	A unique identifier for the component.	None

Source code in src/easydynamics/sample_model/components/model_component.py

def __init__(
    self,
    unit: str | sc.Unit = 'meV',
    name: str = 'ModelComponent',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the ModelComponent.

    Parameters
    ----------
    unit : str | sc.Unit, default='meV'
        The unit of the model component.
    name : str, default='ModelComponent'
        The name of the model component for indexing.
    display_name : str | None, default=None
        A human-readable name for the component.
    unique_name : str | None, default=None
        A unique identifier for the component.
    """
    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

fix_all_parameters()

Fix all parameters in the model component.

Source code in src/easydynamics/sample_model/components/model_component.py

def fix_all_parameters(self) -> None:
    """Fix all parameters in the model component."""

    pars = self.get_fittable_parameters()
    for p in pars:
        p.fixed = True

free_all_parameters()

Free all parameters in the model component.

Source code in src/easydynamics/sample_model/components/model_component.py

def free_all_parameters(self) -> None:
    """Free all parameters in the model component."""
    for p in self.get_fittable_parameters():
        p.fixed = False

convert_unit(unit)

Convert the unit of the Parameters in the component.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The new unit to convert to.	required

Raises:

Type	Description
TypeError	If the provided unit is not a str or sc.Unit.
Exception	If the provided unit is invalid or incompatible with the component's parameters.

Source code in src/easydynamics/sample_model/components/model_component.py

def convert_unit(self, unit: str | sc.Unit) -> None:
    """
    Convert the unit of the Parameters in the component.

    Parameters
    ----------
    unit : str | sc.Unit
        The new unit to convert to.

    Raises
    ------
    TypeError
        If the provided unit is not a str or sc.Unit.
    Exception
        If the provided unit is invalid or incompatible with the component's parameters.
    """
    if not isinstance(unit, (str, sc.Unit)):
        raise TypeError(f'Unit must be a string or sc.Unit, got {type(unit).__name__}')

    old_unit = self._unit
    pars = self.get_all_parameters()
    try:
        for p in pars:
            p.convert_unit(unit)
        self._unit = unit
    except Exception as e:
        # Attempt to rollback on failure
        try:
            for p in pars:
                if hasattr(p, 'convert_unit'):
                    p.convert_unit(old_unit)
        except Exception:  # noqa: S110
            pass  # Best effort rollback
        raise e

evaluate(x) abstractmethod

Abstract method to evaluate the model component at input x.

Must be implemented by subclasses.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the component.	required

Returns:

Type	Description
np.ndarray	Evaluated function values.

Source code in src/easydynamics/sample_model/components/model_component.py

@abstractmethod
def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    """
    Abstract method to evaluate the model component at input x.

    Must be implemented by subclasses.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the component.

    Returns
    -------
    np.ndarray
        Evaluated function values.
    """

__repr__()

Return a string representation of the ModelComponent.

Returns:

Type	Description
str	A string representation of the ModelComponent.

Source code in src/easydynamics/sample_model/components/model_component.py

def __repr__(self) -> str:
    """
    Return a string representation of the ModelComponent.

    Returns
    -------
    str
        A string representation of the ModelComponent.
    """

    return f'{self.__class__.__name__}(unique_name={self.unique_name}, unit={self._unit})'

polynomial

Polynomial

Bases: ModelComponent

Polynomial function component.

The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ... + c_N x^N, $$ where \(C_i\) are the coefficients.

Source code in src/easydynamics/sample_model/components/polynomial.py

class Polynomial(ModelComponent):
    r"""
    Polynomial function component.

    The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ... + c_N x^N, $$ where $C_i$ are
    the coefficients.
    """

    def __init__(
        self,
        coefficients: Sequence[Numeric | Parameter] = (0.0,),
        unit: str | sc.Unit = 'meV',
        name: str = 'Polynomial',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize the Polynomial component.

        Parameters
        ----------
        coefficients : Sequence[Numeric | Parameter], default=(0.0,)
            Coefficients c0, c1, ..., cN.
        unit : str | sc.Unit, default='meV'
            Unit of the Polynomial component.
        name : str, default='Polynomial'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the Polynomial component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.

        Raises
        ------
        TypeError
            If coefficients is not a sequence of numbers or Parameters or if any item in
            coefficients is not a number or Parameter.
        ValueError
            If coefficients is an empty sequence.
        """

        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        if not isinstance(coefficients, (list, tuple, np.ndarray)):
            raise TypeError(
                'coefficients must be a sequence (list/tuple/ndarray) \
                    of numbers or Parameter objects.'
            )

        if len(coefficients) == 0:
            raise ValueError('At least one coefficient must be provided.')

        # Internal storage of Parameter objects
        self._coefficients: list[Parameter] = []

        # Coefficients are treated as dimensionless Parameters
        for i, coef in enumerate(coefficients):
            if isinstance(coef, Parameter):
                param = coef
            elif isinstance(coef, Numeric):
                param = Parameter(name=f'{name}_c{i}', value=float(coef))
            else:
                raise TypeError('Each coefficient must be either a numeric value or a Parameter.')
            self._coefficients.append(param)

        # Helper scipp scalar to track unit conversions
        # (value initialized to 1 with provided unit)
        self._unit_conversion_helper = sc.scalar(value=1.0, unit=unit)

    @property
    def coefficients(self) -> list[Parameter]:
        """
        Get the coefficients of the polynomial as a list of Parameters.

        Returns
        -------
        list[Parameter]
            The coefficients of the polynomial.
        """
        return list(self._coefficients)

    @coefficients.setter
    def coefficients(self, coeffs: Sequence[Numeric | Parameter]) -> None:
        """
        Set the coefficients of the polynomial.

        Length must match current number of coefficients.

        Parameters
        ----------
        coeffs : Sequence[Numeric | Parameter]
            New coefficients as a sequence of numbers or Parameters.

        Raises
        ------
        TypeError
            If coeffs is not a sequence of numbers or Parameters or if any item in coeffs is not a
            number or Parameter.
        ValueError
            If the length of coeffs does not match the existing number of coefficients.
        """
        if not isinstance(coeffs, (list, tuple, np.ndarray)):
            raise TypeError(
                'coefficients must be a sequence (list/tuple/ndarray) of numbers or Parameter .'
            )
        if len(coeffs) != len(self._coefficients):
            raise ValueError(
                'Number of coefficients must match the existing number of coefficients.'
            )
        for i, coef in enumerate(coeffs):
            if isinstance(coef, Parameter):
                # replace parameter
                self._coefficients[i] = coef
            elif isinstance(coef, Numeric):
                self._coefficients[i].value = float(coef)
            else:
                raise TypeError('Each coefficient must be either a numeric value or a Parameter.')

    def coefficient_values(self) -> list[float]:
        """
        Get the coefficients of the polynomial as a list.

        Returns
        -------
        list[float]
            The coefficient values of the polynomial.
        """
        return [param.value for param in self._coefficients]

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        r"""
        Evaluate the Polynomial at the given x values.

        The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ...
        + c_N x^N, $$ where $C_i$ are the coefficients.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Polynomial.

        Returns
        -------
        np.ndarray
            The evaluated Polynomial at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        result = np.zeros_like(x, dtype=float)
        for i, param in enumerate(self._coefficients):
            result += param.value * np.power(x, i)

        if any(result < 0):
            warnings.warn(
                f'The Polynomial with unique_name {self.unique_name} has negative values, '
                'which may not be physically meaningful.',
                UserWarning,
                stacklevel=2,
            )
        return result

    @property
    def degree(self) -> int:
        """
        Get the degree of the polynomial.

        Returns
        -------
        int
            The degree of the polynomial.
        """
        return len(self._coefficients) - 1

    @degree.setter
    def degree(self, _value: int) -> None:
        """
        The degree is determined by the number of coefficients and cannot be set directly.

        Parameters
        ----------
        _value : int
            The new degree of the polynomial.

        Raises
        ------
        AttributeError
            Always raised since degree cannot be set directly.
        """
        raise AttributeError(
            'The degree of the polynomial is determined by the number of coefficients '
            'and cannot be set directly.'
        )

    def get_all_variables(self) -> list[DescriptorBase]:
        """
        Get all variables from the model component.

        Returns
        -------
        list[DescriptorBase]
            List of variables in the component.
        """
        return list(self._coefficients)

    def convert_unit(self, unit: str | sc.Unit) -> None:
        """
        Convert the unit of the polynomial.

        Parameters
        ----------
        unit : str | sc.Unit
            The target unit to convert to.

        Raises
        ------
        UnitError
            If the provided unit is not a string or sc.Unit.
        """

        if not isinstance(unit, (str, sc.Unit)):
            raise UnitError('unit must be a string or a scipp unit.')

        # Find out how much the unit changes
        # by converting a helper variable
        conversion_value_before = self._unit_conversion_helper.value
        self._unit_conversion_helper = sc.to_unit(self._unit_conversion_helper, unit=unit)
        conversion_value_after = self._unit_conversion_helper.value
        for i, param in enumerate(self._coefficients):
            param.value *= (
                conversion_value_before / conversion_value_after
            ) ** i  # set the values directly to the appropriate power

        self._unit = unit

    def __repr__(self) -> str:
        """
        Return a string representation of the Polynomial.

        Returns
        -------
        str
            A string representation of the Polynomial.
        """

        coeffs_str = ', '.join(f'{param.name}={param.value}' for param in self._coefficients)
        return (
            f'Polynomial(name = {self.name}, display_name = {self.display_name}, '
            f'unit = {self._unit},\n'
            f'    coefficients = [{coeffs_str}])'
        )

coefficients property writable

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

Returns:

Type	Description
list[Parameter]	The coefficients of the polynomial.

degree property writable

Get the degree of the polynomial.

Returns:

Type	Description
int	The degree of the polynomial.

__init__(coefficients=(0.0,), unit='meV', name='Polynomial', display_name=None, unique_name=None)

Initialize the Polynomial component.

Parameters:

Name	Type	Description	Default
coefficients	Sequence[Numeric | Parameter]	Coefficients c0, c1, ..., cN.	(0.0,)
unit	str | sc.Unit	Unit of the Polynomial component.	'meV'
name	str	Name of the component for indexing.	'Polynomial'
display_name	str | None	Display name of the Polynomial component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Raises:

Type	Description
TypeError	If coefficients is not a sequence of numbers or Parameters or if any item in coefficients is not a number or Parameter.
ValueError	If coefficients is an empty sequence.

Source code in src/easydynamics/sample_model/components/polynomial.py

def __init__(
    self,
    coefficients: Sequence[Numeric | Parameter] = (0.0,),
    unit: str | sc.Unit = 'meV',
    name: str = 'Polynomial',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize the Polynomial component.

    Parameters
    ----------
    coefficients : Sequence[Numeric | Parameter], default=(0.0,)
        Coefficients c0, c1, ..., cN.
    unit : str | sc.Unit, default='meV'
        Unit of the Polynomial component.
    name : str, default='Polynomial'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the Polynomial component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.

    Raises
    ------
    TypeError
        If coefficients is not a sequence of numbers or Parameters or if any item in
        coefficients is not a number or Parameter.
    ValueError
        If coefficients is an empty sequence.
    """

    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    if not isinstance(coefficients, (list, tuple, np.ndarray)):
        raise TypeError(
            'coefficients must be a sequence (list/tuple/ndarray) \
                of numbers or Parameter objects.'
        )

    if len(coefficients) == 0:
        raise ValueError('At least one coefficient must be provided.')

    # Internal storage of Parameter objects
    self._coefficients: list[Parameter] = []

    # Coefficients are treated as dimensionless Parameters
    for i, coef in enumerate(coefficients):
        if isinstance(coef, Parameter):
            param = coef
        elif isinstance(coef, Numeric):
            param = Parameter(name=f'{name}_c{i}', value=float(coef))
        else:
            raise TypeError('Each coefficient must be either a numeric value or a Parameter.')
        self._coefficients.append(param)

    # Helper scipp scalar to track unit conversions
    # (value initialized to 1 with provided unit)
    self._unit_conversion_helper = sc.scalar(value=1.0, unit=unit)

coefficient_values()

Get the coefficients of the polynomial as a list.

Returns:

Type	Description
list[float]	The coefficient values of the polynomial.

Source code in src/easydynamics/sample_model/components/polynomial.py

def coefficient_values(self) -> list[float]:
    """
    Get the coefficients of the polynomial as a list.

    Returns
    -------
    list[float]
        The coefficient values of the polynomial.
    """
    return [param.value for param in self._coefficients]

evaluate(x)

Evaluate the Polynomial at the given x values.

The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ... + c_N x^N, $$ where \(C_i\) are the coefficients.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Polynomial.	required

Returns:

Type	Description
np.ndarray	The evaluated Polynomial at the given x values.

Source code in src/easydynamics/sample_model/components/polynomial.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    r"""
    Evaluate the Polynomial at the given x values.

    The intensity is given by $$ I(x) = c_0 + c_1 x + c_2 x^2 + ...
    + c_N x^N, $$ where $C_i$ are the coefficients.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Polynomial.

    Returns
    -------
    np.ndarray
        The evaluated Polynomial at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    result = np.zeros_like(x, dtype=float)
    for i, param in enumerate(self._coefficients):
        result += param.value * np.power(x, i)

    if any(result < 0):
        warnings.warn(
            f'The Polynomial with unique_name {self.unique_name} has negative values, '
            'which may not be physically meaningful.',
            UserWarning,
            stacklevel=2,
        )
    return result

get_all_variables()

Get all variables from the model component.

Returns:

Type	Description
list[DescriptorBase]	List of variables in the component.

Source code in src/easydynamics/sample_model/components/polynomial.py

def get_all_variables(self) -> list[DescriptorBase]:
    """
    Get all variables from the model component.

    Returns
    -------
    list[DescriptorBase]
        List of variables in the component.
    """
    return list(self._coefficients)

convert_unit(unit)

Convert the unit of the polynomial.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The target unit to convert to.	required

Raises:

Type	Description
UnitError	If the provided unit is not a string or sc.Unit.

Source code in src/easydynamics/sample_model/components/polynomial.py

def convert_unit(self, unit: str | sc.Unit) -> None:
    """
    Convert the unit of the polynomial.

    Parameters
    ----------
    unit : str | sc.Unit
        The target unit to convert to.

    Raises
    ------
    UnitError
        If the provided unit is not a string or sc.Unit.
    """

    if not isinstance(unit, (str, sc.Unit)):
        raise UnitError('unit must be a string or a scipp unit.')

    # Find out how much the unit changes
    # by converting a helper variable
    conversion_value_before = self._unit_conversion_helper.value
    self._unit_conversion_helper = sc.to_unit(self._unit_conversion_helper, unit=unit)
    conversion_value_after = self._unit_conversion_helper.value
    for i, param in enumerate(self._coefficients):
        param.value *= (
            conversion_value_before / conversion_value_after
        ) ** i  # set the values directly to the appropriate power

    self._unit = unit

__repr__()

Return a string representation of the Polynomial.

Returns:

Type	Description
str	A string representation of the Polynomial.

Source code in src/easydynamics/sample_model/components/polynomial.py

def __repr__(self) -> str:
    """
    Return a string representation of the Polynomial.

    Returns
    -------
    str
        A string representation of the Polynomial.
    """

    coeffs_str = ', '.join(f'{param.name}={param.value}' for param in self._coefficients)
    return (
        f'Polynomial(name = {self.name}, display_name = {self.display_name}, '
        f'unit = {self._unit},\n'
        f'    coefficients = [{coeffs_str}])'
    )

voigt

Voigt

Bases: CreateParametersMixin, ModelComponent

Voigt profile, a convolution of Gaussian and Lorentzian.

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

Use scipy.special.voigt_profile to evaluate the Voigt profile.

Source code in src/easydynamics/sample_model/components/voigt.py

class Voigt(CreateParametersMixin, ModelComponent):
    r"""
    Voigt profile, a convolution of Gaussian and Lorentzian.

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

    Use scipy.special.voigt_profile to evaluate the Voigt profile.
    """

    def __init__(
        self,
        area: Numeric | Parameter = 1.0,
        center: Numeric | Parameter | None = None,
        gaussian_width: Numeric | Parameter = 1.0,
        lorentzian_width: Numeric | Parameter = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'Voigt',
        display_name: str | None = None,
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize a Voigt component.

        Parameters
        ----------
        area : Numeric | Parameter, default=1.0
            Total area under the curve.
        center : Numeric | Parameter | None, default=None
            Center of the Voigt profile.
        gaussian_width : Numeric | Parameter, default=1.0
            Standard deviation of the Gaussian part.
        lorentzian_width : Numeric | Parameter, default=1.0
            Half width at half max (HWHM) of the Lorentzian part.
        unit : str | sc.Unit, default='meV'
            Unit of the parameters.
        name : str, default='Voigt'
            Name of the component for indexing.
        display_name : str | None, default=None
            Display name of the component.
        unique_name : str | None, default=None
            Unique name of the component. If None, a unique_name is automatically generated. By
            default, None.
        """

        super().__init__(
            unit=unit,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )

        # These methods live in ValidationMixin
        area = self._create_area_parameter(area=area, name=name, unit=self._unit)
        center = self._create_center_parameter(
            center=center, name=name, fix_if_none=True, unit=self._unit
        )
        gaussian_width = self._create_width_parameter(
            width=gaussian_width,
            name=name,
            param_name='gaussian_width',
            unit=self._unit,
        )
        lorentzian_width = self._create_width_parameter(
            width=lorentzian_width,
            name=name,
            param_name='lorentzian_width',
            unit=self._unit,
        )

        self._area = area
        self._center = center
        self._gaussian_width = gaussian_width
        self._lorentzian_width = lorentzian_width

    @property
    def area(self) -> Parameter:
        """
        Get the area parameter.

        Returns
        -------
        Parameter
            The area parameter.
        """
        return self._area

    @area.setter
    def area(self, value: Numeric) -> None:
        """
        Set the value of the area parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the area parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError('area must be a number')
        self._area.value = value

    @property
    def center(self) -> Parameter:
        """
        Get the center parameter.

        Returns
        -------
        Parameter
            The center parameter.
        """
        return self._center

    @center.setter
    def center(self, value: Numeric | None) -> None:
        """
        Set the value of the center parameter.

        Parameters
        ----------
        value : Numeric | None
            The new value for the center parameter. If None, defaults to 0 and is fixed.

        Raises
        ------
        TypeError
            If the value is not a number.
        """
        if value is None:
            value = 0.0
            self._center.fixed = True
        if not isinstance(value, Numeric):
            raise TypeError('center must be a number')
        self._center.value = value

    @property
    def gaussian_width(self) -> Parameter:
        """
        Get the Gaussian width parameter.

        Returns
        -------
        Parameter
            The Gaussian width parameter.
        """
        return self._gaussian_width

    @gaussian_width.setter
    def gaussian_width(self, value: Numeric) -> None:
        """
        Set the width parameter value.

        Parameters
        ----------
        value : Numeric
            The new value for the width parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('gaussian_width must be a number')
        if float(value) <= 0:
            raise ValueError('gaussian_width must be positive')
        self._gaussian_width.value = value

    @property
    def lorentzian_width(self) -> Parameter:
        """
        Get the Lorentzian width parameter (HWHM).

        Returns
        -------
        Parameter
            The Lorentzian width parameter.
        """
        return self._lorentzian_width

    @lorentzian_width.setter
    def lorentzian_width(self, value: Numeric) -> None:
        """
        Set the value of the Lorentzian width parameter.

        Parameters
        ----------
        value : Numeric
            The new value for the Lorentzian width parameter.

        Raises
        ------
        TypeError
            If the value is not a number.
        ValueError
            If the value is not positive.
        """
        if not isinstance(value, Numeric):
            raise TypeError('lorentzian_width must be a number')
        if float(value) <= 0:
            raise ValueError('lorentzian_width must be positive')
        self._lorentzian_width.value = value

    def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
        r"""
        Evaluate the Voigt at the given x values.

        If x is a scipp Variable, the unit of the Voigt will be converted to match x. The Voigt
        evaluates to the convolution of a Gaussian with sigma gaussian_width and a Lorentzian with
        half width at half max lorentzian_width, centered at center, with area equal to area.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values at which to evaluate the Voigt.

        Returns
        -------
        np.ndarray
            The intensity of the Voigt at the given x values.
        """

        x = self._prepare_x_for_evaluate(x)

        return self.area.value * voigt_profile(
            x - self.center.value,
            self.gaussian_width.value,
            self.lorentzian_width.value,
        )

    def __repr__(self) -> str:
        """
        Return a string representation of the Voigt.

        Returns
        -------
        str
            A string representation of the Voigt.
        """

        return (
            f'Voigt(name = {self.name}, display_name = {self.display_name}, unit = {self._unit},\n'
            f'    area = {self.area},\n'
            f'    center = {self.center},\n'
            f'    gaussian_width = {self.gaussian_width},\n'
            f'    lorentzian_width = {self.lorentzian_width})'
        )

area property writable

Get the area parameter.

Returns:

Type	Description
Parameter	The area parameter.

center property writable

Get the center parameter.

Returns:

Type	Description
Parameter	The center parameter.

gaussian_width property writable

Get the Gaussian width parameter.

Returns:

Type	Description
Parameter	The Gaussian width parameter.

lorentzian_width property writable

Get the Lorentzian width parameter (HWHM).

Returns:

Type	Description
Parameter	The Lorentzian width parameter.

__init__(area=1.0, center=None, gaussian_width=1.0, lorentzian_width=1.0, unit='meV', name='Voigt', display_name=None, unique_name=None)

Initialize a Voigt component.

Parameters:

Name	Type	Description	Default
area	Numeric | Parameter	Total area under the curve.	1.0
center	Numeric | Parameter | None	Center of the Voigt profile.	None
gaussian_width	Numeric | Parameter	Standard deviation of the Gaussian part.	1.0
lorentzian_width	Numeric | Parameter	Half width at half max (HWHM) of the Lorentzian part.	1.0
unit	str | sc.Unit	Unit of the parameters.	'meV'
name	str	Name of the component for indexing.	'Voigt'
display_name	str | None	Display name of the component.	None
unique_name	str | None	Unique name of the component. If None, a unique_name is automatically generated. By default, None.	None

Source code in src/easydynamics/sample_model/components/voigt.py

def __init__(
    self,
    area: Numeric | Parameter = 1.0,
    center: Numeric | Parameter | None = None,
    gaussian_width: Numeric | Parameter = 1.0,
    lorentzian_width: Numeric | Parameter = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'Voigt',
    display_name: str | None = None,
    unique_name: str | None = None,
) -> None:
    """
    Initialize a Voigt component.

    Parameters
    ----------
    area : Numeric | Parameter, default=1.0
        Total area under the curve.
    center : Numeric | Parameter | None, default=None
        Center of the Voigt profile.
    gaussian_width : Numeric | Parameter, default=1.0
        Standard deviation of the Gaussian part.
    lorentzian_width : Numeric | Parameter, default=1.0
        Half width at half max (HWHM) of the Lorentzian part.
    unit : str | sc.Unit, default='meV'
        Unit of the parameters.
    name : str, default='Voigt'
        Name of the component for indexing.
    display_name : str | None, default=None
        Display name of the component.
    unique_name : str | None, default=None
        Unique name of the component. If None, a unique_name is automatically generated. By
        default, None.
    """

    super().__init__(
        unit=unit,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )

    # These methods live in ValidationMixin
    area = self._create_area_parameter(area=area, name=name, unit=self._unit)
    center = self._create_center_parameter(
        center=center, name=name, fix_if_none=True, unit=self._unit
    )
    gaussian_width = self._create_width_parameter(
        width=gaussian_width,
        name=name,
        param_name='gaussian_width',
        unit=self._unit,
    )
    lorentzian_width = self._create_width_parameter(
        width=lorentzian_width,
        name=name,
        param_name='lorentzian_width',
        unit=self._unit,
    )

    self._area = area
    self._center = center
    self._gaussian_width = gaussian_width
    self._lorentzian_width = lorentzian_width

evaluate(x)

Evaluate the Voigt at the given x values.

If x is a scipp Variable, the unit of the Voigt will be converted to match x. The Voigt evaluates to the convolution of a Gaussian with sigma gaussian_width and a Lorentzian with half width at half max lorentzian_width, centered at center, with area equal to area.

Parameters:

Name	Type	Description	Default
x	Numeric | list | np.ndarray | sc.Variable | sc.DataArray	The x values at which to evaluate the Voigt.	required

Returns:

Type	Description
np.ndarray	The intensity of the Voigt at the given x values.

Source code in src/easydynamics/sample_model/components/voigt.py

def evaluate(self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray) -> np.ndarray:
    r"""
    Evaluate the Voigt at the given x values.

    If x is a scipp Variable, the unit of the Voigt will be converted to match x. The Voigt
    evaluates to the convolution of a Gaussian with sigma gaussian_width and a Lorentzian with
    half width at half max lorentzian_width, centered at center, with area equal to area.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values at which to evaluate the Voigt.

    Returns
    -------
    np.ndarray
        The intensity of the Voigt at the given x values.
    """

    x = self._prepare_x_for_evaluate(x)

    return self.area.value * voigt_profile(
        x - self.center.value,
        self.gaussian_width.value,
        self.lorentzian_width.value,
    )

__repr__()

Return a string representation of the Voigt.

Returns:

Type	Description
str	A string representation of the Voigt.

Source code in src/easydynamics/sample_model/components/voigt.py

def __repr__(self) -> str:
    """
    Return a string representation of the Voigt.

    Returns
    -------
    str
        A string representation of the Voigt.
    """

    return (
        f'Voigt(name = {self.name}, display_name = {self.display_name}, unit = {self._unit},\n'
        f'    area = {self.area},\n'
        f'    center = {self.center},\n'
        f'    gaussian_width = {self.gaussian_width},\n'
        f'    lorentzian_width = {self.lorentzian_width})'
    )

diffusion_model

BrownianTranslationalDiffusion

Bases: DiffusionModelBase

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:

>>> Q=np.linspace(0.5,2,7) >>>energy=np.linspace(-2, 2, 501)
>>> scale = 1.0
>>> diffusion_coefficient = 2.4e-9  # m^2/s
>>> diffusion_model=BrownianTranslationalDiffusion(name="DiffusionModel",
>>> scale=scale, diffusion_coefficient= diffusion_coefficient,)
>>> component_collections = diffusion_model.create_component_collections(Q)

See also the tutorials.

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

class BrownianTranslationalDiffusion(DiffusionModelBase):
    r"""
    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
    --------
    >>> Q=np.linspace(0.5,2,7) >>>energy=np.linspace(-2, 2, 501)
    >>> scale = 1.0
    >>> diffusion_coefficient = 2.4e-9  # m^2/s
    >>> diffusion_model=BrownianTranslationalDiffusion(name="DiffusionModel",
    >>> scale=scale, diffusion_coefficient= diffusion_coefficient,)
    >>> component_collections = diffusion_model.create_component_collections(Q)

    See also the tutorials.
    """

    def __init__(
        self,
        scale: Numeric = 1.0,
        diffusion_coefficient: Numeric = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'BrownianTranslationalDiffusion',
        display_name: str | None = 'BrownianTranslationalDiffusion',
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize a new BrownianTranslationalDiffusion model.

        Parameters
        ----------
        scale : Numeric, default=1.0
            Scale factor for the diffusion model. Must be a non-negative number.
        diffusion_coefficient : Numeric, default=1.0
            Diffusion coefficient D in m^2/s.
        unit : str | sc.Unit, default='meV'
            Unit of the diffusion model. Must be convertible to meV.
        name : str, default='BrownianTranslationalDiffusion'
            Name of the diffusion model.
        display_name : str | None, default='BrownianTranslationalDiffusion'
            Display name of the diffusion model.
        unique_name : str | None, default=None
            Unique name of the diffusion model. If None, a unique name will be generated. By
            default, None.

        Raises
        ------
        TypeError
            If scale or diffusion_coefficient is not a number.
        """
        if not isinstance(scale, Numeric):
            raise TypeError('scale must be a number.')

        if not isinstance(diffusion_coefficient, Numeric):
            raise TypeError('diffusion_coefficient must be a number.')

        diffusion_coefficient = Parameter(
            name='diffusion_coefficient',
            value=float(diffusion_coefficient),
            fixed=False,
            unit='m**2/s',
            min=0.0,
        )
        super().__init__(
            unit=unit,
            scale=scale,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )
        self._hbar = hbar
        self._angstrom = angstrom
        self._diffusion_coefficient = diffusion_coefficient

    # ------------------------------------------------------------------
    # Properties
    # ------------------------------------------------------------------

    @property
    def diffusion_coefficient(self) -> Parameter:
        """
        Get the diffusion coefficient parameter D.

        Returns
        -------
        Parameter
            Diffusion coefficient D in m^2/s.
        """
        return self._diffusion_coefficient

    @diffusion_coefficient.setter
    def diffusion_coefficient(self, diffusion_coefficient: Numeric) -> None:
        """
        Set the diffusion coefficient parameter D.

        Parameters
        ----------
        diffusion_coefficient : Numeric
            The new value for the diffusion coefficient D in m^2/s.

        Raises
        ------
        TypeError
            If diffusion_coefficient is not a number.
        ValueError
            If diffusion_coefficient is negative.
        """
        if not isinstance(diffusion_coefficient, Numeric):
            raise TypeError('diffusion_coefficient must be a number.')

        if float(diffusion_coefficient) < 0:
            raise ValueError('diffusion_coefficient must be non-negative.')
        self._diffusion_coefficient.value = float(diffusion_coefficient)

    # ------------------------------------------------------------------
    # Other methods
    # ------------------------------------------------------------------

    def calculate_width(self, Q: Q_type) -> np.ndarray:
        """
        Calculate the half-width at half-maximum (HWHM) for the diffusion model.

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom.

        Returns
        -------
        np.ndarray
            HWHM values in the unit of the model (e.g., meV).
        """

        Q = _validate_and_convert_Q(Q)

        unit_conversion_factor = self._hbar * self.diffusion_coefficient / (self._angstrom**2)
        unit_conversion_factor.convert_unit(self.unit)
        return Q**2 * unit_conversion_factor.value

    def calculate_EISF(self, Q: Q_type) -> np.ndarray:
        """
        Calculate the Elastic Incoherent Structure Factor (EISF) for the Brownian translational
        diffusion model.

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom.

        Returns
        -------
        np.ndarray
            EISF values (dimensionless).
        """
        Q = _validate_and_convert_Q(Q)
        return np.zeros_like(Q)

    def calculate_QISF(self, Q: Q_type) -> np.ndarray:
        """
        Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom.

        Returns
        -------
        np.ndarray
            QISF values (dimensionless).
        """

        Q = _validate_and_convert_Q(Q)
        return np.ones_like(Q)

    def create_component_collections(
        self,
        Q: Q_type,
        component_name: str = 'Brownian diffusion',
        component_display_name: str | None = None,
    ) -> list[ComponentCollection]:
        r"""
        Create ComponentCollection components for the Brownian translational diffusion model at
        given Q values.

        Parameters
        ----------
        Q : Q_type
            Scattering vector values.
        component_name : str, default='Brownian diffusion'
            Name of the Brownian diffusion component.
        component_display_name : str | None, default=None
            Display name of the Brownian diffusion component.

        Raises
        ------
        TypeError
            If component_display_name is not a string. If component_name is not a string.

        Returns
        -------
        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).
        """
        Q = _validate_and_convert_Q(Q)

        if not isinstance(component_name, str):
            raise TypeError('component_name must be a string.')

        if component_display_name is None:
            component_display_name = component_name

        if not isinstance(component_display_name, str):
            raise TypeError('component_display_name must be a string.')

        component_collection_list = [None] * len(Q)
        # In more complex models, this is used to scale the area of the
        # Lorentzians and the delta function.
        QISF = self.calculate_QISF(Q)

        # Create a Lorentzian component for each Q-value, with
        # width D*Q^2 and area equal to scale.
        # No delta function, as the EISF is 0.
        for i, Q_value in enumerate(Q):
            component_collection_list[i] = ComponentCollection(
                name=f'{self.name}_Q{Q_value:.2f}',
                display_name=f'{self.display_name}_Q{Q_value:.2f}',
                unit=self.unit,
            )

            lorentzian_component = Lorentzian(
                name=component_name,
                display_name=component_display_name,
                unit=self.unit,
            )

            # Make the width dependent on Q
            dependency_expression = self._write_width_dependency_expression(Q[i])
            dependency_map = self._write_width_dependency_map_expression()

            lorentzian_component.width.make_dependent_on(
                dependency_expression=dependency_expression,
                dependency_map=dependency_map,
                desired_unit=self.unit,
            )

            # Make the area dependent on Q
            area_dependency_map = self._write_area_dependency_map_expression()
            lorentzian_component.area.make_dependent_on(
                dependency_expression=self._write_area_dependency_expression(QISF[i]),
                dependency_map=area_dependency_map,
            )

            component_collection_list[i].append_component(lorentzian_component)

        return component_collection_list

    # ------------------------------------------------------------------
    # Private methods
    # ------------------------------------------------------------------

    def _write_width_dependency_expression(self, Q: float) -> str:
        """
        Write the dependency expression for the width as a function of Q to make dependent
        Parameters.

        Parameters
        ----------
        Q : float
            Scattering vector in 1/angstrom.

        Raises
        ------
        TypeError
            If Q is not a float.

        Returns
        -------
        str
            Dependency expression for the width.
        """
        if not isinstance(Q, (float)):
            raise TypeError('Q must be a float.')

        # Q is given as a float, so we need to add the units
        return f'hbar * D* {Q} **2*1/(angstrom**2)'

    def _write_width_dependency_map_expression(self) -> dict[str, DescriptorNumber]:
        """
        Write the dependency map expression to make dependent Parameters.

        Returns
        -------
        dict[str, DescriptorNumber]
            Dependency map for the width.
        """
        return {
            'D': self.diffusion_coefficient,
            'hbar': self._hbar,
            'angstrom': self._angstrom,
        }

    def _write_area_dependency_expression(self, QISF: float) -> str:
        """
        Write the dependency expression for the area to make dependent Parameters.

        Parameters
        ----------
        QISF : float
            Quasielastic Incoherent Scattering Function.

        Raises
        ------
        TypeError
            If QISF is not a float.

        Returns
        -------
        str
            Dependency expression for the area.
        """
        if not isinstance(QISF, (float)):
            raise TypeError('QISF must be a float.')

        return f'{QISF} * scale'

    def _write_area_dependency_map_expression(self) -> dict[str, DescriptorNumber]:
        """
        Write the dependency map expression to make dependent Parameters.

        Returns
        -------
        dict[str, DescriptorNumber]
            Dependency map for the area.
        """
        return {
            'scale': self.scale,
        }

    # ------------------------------------------------------------------
    # dunder methods
    # ------------------------------------------------------------------

    def __repr__(self) -> str:
        """
        String representation of the BrownianTranslationalDiffusion model.

        Returns
        -------
        str
            String representation of the BrownianTranslationalDiffusion model.
        """
        return (
            f'BrownianTranslationalDiffusion(name={self.name}, '
            f'display_name={self.display_name}, \n'
            f'    diffusion_coefficient={self.diffusion_coefficient}, \n'
            f'    scale={self.scale})'
        )

diffusion_coefficient property writable

Get the diffusion coefficient parameter D.

Returns:

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

__init__(scale=1.0, diffusion_coefficient=1.0, unit='meV', name='BrownianTranslationalDiffusion', display_name='BrownianTranslationalDiffusion', unique_name=None)

Initialize a new BrownianTranslationalDiffusion model.

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
unit	str | sc.Unit	Unit of the diffusion model. Must be convertible to meV.	'meV'
name	str	Name of the diffusion model.	'BrownianTranslationalDiffusion'
display_name	str | None	Display name of the diffusion model.	'BrownianTranslationalDiffusion'
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.

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def __init__(
    self,
    scale: Numeric = 1.0,
    diffusion_coefficient: Numeric = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'BrownianTranslationalDiffusion',
    display_name: str | None = 'BrownianTranslationalDiffusion',
    unique_name: str | None = None,
) -> None:
    """
    Initialize a new BrownianTranslationalDiffusion model.

    Parameters
    ----------
    scale : Numeric, default=1.0
        Scale factor for the diffusion model. Must be a non-negative number.
    diffusion_coefficient : Numeric, default=1.0
        Diffusion coefficient D in m^2/s.
    unit : str | sc.Unit, default='meV'
        Unit of the diffusion model. Must be convertible to meV.
    name : str, default='BrownianTranslationalDiffusion'
        Name of the diffusion model.
    display_name : str | None, default='BrownianTranslationalDiffusion'
        Display name of the diffusion model.
    unique_name : str | None, default=None
        Unique name of the diffusion model. If None, a unique name will be generated. By
        default, None.

    Raises
    ------
    TypeError
        If scale or diffusion_coefficient is not a number.
    """
    if not isinstance(scale, Numeric):
        raise TypeError('scale must be a number.')

    if not isinstance(diffusion_coefficient, Numeric):
        raise TypeError('diffusion_coefficient must be a number.')

    diffusion_coefficient = Parameter(
        name='diffusion_coefficient',
        value=float(diffusion_coefficient),
        fixed=False,
        unit='m**2/s',
        min=0.0,
    )
    super().__init__(
        unit=unit,
        scale=scale,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )
    self._hbar = hbar
    self._angstrom = angstrom
    self._diffusion_coefficient = diffusion_coefficient

calculate_width(Q)

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

Parameters:

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

Returns:

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

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def calculate_width(self, Q: Q_type) -> np.ndarray:
    """
    Calculate the half-width at half-maximum (HWHM) for the diffusion model.

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom.

    Returns
    -------
    np.ndarray
        HWHM values in the unit of the model (e.g., meV).
    """

    Q = _validate_and_convert_Q(Q)

    unit_conversion_factor = self._hbar * self.diffusion_coefficient / (self._angstrom**2)
    unit_conversion_factor.convert_unit(self.unit)
    return Q**2 * unit_conversion_factor.value

calculate_EISF(Q)

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

Parameters:

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

Returns:

Type	Description
np.ndarray	EISF values (dimensionless).

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def calculate_EISF(self, Q: Q_type) -> np.ndarray:
    """
    Calculate the Elastic Incoherent Structure Factor (EISF) for the Brownian translational
    diffusion model.

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom.

    Returns
    -------
    np.ndarray
        EISF values (dimensionless).
    """
    Q = _validate_and_convert_Q(Q)
    return np.zeros_like(Q)

calculate_QISF(Q)

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

Parameters:

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

Returns:

Type	Description
np.ndarray	QISF values (dimensionless).

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def calculate_QISF(self, Q: Q_type) -> np.ndarray:
    """
    Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom.

    Returns
    -------
    np.ndarray
        QISF values (dimensionless).
    """

    Q = _validate_and_convert_Q(Q)
    return np.ones_like(Q)

create_component_collections(Q, component_name='Brownian diffusion', component_display_name=None)

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

Parameters:

Name	Type	Description	Default
Q	Q_type	Scattering vector values.	required
component_name	str	Name of the Brownian diffusion component.	'Brownian diffusion'
component_display_name	str | None	Display name of the Brownian diffusion component.	None

Raises:

Type	Description
TypeError	If component_display_name is not a string. If component_name is not a string.

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).

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def create_component_collections(
    self,
    Q: Q_type,
    component_name: str = 'Brownian diffusion',
    component_display_name: str | None = None,
) -> list[ComponentCollection]:
    r"""
    Create ComponentCollection components for the Brownian translational diffusion model at
    given Q values.

    Parameters
    ----------
    Q : Q_type
        Scattering vector values.
    component_name : str, default='Brownian diffusion'
        Name of the Brownian diffusion component.
    component_display_name : str | None, default=None
        Display name of the Brownian diffusion component.

    Raises
    ------
    TypeError
        If component_display_name is not a string. If component_name is not a string.

    Returns
    -------
    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).
    """
    Q = _validate_and_convert_Q(Q)

    if not isinstance(component_name, str):
        raise TypeError('component_name must be a string.')

    if component_display_name is None:
        component_display_name = component_name

    if not isinstance(component_display_name, str):
        raise TypeError('component_display_name must be a string.')

    component_collection_list = [None] * len(Q)
    # In more complex models, this is used to scale the area of the
    # Lorentzians and the delta function.
    QISF = self.calculate_QISF(Q)

    # Create a Lorentzian component for each Q-value, with
    # width D*Q^2 and area equal to scale.
    # No delta function, as the EISF is 0.
    for i, Q_value in enumerate(Q):
        component_collection_list[i] = ComponentCollection(
            name=f'{self.name}_Q{Q_value:.2f}',
            display_name=f'{self.display_name}_Q{Q_value:.2f}',
            unit=self.unit,
        )

        lorentzian_component = Lorentzian(
            name=component_name,
            display_name=component_display_name,
            unit=self.unit,
        )

        # Make the width dependent on Q
        dependency_expression = self._write_width_dependency_expression(Q[i])
        dependency_map = self._write_width_dependency_map_expression()

        lorentzian_component.width.make_dependent_on(
            dependency_expression=dependency_expression,
            dependency_map=dependency_map,
            desired_unit=self.unit,
        )

        # Make the area dependent on Q
        area_dependency_map = self._write_area_dependency_map_expression()
        lorentzian_component.area.make_dependent_on(
            dependency_expression=self._write_area_dependency_expression(QISF[i]),
            dependency_map=area_dependency_map,
        )

        component_collection_list[i].append_component(lorentzian_component)

    return component_collection_list

__repr__()

String representation of the BrownianTranslationalDiffusion model.

Returns:

Type	Description
str	String representation of the BrownianTranslationalDiffusion model.

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def __repr__(self) -> str:
    """
    String representation of the BrownianTranslationalDiffusion model.

    Returns
    -------
    str
        String representation of the BrownianTranslationalDiffusion model.
    """
    return (
        f'BrownianTranslationalDiffusion(name={self.name}, '
        f'display_name={self.display_name}, \n'
        f'    diffusion_coefficient={self.diffusion_coefficient}, \n'
        f'    scale={self.scale})'
    )

JumpTranslationalDiffusion

Bases: DiffusionModelBase

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:

>>> Q = np.linspace(0.5, 2, 7)
>>> energy = np.linspace(-2, 2, 501)
>>> scale = 1.0
>>> diffusion_coefficient = 2.4e-9  # m^2/s
>>> relaxation_time = 1.0  # ps
>>> diffusion_model = JumpTranslationalDiffusion(
...     scale=scale,
...     diffusion_coefficient=diffusion_coefficient,
...     relaxation_time=relaxation_time,
... )
>>> component_collections = diffusion_model.create_component_collections(Q)

See also the tutorials..

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

class JumpTranslationalDiffusion(DiffusionModelBase):
    r"""
    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
    --------
    >>> Q = np.linspace(0.5, 2, 7)
    >>> energy = np.linspace(-2, 2, 501)
    >>> scale = 1.0
    >>> diffusion_coefficient = 2.4e-9  # m^2/s
    >>> relaxation_time = 1.0  # ps
    >>> diffusion_model = JumpTranslationalDiffusion(
    ...     scale=scale,
    ...     diffusion_coefficient=diffusion_coefficient,
    ...     relaxation_time=relaxation_time,
    ... )
    >>> component_collections = diffusion_model.create_component_collections(Q)

    See also the tutorials..
    """

    def __init__(
        self,
        scale: Numeric = 1.0,
        diffusion_coefficient: Numeric = 1.0,
        relaxation_time: Numeric = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'JumpTranslationalDiffusion',
        display_name: str | None = 'JumpTranslationalDiffusion',
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize a new JumpTranslationalDiffusion model.

        Parameters
        ----------
        scale : Numeric, default=1.0
            Scale factor for the diffusion model. Must be a non-negative number.
        diffusion_coefficient : Numeric, default=1.0
            Diffusion coefficient D in m^2/s.
        relaxation_time : Numeric, default=1.0
            Relaxation time t in ps.
        unit : str | sc.Unit, default='meV'
            Unit of the diffusion model. Must be convertible to meV.
        name : str, default='JumpTranslationalDiffusion'
            Name of the diffusion model.
        display_name : str | None, default='JumpTranslationalDiffusion'
            Display name of the diffusion model.
        unique_name : str | None, default=None
            Unique name of the diffusion model. If None, a unique name will be generated. By
            default, None.

        Raises
        ------
        TypeError
            If scale, diffusion_coefficient, or relaxation_time  are not numbers.
        """
        super().__init__(
            name=name,
            display_name=display_name,
            unique_name=unique_name,
            unit=unit,
            scale=scale,
        )

        if not isinstance(diffusion_coefficient, Numeric):
            raise TypeError('diffusion_coefficient must be a number.')

        if not isinstance(relaxation_time, Numeric):
            raise TypeError('relaxation_time must be a number.')

        diffusion_coefficient = Parameter(
            name='diffusion_coefficient',
            value=float(diffusion_coefficient),
            fixed=False,
            unit='m**2/s',
        )

        relaxation_time = Parameter(
            name='relaxation_time',
            value=float(relaxation_time),
            fixed=False,
            unit='ps',
        )

        self._hbar = hbar
        self._angstrom = angstrom
        self._diffusion_coefficient = diffusion_coefficient
        self._relaxation_time = relaxation_time

    ################################
    # Properties
    ################################

    @property
    def diffusion_coefficient(self) -> Parameter:
        """
        Get the diffusion coefficient parameter D.

        Returns
        -------
        Parameter
            Diffusion coefficient D.
        """
        return self._diffusion_coefficient

    @diffusion_coefficient.setter
    def diffusion_coefficient(self, diffusion_coefficient: Numeric) -> None:
        """
        Set the diffusion coefficient parameter D.

        Parameters
        ----------
        diffusion_coefficient : Numeric
            Diffusion coefficient D in m^2/s.

        Raises
        ------
        TypeError
            If diffusion_coefficient is not a number.
        ValueError
            If diffusion_coefficient is negative.
        """
        if not isinstance(diffusion_coefficient, Numeric):
            raise TypeError('diffusion_coefficient must be a number.')
        if float(diffusion_coefficient) < 0:
            raise ValueError('diffusion_coefficient must be non-negative.')
        self._diffusion_coefficient.value = float(diffusion_coefficient)

    @property
    def relaxation_time(self) -> Parameter:
        """
        Get the relaxation time parameter t.

        Returns
        -------
        Parameter
            Relaxation time t in ps.
        """
        return self._relaxation_time

    @relaxation_time.setter
    def relaxation_time(self, relaxation_time: Numeric) -> None:
        """
        Set the relaxation time parameter t.

        Parameters
        ----------
        relaxation_time : Numeric
            Relaxation time t in ps.

        Raises
        ------
        TypeError
            If relaxation_time is not a number.
        ValueError
            If relaxation_time is negative.
        """
        if not isinstance(relaxation_time, Numeric):
            raise TypeError('relaxation_time must be a number.')

        if float(relaxation_time) < 0:
            raise ValueError('relaxation_time must be non-negative.')
        self._relaxation_time.value = float(relaxation_time)

    ################################
    # Other methods
    ################################

    def calculate_width(self, Q: Q_type) -> np.ndarray:
        r"""
        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
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom. Can be a single value or an array of values.

        Returns
        -------
        np.ndarray
            HWHM values in the unit of the model (e.g., meV).
        """

        Q = _validate_and_convert_Q(Q)

        unit_conversion_factor_numerator = (
            self._hbar * self.diffusion_coefficient / (self._angstrom**2)
        )
        unit_conversion_factor_numerator.convert_unit(self.unit)

        numerator = unit_conversion_factor_numerator.value * Q**2

        unit_conversion_factor_denominator = (
            self.diffusion_coefficient / self._angstrom**2 * self.relaxation_time
        )
        unit_conversion_factor_denominator.convert_unit('dimensionless')

        denominator = 1 + unit_conversion_factor_denominator.value * Q**2

        return numerator / denominator

    def calculate_EISF(self, Q: Q_type) -> np.ndarray:
        """
        Calculate the Elastic Incoherent Structure Factor (EISF).

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom. Can be a single value or an array of values.

        Returns
        -------
        np.ndarray
            EISF values (dimensionless).
        """
        Q = _validate_and_convert_Q(Q)
        return np.zeros_like(Q)

    def calculate_QISF(self, Q: Q_type) -> np.ndarray:
        """
        Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom. Can be a single value or an array of values.

        Returns
        -------
        np.ndarray
            QISF values (dimensionless).
        """
        Q = _validate_and_convert_Q(Q)
        return np.ones_like(Q)

    def create_component_collections(
        self,
        Q: Q_type,
        component_name: str = 'Jump translational diffusion',
        component_display_name: str = 'Jump translational diffusion',
    ) -> list[ComponentCollection]:
        """
        Create ComponentCollection components for the diffusion model at given Q values.

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom. Can be a single value or an array of values.
        component_name : str, default='Jump translational diffusion'
            Name of the Jump Diffusion Lorentzian component.
        component_display_name : str, default='Jump translational diffusion'
            Name of the Jump Diffusion Lorentzian component.

        Raises
        ------
        TypeError
            If component_display_name is not a string. If component_name is not a string.

        Returns
        -------
        list[ComponentCollection]
            List of ComponentCollections with Jump Diffusion Lorentzian components.
        """
        Q = _validate_and_convert_Q(Q)

        if not isinstance(component_display_name, str):
            raise TypeError('component_display_name must be a string.')

        if not isinstance(component_name, str):
            raise TypeError('component_name must be a string.')

        component_collection_list = [None] * len(Q)
        # In more complex models, this is used to scale the area of the
        # Lorentzians and the delta function.
        QISF = self.calculate_QISF(Q)

        # Create a Lorentzian component for each Q-value, with width
        # D*Q^2 and area equal to scale. No delta function, as the EISF
        # is 0.
        for i, Q_value in enumerate(Q):
            component_collection_list[i] = ComponentCollection(
                name=f'{self.name}_Q{Q_value:.2f}',
                display_name=f'{self.display_name}_Q{Q_value:.2f}',
                unit=self.unit,
            )

            lorentzian_component = Lorentzian(
                name=component_name,
                display_name=component_display_name,
                unit=self.unit,
            )

            # Make the width dependent on Q
            dependency_expression = self._write_width_dependency_expression(Q[i])
            dependency_map = self._write_width_dependency_map_expression()

            lorentzian_component.width.make_dependent_on(
                dependency_expression=dependency_expression,
                dependency_map=dependency_map,
                desired_unit=self.unit,
            )

            # Make the area dependent on Q
            area_dependency_map = self._write_area_dependency_map_expression()
            lorentzian_component.area.make_dependent_on(
                dependency_expression=self._write_area_dependency_expression(QISF[i]),
                dependency_map=area_dependency_map,
            )

            component_collection_list[i].append_component(lorentzian_component)

        return component_collection_list

    ################################
    # Private methods
    ################################

    def _write_width_dependency_expression(self, Q: float) -> str:
        """
        Write the dependency expression for the width as a function of Q to make dependent
        Parameters.

        Parameters
        ----------
        Q : float
            Scattering vector in 1/angstrom.

        Raises
        ------
        TypeError
            If Q is not a float.

        Returns
        -------
        str
            Dependency expression for the width.
        """
        if not isinstance(Q, (float)):
            raise TypeError('Q must be a float.')

        # Q is given as a float, so we need to add the units
        return f'hbar * D* {Q} **2/(angstrom**2)/(1 + (D * t* {Q} **2/(angstrom**2)))'

    def _write_width_dependency_map_expression(self) -> dict[str, DescriptorNumber]:
        """
        Write the dependency map expression to make dependent Parameters.

        Returns
        -------
        dict[str, DescriptorNumber]
            Dependency map for the width.
        """
        return {
            'D': self._diffusion_coefficient,
            't': self._relaxation_time,
            'hbar': self._hbar,
            'angstrom': self._angstrom,
        }

    def _write_area_dependency_expression(self, QISF: float) -> str:
        """
        Write the dependency expression for the area to make dependent Parameters.

        Parameters
        ----------
        QISF : float
            Q-dependent intermediate scattering function.

        Raises
        ------
        TypeError
            If QISF is not a float.

        Returns
        -------
        str
            Dependency expression for the area.
        """

        if not isinstance(QISF, (float)):
            raise TypeError('QISF must be a float.')

        return f'{QISF} * scale'

    def _write_area_dependency_map_expression(self) -> dict[str, DescriptorNumber]:
        """
        Write the dependency map expression to make dependent Parameters.

        Returns
        -------
        dict[str, DescriptorNumber]
            Dependency map for the area.
        """
        return {
            'scale': self._scale,
        }

    ################################
    # dunder methods
    ################################

    def __repr__(self) -> str:
        """
        String representation of the JumpTranslationalDiffusion model.

        Returns
        -------
        str
            String representation of the JumpTranslationalDiffusion model.
        """
        return (
            f'JumpTranslationalDiffusion(name={self.name}, display_name={self.display_name},\n '
            f'    diffusion_coefficient={self._diffusion_coefficient}, \n'
            f'    scale={self._scale})'
        )

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.

__init__(scale=1.0, diffusion_coefficient=1.0, relaxation_time=1.0, unit='meV', name='JumpTranslationalDiffusion', display_name='JumpTranslationalDiffusion', unique_name=None)

Initialize a new JumpTranslationalDiffusion model.

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
unit	str | sc.Unit	Unit of the diffusion model. Must be convertible to meV.	'meV'
name	str	Name of the diffusion model.	'JumpTranslationalDiffusion'
display_name	str | None	Display name of the diffusion model.	'JumpTranslationalDiffusion'
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.

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

def __init__(
    self,
    scale: Numeric = 1.0,
    diffusion_coefficient: Numeric = 1.0,
    relaxation_time: Numeric = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'JumpTranslationalDiffusion',
    display_name: str | None = 'JumpTranslationalDiffusion',
    unique_name: str | None = None,
) -> None:
    """
    Initialize a new JumpTranslationalDiffusion model.

    Parameters
    ----------
    scale : Numeric, default=1.0
        Scale factor for the diffusion model. Must be a non-negative number.
    diffusion_coefficient : Numeric, default=1.0
        Diffusion coefficient D in m^2/s.
    relaxation_time : Numeric, default=1.0
        Relaxation time t in ps.
    unit : str | sc.Unit, default='meV'
        Unit of the diffusion model. Must be convertible to meV.
    name : str, default='JumpTranslationalDiffusion'
        Name of the diffusion model.
    display_name : str | None, default='JumpTranslationalDiffusion'
        Display name of the diffusion model.
    unique_name : str | None, default=None
        Unique name of the diffusion model. If None, a unique name will be generated. By
        default, None.

    Raises
    ------
    TypeError
        If scale, diffusion_coefficient, or relaxation_time  are not numbers.
    """
    super().__init__(
        name=name,
        display_name=display_name,
        unique_name=unique_name,
        unit=unit,
        scale=scale,
    )

    if not isinstance(diffusion_coefficient, Numeric):
        raise TypeError('diffusion_coefficient must be a number.')

    if not isinstance(relaxation_time, Numeric):
        raise TypeError('relaxation_time must be a number.')

    diffusion_coefficient = Parameter(
        name='diffusion_coefficient',
        value=float(diffusion_coefficient),
        fixed=False,
        unit='m**2/s',
    )

    relaxation_time = Parameter(
        name='relaxation_time',
        value=float(relaxation_time),
        fixed=False,
        unit='ps',
    )

    self._hbar = hbar
    self._angstrom = angstrom
    self._diffusion_coefficient = diffusion_coefficient
    self._relaxation_time = relaxation_time

calculate_width(Q)

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	Scattering vector in 1/angstrom. Can be a single value or an array of values.	required

Returns:

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

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

def calculate_width(self, Q: Q_type) -> np.ndarray:
    r"""
    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
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom. Can be a single value or an array of values.

    Returns
    -------
    np.ndarray
        HWHM values in the unit of the model (e.g., meV).
    """

    Q = _validate_and_convert_Q(Q)

    unit_conversion_factor_numerator = (
        self._hbar * self.diffusion_coefficient / (self._angstrom**2)
    )
    unit_conversion_factor_numerator.convert_unit(self.unit)

    numerator = unit_conversion_factor_numerator.value * Q**2

    unit_conversion_factor_denominator = (
        self.diffusion_coefficient / self._angstrom**2 * self.relaxation_time
    )
    unit_conversion_factor_denominator.convert_unit('dimensionless')

    denominator = 1 + unit_conversion_factor_denominator.value * Q**2

    return numerator / denominator

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).

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

def calculate_EISF(self, Q: Q_type) -> np.ndarray:
    """
    Calculate the Elastic Incoherent Structure Factor (EISF).

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom. Can be a single value or an array of values.

    Returns
    -------
    np.ndarray
        EISF values (dimensionless).
    """
    Q = _validate_and_convert_Q(Q)
    return np.zeros_like(Q)

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).

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

def calculate_QISF(self, Q: Q_type) -> np.ndarray:
    """
    Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom. Can be a single value or an array of values.

    Returns
    -------
    np.ndarray
        QISF values (dimensionless).
    """
    Q = _validate_and_convert_Q(Q)
    return np.ones_like(Q)

create_component_collections(Q, component_name='Jump translational diffusion', component_display_name='Jump translational diffusion')

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

Parameters:

Name	Type	Description	Default
Q	Q_type	Scattering vector in 1/angstrom. Can be a single value or an array of values.	required
component_name	str	Name of the Jump Diffusion Lorentzian component.	'Jump translational diffusion'
component_display_name	str	Name of the Jump Diffusion Lorentzian component.	'Jump translational diffusion'

Raises:

Type	Description
TypeError	If component_display_name is not a string. If component_name is not a string.

Returns:

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

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

def create_component_collections(
    self,
    Q: Q_type,
    component_name: str = 'Jump translational diffusion',
    component_display_name: str = 'Jump translational diffusion',
) -> list[ComponentCollection]:
    """
    Create ComponentCollection components for the diffusion model at given Q values.

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom. Can be a single value or an array of values.
    component_name : str, default='Jump translational diffusion'
        Name of the Jump Diffusion Lorentzian component.
    component_display_name : str, default='Jump translational diffusion'
        Name of the Jump Diffusion Lorentzian component.

    Raises
    ------
    TypeError
        If component_display_name is not a string. If component_name is not a string.

    Returns
    -------
    list[ComponentCollection]
        List of ComponentCollections with Jump Diffusion Lorentzian components.
    """
    Q = _validate_and_convert_Q(Q)

    if not isinstance(component_display_name, str):
        raise TypeError('component_display_name must be a string.')

    if not isinstance(component_name, str):
        raise TypeError('component_name must be a string.')

    component_collection_list = [None] * len(Q)
    # In more complex models, this is used to scale the area of the
    # Lorentzians and the delta function.
    QISF = self.calculate_QISF(Q)

    # Create a Lorentzian component for each Q-value, with width
    # D*Q^2 and area equal to scale. No delta function, as the EISF
    # is 0.
    for i, Q_value in enumerate(Q):
        component_collection_list[i] = ComponentCollection(
            name=f'{self.name}_Q{Q_value:.2f}',
            display_name=f'{self.display_name}_Q{Q_value:.2f}',
            unit=self.unit,
        )

        lorentzian_component = Lorentzian(
            name=component_name,
            display_name=component_display_name,
            unit=self.unit,
        )

        # Make the width dependent on Q
        dependency_expression = self._write_width_dependency_expression(Q[i])
        dependency_map = self._write_width_dependency_map_expression()

        lorentzian_component.width.make_dependent_on(
            dependency_expression=dependency_expression,
            dependency_map=dependency_map,
            desired_unit=self.unit,
        )

        # Make the area dependent on Q
        area_dependency_map = self._write_area_dependency_map_expression()
        lorentzian_component.area.make_dependent_on(
            dependency_expression=self._write_area_dependency_expression(QISF[i]),
            dependency_map=area_dependency_map,
        )

        component_collection_list[i].append_component(lorentzian_component)

    return component_collection_list

__repr__()

String representation of the JumpTranslationalDiffusion model.

Returns:

Type	Description
str	String representation of the JumpTranslationalDiffusion model.

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

def __repr__(self) -> str:
    """
    String representation of the JumpTranslationalDiffusion model.

    Returns
    -------
    str
        String representation of the JumpTranslationalDiffusion model.
    """
    return (
        f'JumpTranslationalDiffusion(name={self.name}, display_name={self.display_name},\n '
        f'    diffusion_coefficient={self._diffusion_coefficient}, \n'
        f'    scale={self._scale})'
    )

brownian_translational_diffusion

BrownianTranslationalDiffusion

Bases: DiffusionModelBase

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:

>>> Q=np.linspace(0.5,2,7) >>>energy=np.linspace(-2, 2, 501)
>>> scale = 1.0
>>> diffusion_coefficient = 2.4e-9  # m^2/s
>>> diffusion_model=BrownianTranslationalDiffusion(name="DiffusionModel",
>>> scale=scale, diffusion_coefficient= diffusion_coefficient,)
>>> component_collections = diffusion_model.create_component_collections(Q)

See also the tutorials.

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

class BrownianTranslationalDiffusion(DiffusionModelBase):
    r"""
    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
    --------
    >>> Q=np.linspace(0.5,2,7) >>>energy=np.linspace(-2, 2, 501)
    >>> scale = 1.0
    >>> diffusion_coefficient = 2.4e-9  # m^2/s
    >>> diffusion_model=BrownianTranslationalDiffusion(name="DiffusionModel",
    >>> scale=scale, diffusion_coefficient= diffusion_coefficient,)
    >>> component_collections = diffusion_model.create_component_collections(Q)

    See also the tutorials.
    """

    def __init__(
        self,
        scale: Numeric = 1.0,
        diffusion_coefficient: Numeric = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'BrownianTranslationalDiffusion',
        display_name: str | None = 'BrownianTranslationalDiffusion',
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize a new BrownianTranslationalDiffusion model.

        Parameters
        ----------
        scale : Numeric, default=1.0
            Scale factor for the diffusion model. Must be a non-negative number.
        diffusion_coefficient : Numeric, default=1.0
            Diffusion coefficient D in m^2/s.
        unit : str | sc.Unit, default='meV'
            Unit of the diffusion model. Must be convertible to meV.
        name : str, default='BrownianTranslationalDiffusion'
            Name of the diffusion model.
        display_name : str | None, default='BrownianTranslationalDiffusion'
            Display name of the diffusion model.
        unique_name : str | None, default=None
            Unique name of the diffusion model. If None, a unique name will be generated. By
            default, None.

        Raises
        ------
        TypeError
            If scale or diffusion_coefficient is not a number.
        """
        if not isinstance(scale, Numeric):
            raise TypeError('scale must be a number.')

        if not isinstance(diffusion_coefficient, Numeric):
            raise TypeError('diffusion_coefficient must be a number.')

        diffusion_coefficient = Parameter(
            name='diffusion_coefficient',
            value=float(diffusion_coefficient),
            fixed=False,
            unit='m**2/s',
            min=0.0,
        )
        super().__init__(
            unit=unit,
            scale=scale,
            name=name,
            display_name=display_name,
            unique_name=unique_name,
        )
        self._hbar = hbar
        self._angstrom = angstrom
        self._diffusion_coefficient = diffusion_coefficient

    # ------------------------------------------------------------------
    # Properties
    # ------------------------------------------------------------------

    @property
    def diffusion_coefficient(self) -> Parameter:
        """
        Get the diffusion coefficient parameter D.

        Returns
        -------
        Parameter
            Diffusion coefficient D in m^2/s.
        """
        return self._diffusion_coefficient

    @diffusion_coefficient.setter
    def diffusion_coefficient(self, diffusion_coefficient: Numeric) -> None:
        """
        Set the diffusion coefficient parameter D.

        Parameters
        ----------
        diffusion_coefficient : Numeric
            The new value for the diffusion coefficient D in m^2/s.

        Raises
        ------
        TypeError
            If diffusion_coefficient is not a number.
        ValueError
            If diffusion_coefficient is negative.
        """
        if not isinstance(diffusion_coefficient, Numeric):
            raise TypeError('diffusion_coefficient must be a number.')

        if float(diffusion_coefficient) < 0:
            raise ValueError('diffusion_coefficient must be non-negative.')
        self._diffusion_coefficient.value = float(diffusion_coefficient)

    # ------------------------------------------------------------------
    # Other methods
    # ------------------------------------------------------------------

    def calculate_width(self, Q: Q_type) -> np.ndarray:
        """
        Calculate the half-width at half-maximum (HWHM) for the diffusion model.

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom.

        Returns
        -------
        np.ndarray
            HWHM values in the unit of the model (e.g., meV).
        """

        Q = _validate_and_convert_Q(Q)

        unit_conversion_factor = self._hbar * self.diffusion_coefficient / (self._angstrom**2)
        unit_conversion_factor.convert_unit(self.unit)
        return Q**2 * unit_conversion_factor.value

    def calculate_EISF(self, Q: Q_type) -> np.ndarray:
        """
        Calculate the Elastic Incoherent Structure Factor (EISF) for the Brownian translational
        diffusion model.

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom.

        Returns
        -------
        np.ndarray
            EISF values (dimensionless).
        """
        Q = _validate_and_convert_Q(Q)
        return np.zeros_like(Q)

    def calculate_QISF(self, Q: Q_type) -> np.ndarray:
        """
        Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom.

        Returns
        -------
        np.ndarray
            QISF values (dimensionless).
        """

        Q = _validate_and_convert_Q(Q)
        return np.ones_like(Q)

    def create_component_collections(
        self,
        Q: Q_type,
        component_name: str = 'Brownian diffusion',
        component_display_name: str | None = None,
    ) -> list[ComponentCollection]:
        r"""
        Create ComponentCollection components for the Brownian translational diffusion model at
        given Q values.

        Parameters
        ----------
        Q : Q_type
            Scattering vector values.
        component_name : str, default='Brownian diffusion'
            Name of the Brownian diffusion component.
        component_display_name : str | None, default=None
            Display name of the Brownian diffusion component.

        Raises
        ------
        TypeError
            If component_display_name is not a string. If component_name is not a string.

        Returns
        -------
        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).
        """
        Q = _validate_and_convert_Q(Q)

        if not isinstance(component_name, str):
            raise TypeError('component_name must be a string.')

        if component_display_name is None:
            component_display_name = component_name

        if not isinstance(component_display_name, str):
            raise TypeError('component_display_name must be a string.')

        component_collection_list = [None] * len(Q)
        # In more complex models, this is used to scale the area of the
        # Lorentzians and the delta function.
        QISF = self.calculate_QISF(Q)

        # Create a Lorentzian component for each Q-value, with
        # width D*Q^2 and area equal to scale.
        # No delta function, as the EISF is 0.
        for i, Q_value in enumerate(Q):
            component_collection_list[i] = ComponentCollection(
                name=f'{self.name}_Q{Q_value:.2f}',
                display_name=f'{self.display_name}_Q{Q_value:.2f}',
                unit=self.unit,
            )

            lorentzian_component = Lorentzian(
                name=component_name,
                display_name=component_display_name,
                unit=self.unit,
            )

            # Make the width dependent on Q
            dependency_expression = self._write_width_dependency_expression(Q[i])
            dependency_map = self._write_width_dependency_map_expression()

            lorentzian_component.width.make_dependent_on(
                dependency_expression=dependency_expression,
                dependency_map=dependency_map,
                desired_unit=self.unit,
            )

            # Make the area dependent on Q
            area_dependency_map = self._write_area_dependency_map_expression()
            lorentzian_component.area.make_dependent_on(
                dependency_expression=self._write_area_dependency_expression(QISF[i]),
                dependency_map=area_dependency_map,
            )

            component_collection_list[i].append_component(lorentzian_component)

        return component_collection_list

    # ------------------------------------------------------------------
    # Private methods
    # ------------------------------------------------------------------

    def _write_width_dependency_expression(self, Q: float) -> str:
        """
        Write the dependency expression for the width as a function of Q to make dependent
        Parameters.

        Parameters
        ----------
        Q : float
            Scattering vector in 1/angstrom.

        Raises
        ------
        TypeError
            If Q is not a float.

        Returns
        -------
        str
            Dependency expression for the width.
        """
        if not isinstance(Q, (float)):
            raise TypeError('Q must be a float.')

        # Q is given as a float, so we need to add the units
        return f'hbar * D* {Q} **2*1/(angstrom**2)'

    def _write_width_dependency_map_expression(self) -> dict[str, DescriptorNumber]:
        """
        Write the dependency map expression to make dependent Parameters.

        Returns
        -------
        dict[str, DescriptorNumber]
            Dependency map for the width.
        """
        return {
            'D': self.diffusion_coefficient,
            'hbar': self._hbar,
            'angstrom': self._angstrom,
        }

    def _write_area_dependency_expression(self, QISF: float) -> str:
        """
        Write the dependency expression for the area to make dependent Parameters.

        Parameters
        ----------
        QISF : float
            Quasielastic Incoherent Scattering Function.

        Raises
        ------
        TypeError
            If QISF is not a float.

        Returns
        -------
        str
            Dependency expression for the area.
        """
        if not isinstance(QISF, (float)):
            raise TypeError('QISF must be a float.')

        return f'{QISF} * scale'

    def _write_area_dependency_map_expression(self) -> dict[str, DescriptorNumber]:
        """
        Write the dependency map expression to make dependent Parameters.

        Returns
        -------
        dict[str, DescriptorNumber]
            Dependency map for the area.
        """
        return {
            'scale': self.scale,
        }

    # ------------------------------------------------------------------
    # dunder methods
    # ------------------------------------------------------------------

    def __repr__(self) -> str:
        """
        String representation of the BrownianTranslationalDiffusion model.

        Returns
        -------
        str
            String representation of the BrownianTranslationalDiffusion model.
        """
        return (
            f'BrownianTranslationalDiffusion(name={self.name}, '
            f'display_name={self.display_name}, \n'
            f'    diffusion_coefficient={self.diffusion_coefficient}, \n'
            f'    scale={self.scale})'
        )

diffusion_coefficient property writable

Get the diffusion coefficient parameter D.

Returns:

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

__init__(scale=1.0, diffusion_coefficient=1.0, unit='meV', name='BrownianTranslationalDiffusion', display_name='BrownianTranslationalDiffusion', unique_name=None)

Initialize a new BrownianTranslationalDiffusion model.

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
unit	str | sc.Unit	Unit of the diffusion model. Must be convertible to meV.	'meV'
name	str	Name of the diffusion model.	'BrownianTranslationalDiffusion'
display_name	str | None	Display name of the diffusion model.	'BrownianTranslationalDiffusion'
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.

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def __init__(
    self,
    scale: Numeric = 1.0,
    diffusion_coefficient: Numeric = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'BrownianTranslationalDiffusion',
    display_name: str | None = 'BrownianTranslationalDiffusion',
    unique_name: str | None = None,
) -> None:
    """
    Initialize a new BrownianTranslationalDiffusion model.

    Parameters
    ----------
    scale : Numeric, default=1.0
        Scale factor for the diffusion model. Must be a non-negative number.
    diffusion_coefficient : Numeric, default=1.0
        Diffusion coefficient D in m^2/s.
    unit : str | sc.Unit, default='meV'
        Unit of the diffusion model. Must be convertible to meV.
    name : str, default='BrownianTranslationalDiffusion'
        Name of the diffusion model.
    display_name : str | None, default='BrownianTranslationalDiffusion'
        Display name of the diffusion model.
    unique_name : str | None, default=None
        Unique name of the diffusion model. If None, a unique name will be generated. By
        default, None.

    Raises
    ------
    TypeError
        If scale or diffusion_coefficient is not a number.
    """
    if not isinstance(scale, Numeric):
        raise TypeError('scale must be a number.')

    if not isinstance(diffusion_coefficient, Numeric):
        raise TypeError('diffusion_coefficient must be a number.')

    diffusion_coefficient = Parameter(
        name='diffusion_coefficient',
        value=float(diffusion_coefficient),
        fixed=False,
        unit='m**2/s',
        min=0.0,
    )
    super().__init__(
        unit=unit,
        scale=scale,
        name=name,
        display_name=display_name,
        unique_name=unique_name,
    )
    self._hbar = hbar
    self._angstrom = angstrom
    self._diffusion_coefficient = diffusion_coefficient

calculate_width(Q)

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

Parameters:

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

Returns:

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

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def calculate_width(self, Q: Q_type) -> np.ndarray:
    """
    Calculate the half-width at half-maximum (HWHM) for the diffusion model.

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom.

    Returns
    -------
    np.ndarray
        HWHM values in the unit of the model (e.g., meV).
    """

    Q = _validate_and_convert_Q(Q)

    unit_conversion_factor = self._hbar * self.diffusion_coefficient / (self._angstrom**2)
    unit_conversion_factor.convert_unit(self.unit)
    return Q**2 * unit_conversion_factor.value

calculate_EISF(Q)

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

Parameters:

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

Returns:

Type	Description
np.ndarray	EISF values (dimensionless).

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def calculate_EISF(self, Q: Q_type) -> np.ndarray:
    """
    Calculate the Elastic Incoherent Structure Factor (EISF) for the Brownian translational
    diffusion model.

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom.

    Returns
    -------
    np.ndarray
        EISF values (dimensionless).
    """
    Q = _validate_and_convert_Q(Q)
    return np.zeros_like(Q)

calculate_QISF(Q)

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

Parameters:

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

Returns:

Type	Description
np.ndarray	QISF values (dimensionless).

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def calculate_QISF(self, Q: Q_type) -> np.ndarray:
    """
    Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom.

    Returns
    -------
    np.ndarray
        QISF values (dimensionless).
    """

    Q = _validate_and_convert_Q(Q)
    return np.ones_like(Q)

create_component_collections(Q, component_name='Brownian diffusion', component_display_name=None)

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

Parameters:

Name	Type	Description	Default
Q	Q_type	Scattering vector values.	required
component_name	str	Name of the Brownian diffusion component.	'Brownian diffusion'
component_display_name	str | None	Display name of the Brownian diffusion component.	None

Raises:

Type	Description
TypeError	If component_display_name is not a string. If component_name is not a string.

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).

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def create_component_collections(
    self,
    Q: Q_type,
    component_name: str = 'Brownian diffusion',
    component_display_name: str | None = None,
) -> list[ComponentCollection]:
    r"""
    Create ComponentCollection components for the Brownian translational diffusion model at
    given Q values.

    Parameters
    ----------
    Q : Q_type
        Scattering vector values.
    component_name : str, default='Brownian diffusion'
        Name of the Brownian diffusion component.
    component_display_name : str | None, default=None
        Display name of the Brownian diffusion component.

    Raises
    ------
    TypeError
        If component_display_name is not a string. If component_name is not a string.

    Returns
    -------
    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).
    """
    Q = _validate_and_convert_Q(Q)

    if not isinstance(component_name, str):
        raise TypeError('component_name must be a string.')

    if component_display_name is None:
        component_display_name = component_name

    if not isinstance(component_display_name, str):
        raise TypeError('component_display_name must be a string.')

    component_collection_list = [None] * len(Q)
    # In more complex models, this is used to scale the area of the
    # Lorentzians and the delta function.
    QISF = self.calculate_QISF(Q)

    # Create a Lorentzian component for each Q-value, with
    # width D*Q^2 and area equal to scale.
    # No delta function, as the EISF is 0.
    for i, Q_value in enumerate(Q):
        component_collection_list[i] = ComponentCollection(
            name=f'{self.name}_Q{Q_value:.2f}',
            display_name=f'{self.display_name}_Q{Q_value:.2f}',
            unit=self.unit,
        )

        lorentzian_component = Lorentzian(
            name=component_name,
            display_name=component_display_name,
            unit=self.unit,
        )

        # Make the width dependent on Q
        dependency_expression = self._write_width_dependency_expression(Q[i])
        dependency_map = self._write_width_dependency_map_expression()

        lorentzian_component.width.make_dependent_on(
            dependency_expression=dependency_expression,
            dependency_map=dependency_map,
            desired_unit=self.unit,
        )

        # Make the area dependent on Q
        area_dependency_map = self._write_area_dependency_map_expression()
        lorentzian_component.area.make_dependent_on(
            dependency_expression=self._write_area_dependency_expression(QISF[i]),
            dependency_map=area_dependency_map,
        )

        component_collection_list[i].append_component(lorentzian_component)

    return component_collection_list

__repr__()

String representation of the BrownianTranslationalDiffusion model.

Returns:

Type	Description
str	String representation of the BrownianTranslationalDiffusion model.

Source code in src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py

def __repr__(self) -> str:
    """
    String representation of the BrownianTranslationalDiffusion model.

    Returns
    -------
    str
        String representation of the BrownianTranslationalDiffusion model.
    """
    return (
        f'BrownianTranslationalDiffusion(name={self.name}, '
        f'display_name={self.display_name}, \n'
        f'    diffusion_coefficient={self.diffusion_coefficient}, \n'
        f'    scale={self.scale})'
    )

diffusion_model_base

DiffusionModelBase

Bases: EasyDynamicsModelBase

Base class for constructing diffusion models.

Source code in src/easydynamics/sample_model/diffusion_model/diffusion_model_base.py

class DiffusionModelBase(EasyDynamicsModelBase):
    """Base class for constructing diffusion models."""

    def __init__(
        self,
        scale: Numeric = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'DiffusionModel',
        display_name: str | None = 'MyDiffusionModel',
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize a new DiffusionModel.

        Parameters
        ----------
        scale : Numeric, default=1.0
            Scale factor for the diffusion model. Must be a non-negative number.
        unit : str | sc.Unit, default='meV'
            Unit of the diffusion model. Must be convertible to meV.
        name : str, default='DiffusionModel'
            Name of the diffusion model.
        display_name : str | None, default='MyDiffusionModel'
            Display name of the diffusion model.
        unique_name : str | None, default=None
            Unique name of the diffusion model. If None, a unique name will be generated. By
            default, None.

        Raises
        ------
        TypeError
            If scale is not a number.
        UnitError
            If unit is not a string or scipp Unit, or if it cannot be converted to meV.
        """

        try:
            test = DescriptorNumber(name='test', value=1, unit=unit)
            test.convert_unit('meV')
        except Exception as e:
            raise UnitError(
                f'Invalid unit: {unit}. Unit must be a string or scipp Unit and convertible to meV.'  # noqa: E501
            ) from e

        if not isinstance(scale, Numeric):
            raise TypeError('scale must be a number.')

        scale = Parameter(name='scale', value=float(scale), fixed=False, min=0.0, unit=unit)

        super().__init__(unit=unit, name=name, display_name=display_name, unique_name=unique_name)
        self._scale = scale

    # ------------------------------------------------------------------
    # Properties
    # ------------------------------------------------------------------

    @property
    def scale(self) -> Parameter:
        """
        Get the scale parameter of the diffusion model.

        Returns
        -------
        Parameter
            Scale parameter of the diffusion model.
        """
        return self._scale

    @scale.setter
    def scale(self, scale: Numeric) -> None:
        """
        Set the scale parameter of the diffusion model.

        Parameters
        ----------
        scale : Numeric
            The new value for the scale parameter. Must be a non-negative number.

        Raises
        ------
        TypeError
            If scale is not a number.
        ValueError
            If scale is negative.
        """
        if not isinstance(scale, Numeric):
            raise TypeError('scale must be a number.')

        if float(scale) < 0:
            raise ValueError('scale must be non-negative.')
        self._scale.value = float(scale)

    # ------------------------------------------------------------------
    # dunder methods
    # ------------------------------------------------------------------

    def __repr__(self) -> str:
        """
        String representation of the Diffusion model.

        Returns
        -------
        str
            String representation of the DiffusionModel.
        """
        return (
            f'{self.__class__.__name__}(name={self.name}, display_name={self.display_name}, '
            f'unit={self.unit}), \n'
            f'    scale={self.scale})'
        )

scale property writable

Get the scale parameter of the diffusion model.

Returns:

Type	Description
Parameter	Scale parameter of the diffusion model.

__init__(scale=1.0, unit='meV', name='DiffusionModel', display_name='MyDiffusionModel', unique_name=None)

Initialize a new DiffusionModel.

Parameters:

Name	Type	Description	Default
scale	Numeric	Scale factor for the diffusion model. Must be a non-negative number.	1.0
unit	str | sc.Unit	Unit of the diffusion model. Must be convertible to meV.	'meV'
name	str	Name of the diffusion model.	'DiffusionModel'
display_name	str | None	Display name of the diffusion model.	'MyDiffusionModel'
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.
UnitError	If unit is not a string or scipp Unit, or if it cannot be converted to meV.

Source code in src/easydynamics/sample_model/diffusion_model/diffusion_model_base.py

def __init__(
    self,
    scale: Numeric = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'DiffusionModel',
    display_name: str | None = 'MyDiffusionModel',
    unique_name: str | None = None,
) -> None:
    """
    Initialize a new DiffusionModel.

    Parameters
    ----------
    scale : Numeric, default=1.0
        Scale factor for the diffusion model. Must be a non-negative number.
    unit : str | sc.Unit, default='meV'
        Unit of the diffusion model. Must be convertible to meV.
    name : str, default='DiffusionModel'
        Name of the diffusion model.
    display_name : str | None, default='MyDiffusionModel'
        Display name of the diffusion model.
    unique_name : str | None, default=None
        Unique name of the diffusion model. If None, a unique name will be generated. By
        default, None.

    Raises
    ------
    TypeError
        If scale is not a number.
    UnitError
        If unit is not a string or scipp Unit, or if it cannot be converted to meV.
    """

    try:
        test = DescriptorNumber(name='test', value=1, unit=unit)
        test.convert_unit('meV')
    except Exception as e:
        raise UnitError(
            f'Invalid unit: {unit}. Unit must be a string or scipp Unit and convertible to meV.'  # noqa: E501
        ) from e

    if not isinstance(scale, Numeric):
        raise TypeError('scale must be a number.')

    scale = Parameter(name='scale', value=float(scale), fixed=False, min=0.0, unit=unit)

    super().__init__(unit=unit, name=name, display_name=display_name, unique_name=unique_name)
    self._scale = scale

__repr__()

String representation of the Diffusion model.

Returns:

Type	Description
str	String representation of the DiffusionModel.

Source code in src/easydynamics/sample_model/diffusion_model/diffusion_model_base.py

def __repr__(self) -> str:
    """
    String representation of the Diffusion model.

    Returns
    -------
    str
        String representation of the DiffusionModel.
    """
    return (
        f'{self.__class__.__name__}(name={self.name}, display_name={self.display_name}, '
        f'unit={self.unit}), \n'
        f'    scale={self.scale})'
    )

jump_translational_diffusion

JumpTranslationalDiffusion

Bases: DiffusionModelBase

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:

>>> Q = np.linspace(0.5, 2, 7)
>>> energy = np.linspace(-2, 2, 501)
>>> scale = 1.0
>>> diffusion_coefficient = 2.4e-9  # m^2/s
>>> relaxation_time = 1.0  # ps
>>> diffusion_model = JumpTranslationalDiffusion(
...     scale=scale,
...     diffusion_coefficient=diffusion_coefficient,
...     relaxation_time=relaxation_time,
... )
>>> component_collections = diffusion_model.create_component_collections(Q)

See also the tutorials..

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

class JumpTranslationalDiffusion(DiffusionModelBase):
    r"""
    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
    --------
    >>> Q = np.linspace(0.5, 2, 7)
    >>> energy = np.linspace(-2, 2, 501)
    >>> scale = 1.0
    >>> diffusion_coefficient = 2.4e-9  # m^2/s
    >>> relaxation_time = 1.0  # ps
    >>> diffusion_model = JumpTranslationalDiffusion(
    ...     scale=scale,
    ...     diffusion_coefficient=diffusion_coefficient,
    ...     relaxation_time=relaxation_time,
    ... )
    >>> component_collections = diffusion_model.create_component_collections(Q)

    See also the tutorials..
    """

    def __init__(
        self,
        scale: Numeric = 1.0,
        diffusion_coefficient: Numeric = 1.0,
        relaxation_time: Numeric = 1.0,
        unit: str | sc.Unit = 'meV',
        name: str = 'JumpTranslationalDiffusion',
        display_name: str | None = 'JumpTranslationalDiffusion',
        unique_name: str | None = None,
    ) -> None:
        """
        Initialize a new JumpTranslationalDiffusion model.

        Parameters
        ----------
        scale : Numeric, default=1.0
            Scale factor for the diffusion model. Must be a non-negative number.
        diffusion_coefficient : Numeric, default=1.0
            Diffusion coefficient D in m^2/s.
        relaxation_time : Numeric, default=1.0
            Relaxation time t in ps.
        unit : str | sc.Unit, default='meV'
            Unit of the diffusion model. Must be convertible to meV.
        name : str, default='JumpTranslationalDiffusion'
            Name of the diffusion model.
        display_name : str | None, default='JumpTranslationalDiffusion'
            Display name of the diffusion model.
        unique_name : str | None, default=None
            Unique name of the diffusion model. If None, a unique name will be generated. By
            default, None.

        Raises
        ------
        TypeError
            If scale, diffusion_coefficient, or relaxation_time  are not numbers.
        """
        super().__init__(
            name=name,
            display_name=display_name,
            unique_name=unique_name,
            unit=unit,
            scale=scale,
        )

        if not isinstance(diffusion_coefficient, Numeric):
            raise TypeError('diffusion_coefficient must be a number.')

        if not isinstance(relaxation_time, Numeric):
            raise TypeError('relaxation_time must be a number.')

        diffusion_coefficient = Parameter(
            name='diffusion_coefficient',
            value=float(diffusion_coefficient),
            fixed=False,
            unit='m**2/s',
        )

        relaxation_time = Parameter(
            name='relaxation_time',
            value=float(relaxation_time),
            fixed=False,
            unit='ps',
        )

        self._hbar = hbar
        self._angstrom = angstrom
        self._diffusion_coefficient = diffusion_coefficient
        self._relaxation_time = relaxation_time

    ################################
    # Properties
    ################################

    @property
    def diffusion_coefficient(self) -> Parameter:
        """
        Get the diffusion coefficient parameter D.

        Returns
        -------
        Parameter
            Diffusion coefficient D.
        """
        return self._diffusion_coefficient

    @diffusion_coefficient.setter
    def diffusion_coefficient(self, diffusion_coefficient: Numeric) -> None:
        """
        Set the diffusion coefficient parameter D.

        Parameters
        ----------
        diffusion_coefficient : Numeric
            Diffusion coefficient D in m^2/s.

        Raises
        ------
        TypeError
            If diffusion_coefficient is not a number.
        ValueError
            If diffusion_coefficient is negative.
        """
        if not isinstance(diffusion_coefficient, Numeric):
            raise TypeError('diffusion_coefficient must be a number.')
        if float(diffusion_coefficient) < 0:
            raise ValueError('diffusion_coefficient must be non-negative.')
        self._diffusion_coefficient.value = float(diffusion_coefficient)

    @property
    def relaxation_time(self) -> Parameter:
        """
        Get the relaxation time parameter t.

        Returns
        -------
        Parameter
            Relaxation time t in ps.
        """
        return self._relaxation_time

    @relaxation_time.setter
    def relaxation_time(self, relaxation_time: Numeric) -> None:
        """
        Set the relaxation time parameter t.

        Parameters
        ----------
        relaxation_time : Numeric
            Relaxation time t in ps.

        Raises
        ------
        TypeError
            If relaxation_time is not a number.
        ValueError
            If relaxation_time is negative.
        """
        if not isinstance(relaxation_time, Numeric):
            raise TypeError('relaxation_time must be a number.')

        if float(relaxation_time) < 0:
            raise ValueError('relaxation_time must be non-negative.')
        self._relaxation_time.value = float(relaxation_time)

    ################################
    # Other methods
    ################################

    def calculate_width(self, Q: Q_type) -> np.ndarray:
        r"""
        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
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom. Can be a single value or an array of values.

        Returns
        -------
        np.ndarray
            HWHM values in the unit of the model (e.g., meV).
        """

        Q = _validate_and_convert_Q(Q)

        unit_conversion_factor_numerator = (
            self._hbar * self.diffusion_coefficient / (self._angstrom**2)
        )
        unit_conversion_factor_numerator.convert_unit(self.unit)

        numerator = unit_conversion_factor_numerator.value * Q**2

        unit_conversion_factor_denominator = (
            self.diffusion_coefficient / self._angstrom**2 * self.relaxation_time
        )
        unit_conversion_factor_denominator.convert_unit('dimensionless')

        denominator = 1 + unit_conversion_factor_denominator.value * Q**2

        return numerator / denominator

    def calculate_EISF(self, Q: Q_type) -> np.ndarray:
        """
        Calculate the Elastic Incoherent Structure Factor (EISF).

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom. Can be a single value or an array of values.

        Returns
        -------
        np.ndarray
            EISF values (dimensionless).
        """
        Q = _validate_and_convert_Q(Q)
        return np.zeros_like(Q)

    def calculate_QISF(self, Q: Q_type) -> np.ndarray:
        """
        Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom. Can be a single value or an array of values.

        Returns
        -------
        np.ndarray
            QISF values (dimensionless).
        """
        Q = _validate_and_convert_Q(Q)
        return np.ones_like(Q)

    def create_component_collections(
        self,
        Q: Q_type,
        component_name: str = 'Jump translational diffusion',
        component_display_name: str = 'Jump translational diffusion',
    ) -> list[ComponentCollection]:
        """
        Create ComponentCollection components for the diffusion model at given Q values.

        Parameters
        ----------
        Q : Q_type
            Scattering vector in 1/angstrom. Can be a single value or an array of values.
        component_name : str, default='Jump translational diffusion'
            Name of the Jump Diffusion Lorentzian component.
        component_display_name : str, default='Jump translational diffusion'
            Name of the Jump Diffusion Lorentzian component.

        Raises
        ------
        TypeError
            If component_display_name is not a string. If component_name is not a string.

        Returns
        -------
        list[ComponentCollection]
            List of ComponentCollections with Jump Diffusion Lorentzian components.
        """
        Q = _validate_and_convert_Q(Q)

        if not isinstance(component_display_name, str):
            raise TypeError('component_display_name must be a string.')

        if not isinstance(component_name, str):
            raise TypeError('component_name must be a string.')

        component_collection_list = [None] * len(Q)
        # In more complex models, this is used to scale the area of the
        # Lorentzians and the delta function.
        QISF = self.calculate_QISF(Q)

        # Create a Lorentzian component for each Q-value, with width
        # D*Q^2 and area equal to scale. No delta function, as the EISF
        # is 0.
        for i, Q_value in enumerate(Q):
            component_collection_list[i] = ComponentCollection(
                name=f'{self.name}_Q{Q_value:.2f}',
                display_name=f'{self.display_name}_Q{Q_value:.2f}',
                unit=self.unit,
            )

            lorentzian_component = Lorentzian(
                name=component_name,
                display_name=component_display_name,
                unit=self.unit,
            )

            # Make the width dependent on Q
            dependency_expression = self._write_width_dependency_expression(Q[i])
            dependency_map = self._write_width_dependency_map_expression()

            lorentzian_component.width.make_dependent_on(
                dependency_expression=dependency_expression,
                dependency_map=dependency_map,
                desired_unit=self.unit,
            )

            # Make the area dependent on Q
            area_dependency_map = self._write_area_dependency_map_expression()
            lorentzian_component.area.make_dependent_on(
                dependency_expression=self._write_area_dependency_expression(QISF[i]),
                dependency_map=area_dependency_map,
            )

            component_collection_list[i].append_component(lorentzian_component)

        return component_collection_list

    ################################
    # Private methods
    ################################

    def _write_width_dependency_expression(self, Q: float) -> str:
        """
        Write the dependency expression for the width as a function of Q to make dependent
        Parameters.

        Parameters
        ----------
        Q : float
            Scattering vector in 1/angstrom.

        Raises
        ------
        TypeError
            If Q is not a float.

        Returns
        -------
        str
            Dependency expression for the width.
        """
        if not isinstance(Q, (float)):
            raise TypeError('Q must be a float.')

        # Q is given as a float, so we need to add the units
        return f'hbar * D* {Q} **2/(angstrom**2)/(1 + (D * t* {Q} **2/(angstrom**2)))'

    def _write_width_dependency_map_expression(self) -> dict[str, DescriptorNumber]:
        """
        Write the dependency map expression to make dependent Parameters.

        Returns
        -------
        dict[str, DescriptorNumber]
            Dependency map for the width.
        """
        return {
            'D': self._diffusion_coefficient,
            't': self._relaxation_time,
            'hbar': self._hbar,
            'angstrom': self._angstrom,
        }

    def _write_area_dependency_expression(self, QISF: float) -> str:
        """
        Write the dependency expression for the area to make dependent Parameters.

        Parameters
        ----------
        QISF : float
            Q-dependent intermediate scattering function.

        Raises
        ------
        TypeError
            If QISF is not a float.

        Returns
        -------
        str
            Dependency expression for the area.
        """

        if not isinstance(QISF, (float)):
            raise TypeError('QISF must be a float.')

        return f'{QISF} * scale'

    def _write_area_dependency_map_expression(self) -> dict[str, DescriptorNumber]:
        """
        Write the dependency map expression to make dependent Parameters.

        Returns
        -------
        dict[str, DescriptorNumber]
            Dependency map for the area.
        """
        return {
            'scale': self._scale,
        }

    ################################
    # dunder methods
    ################################

    def __repr__(self) -> str:
        """
        String representation of the JumpTranslationalDiffusion model.

        Returns
        -------
        str
            String representation of the JumpTranslationalDiffusion model.
        """
        return (
            f'JumpTranslationalDiffusion(name={self.name}, display_name={self.display_name},\n '
            f'    diffusion_coefficient={self._diffusion_coefficient}, \n'
            f'    scale={self._scale})'
        )

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.

__init__(scale=1.0, diffusion_coefficient=1.0, relaxation_time=1.0, unit='meV', name='JumpTranslationalDiffusion', display_name='JumpTranslationalDiffusion', unique_name=None)

Initialize a new JumpTranslationalDiffusion model.

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
unit	str | sc.Unit	Unit of the diffusion model. Must be convertible to meV.	'meV'
name	str	Name of the diffusion model.	'JumpTranslationalDiffusion'
display_name	str | None	Display name of the diffusion model.	'JumpTranslationalDiffusion'
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.

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

def __init__(
    self,
    scale: Numeric = 1.0,
    diffusion_coefficient: Numeric = 1.0,
    relaxation_time: Numeric = 1.0,
    unit: str | sc.Unit = 'meV',
    name: str = 'JumpTranslationalDiffusion',
    display_name: str | None = 'JumpTranslationalDiffusion',
    unique_name: str | None = None,
) -> None:
    """
    Initialize a new JumpTranslationalDiffusion model.

    Parameters
    ----------
    scale : Numeric, default=1.0
        Scale factor for the diffusion model. Must be a non-negative number.
    diffusion_coefficient : Numeric, default=1.0
        Diffusion coefficient D in m^2/s.
    relaxation_time : Numeric, default=1.0
        Relaxation time t in ps.
    unit : str | sc.Unit, default='meV'
        Unit of the diffusion model. Must be convertible to meV.
    name : str, default='JumpTranslationalDiffusion'
        Name of the diffusion model.
    display_name : str | None, default='JumpTranslationalDiffusion'
        Display name of the diffusion model.
    unique_name : str | None, default=None
        Unique name of the diffusion model. If None, a unique name will be generated. By
        default, None.

    Raises
    ------
    TypeError
        If scale, diffusion_coefficient, or relaxation_time  are not numbers.
    """
    super().__init__(
        name=name,
        display_name=display_name,
        unique_name=unique_name,
        unit=unit,
        scale=scale,
    )

    if not isinstance(diffusion_coefficient, Numeric):
        raise TypeError('diffusion_coefficient must be a number.')

    if not isinstance(relaxation_time, Numeric):
        raise TypeError('relaxation_time must be a number.')

    diffusion_coefficient = Parameter(
        name='diffusion_coefficient',
        value=float(diffusion_coefficient),
        fixed=False,
        unit='m**2/s',
    )

    relaxation_time = Parameter(
        name='relaxation_time',
        value=float(relaxation_time),
        fixed=False,
        unit='ps',
    )

    self._hbar = hbar
    self._angstrom = angstrom
    self._diffusion_coefficient = diffusion_coefficient
    self._relaxation_time = relaxation_time

calculate_width(Q)

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	Scattering vector in 1/angstrom. Can be a single value or an array of values.	required

Returns:

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

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

def calculate_width(self, Q: Q_type) -> np.ndarray:
    r"""
    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
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom. Can be a single value or an array of values.

    Returns
    -------
    np.ndarray
        HWHM values in the unit of the model (e.g., meV).
    """

    Q = _validate_and_convert_Q(Q)

    unit_conversion_factor_numerator = (
        self._hbar * self.diffusion_coefficient / (self._angstrom**2)
    )
    unit_conversion_factor_numerator.convert_unit(self.unit)

    numerator = unit_conversion_factor_numerator.value * Q**2

    unit_conversion_factor_denominator = (
        self.diffusion_coefficient / self._angstrom**2 * self.relaxation_time
    )
    unit_conversion_factor_denominator.convert_unit('dimensionless')

    denominator = 1 + unit_conversion_factor_denominator.value * Q**2

    return numerator / denominator

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).

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

def calculate_EISF(self, Q: Q_type) -> np.ndarray:
    """
    Calculate the Elastic Incoherent Structure Factor (EISF).

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom. Can be a single value or an array of values.

    Returns
    -------
    np.ndarray
        EISF values (dimensionless).
    """
    Q = _validate_and_convert_Q(Q)
    return np.zeros_like(Q)

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).

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

def calculate_QISF(self, Q: Q_type) -> np.ndarray:
    """
    Calculate the Quasi-Elastic Incoherent Structure Factor (QISF).

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom. Can be a single value or an array of values.

    Returns
    -------
    np.ndarray
        QISF values (dimensionless).
    """
    Q = _validate_and_convert_Q(Q)
    return np.ones_like(Q)

create_component_collections(Q, component_name='Jump translational diffusion', component_display_name='Jump translational diffusion')

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

Parameters:

Name	Type	Description	Default
Q	Q_type	Scattering vector in 1/angstrom. Can be a single value or an array of values.	required
component_name	str	Name of the Jump Diffusion Lorentzian component.	'Jump translational diffusion'
component_display_name	str	Name of the Jump Diffusion Lorentzian component.	'Jump translational diffusion'

Raises:

Type	Description
TypeError	If component_display_name is not a string. If component_name is not a string.

Returns:

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

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

def create_component_collections(
    self,
    Q: Q_type,
    component_name: str = 'Jump translational diffusion',
    component_display_name: str = 'Jump translational diffusion',
) -> list[ComponentCollection]:
    """
    Create ComponentCollection components for the diffusion model at given Q values.

    Parameters
    ----------
    Q : Q_type
        Scattering vector in 1/angstrom. Can be a single value or an array of values.
    component_name : str, default='Jump translational diffusion'
        Name of the Jump Diffusion Lorentzian component.
    component_display_name : str, default='Jump translational diffusion'
        Name of the Jump Diffusion Lorentzian component.

    Raises
    ------
    TypeError
        If component_display_name is not a string. If component_name is not a string.

    Returns
    -------
    list[ComponentCollection]
        List of ComponentCollections with Jump Diffusion Lorentzian components.
    """
    Q = _validate_and_convert_Q(Q)

    if not isinstance(component_display_name, str):
        raise TypeError('component_display_name must be a string.')

    if not isinstance(component_name, str):
        raise TypeError('component_name must be a string.')

    component_collection_list = [None] * len(Q)
    # In more complex models, this is used to scale the area of the
    # Lorentzians and the delta function.
    QISF = self.calculate_QISF(Q)

    # Create a Lorentzian component for each Q-value, with width
    # D*Q^2 and area equal to scale. No delta function, as the EISF
    # is 0.
    for i, Q_value in enumerate(Q):
        component_collection_list[i] = ComponentCollection(
            name=f'{self.name}_Q{Q_value:.2f}',
            display_name=f'{self.display_name}_Q{Q_value:.2f}',
            unit=self.unit,
        )

        lorentzian_component = Lorentzian(
            name=component_name,
            display_name=component_display_name,
            unit=self.unit,
        )

        # Make the width dependent on Q
        dependency_expression = self._write_width_dependency_expression(Q[i])
        dependency_map = self._write_width_dependency_map_expression()

        lorentzian_component.width.make_dependent_on(
            dependency_expression=dependency_expression,
            dependency_map=dependency_map,
            desired_unit=self.unit,
        )

        # Make the area dependent on Q
        area_dependency_map = self._write_area_dependency_map_expression()
        lorentzian_component.area.make_dependent_on(
            dependency_expression=self._write_area_dependency_expression(QISF[i]),
            dependency_map=area_dependency_map,
        )

        component_collection_list[i].append_component(lorentzian_component)

    return component_collection_list

__repr__()

String representation of the JumpTranslationalDiffusion model.

Returns:

Type	Description
str	String representation of the JumpTranslationalDiffusion model.

Source code in src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py

def __repr__(self) -> str:
    """
    String representation of the JumpTranslationalDiffusion model.

    Returns
    -------
    str
        String representation of the JumpTranslationalDiffusion model.
    """
    return (
        f'JumpTranslationalDiffusion(name={self.name}, display_name={self.display_name},\n '
        f'    diffusion_coefficient={self._diffusion_coefficient}, \n'
        f'    scale={self._scale})'
    )

instrument_model

InstrumentModel

Bases: NewBase

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.

Source code in src/easydynamics/sample_model/instrument_model.py

class InstrumentModel(NewBase):
    """
    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.
    """

    def __init__(
        self,
        display_name: str = 'MyInstrumentModel',
        unique_name: str | None = None,
        Q: Q_type | None = None,
        resolution_model: ResolutionModel | None = None,
        background_model: BackgroundModel | None = None,
        energy_offset: Numeric | None = None,
        unit: str | sc.Unit = 'meV',
    ) -> None:
        """
        Initialize an InstrumentModel.

        Parameters
        ----------
        display_name : str, default='MyInstrumentModel'
            The display name of the InstrumentModel.
        unique_name : str | None, default=None
            The unique name of the InstrumentModel.
        Q : Q_type | None, default=None
            The Q values where the instrument is modelled.
        resolution_model : ResolutionModel | None, default=None
            The resolution model of the instrument. If None, an empty resolution model is created
            and no resolution convolution is carried out.
        background_model : BackgroundModel | None, default=None
            The background model of the instrument. If None, an empty background model is created,
            and the background evaluates to 0.
        energy_offset : Numeric | None, default=None
            Template energy offset of the instrument. Will be copied to each Q value. If None, the
            energy offset will be 0.
        unit : str | sc.Unit, default='meV'
            The unit of the energy axis.

        Raises
        ------
        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.
        """
        super().__init__(
            display_name=display_name,
            unique_name=unique_name,
        )

        self._unit = _validate_unit(unit)

        if resolution_model is None:
            self._resolution_model = ResolutionModel()
        else:
            if not isinstance(resolution_model, ResolutionModel):
                raise TypeError(
                    f'resolution_model must be a ResolutionModel or None, '
                    f'got {type(resolution_model).__name__}'
                )
            self._resolution_model = resolution_model

        if background_model is None:
            self._background_model = BackgroundModel()
        else:
            if not isinstance(background_model, BackgroundModel):
                raise TypeError(
                    f'background_model must be a BackgroundModel or None, '
                    f'got {type(background_model).__name__}'
                )
            self._background_model = background_model

        if energy_offset is None:
            energy_offset = 0.0

        if not isinstance(energy_offset, Numeric):
            raise TypeError('energy_offset must be a number or None')

        self._energy_offset = Parameter(
            name='energy_offset',
            value=float(energy_offset),
            unit=self.unit,
            fixed=False,
        )
        self._Q = _validate_and_convert_Q(Q)
        self._on_Q_change()

    # -------------------------------------------------------------
    # Properties
    # -------------------------------------------------------------

    @property
    def resolution_model(self) -> ResolutionModel:
        """
        Get the resolution model of the instrument.

        Returns
        -------
        ResolutionModel
            The resolution model of the instrument.
        """
        return self._resolution_model

    @resolution_model.setter
    def resolution_model(self, value: ResolutionModel) -> None:
        """
        Set the resolution model of the instrument.

        Parameters
        ----------
        value : ResolutionModel
            The new resolution model of the instrument.

        Raises
        ------
        TypeError
            If value is not a ResolutionModel.
        """
        if not isinstance(value, ResolutionModel):
            raise TypeError(
                f'resolution_model must be a ResolutionModel, got {type(value).__name__}'
            )
        self._resolution_model = value
        self._on_resolution_model_change()

    @property
    def background_model(self) -> BackgroundModel:
        """
        Get the background model of the instrument.

        Returns
        -------
        BackgroundModel
            The background model of the instrument.
        """

        return self._background_model

    @background_model.setter
    def background_model(self, value: BackgroundModel) -> None:
        """
        Set the background model of the instrument.

        Parameters
        ----------
        value : BackgroundModel
            The new background model of the instrument.

        Raises
        ------
        TypeError
            If value is not a BackgroundModel.
        """

        if not isinstance(value, BackgroundModel):
            raise TypeError(
                f'background_model must be a BackgroundModel, got {type(value).__name__}'
            )
        self._background_model = value
        self._on_background_model_change()

    @property
    def Q(self) -> np.ndarray | None:
        """
        Get the Q values of the InstrumentModel.

        Returns
        -------
        np.ndarray | None
            The Q values of the InstrumentModel, or None if not set.
        """
        return self._Q

    @Q.setter
    def Q(self, value: Q_type | None) -> None:
        """
        Set the Q values of the InstrumentModel.

        If Q is already set, it raises an error if the new Q values are not similar to the old ones
        to prevent accidental changes to the background and resolution models. To change Q values,
        first run clear_Q().

        Parameters
        ----------
        value : Q_type | None
            The new Q values to set. If None, Q values are not changed.

        Raises
        ------
        ValueError
            If the new Q values are not similar to the old ones when Q is not None.
        """
        if value is None:
            return
        old_Q = self._Q
        new_Q = _validate_and_convert_Q(value)

        if old_Q is None:
            self._Q = new_Q
            self._on_Q_change()
            return

        if len(old_Q) != len(new_Q) or not np.allclose(old_Q, new_Q):
            raise ValueError(
                'New Q values are not similar to the old ones. '
                'To change Q values, first run clear_Q().'
            )

    @property
    def unit(self) -> str | sc.Unit:
        """
        Get the unit of the InstrumentModel.

        Returns
        -------
        str | sc.Unit
            The unit of the InstrumentModel.
        """
        return self._unit

    @unit.setter
    def unit(self, _unit_str: str) -> None:
        """
        Set the unit of the InstrumentModel.

        The unit is read-only and cannot be set directly. Use convert_unit to change the unit
        between allowed types or create a new InstrumentModel with the desired unit.

        Parameters
        ----------
        _unit_str : str
            The new unit for the InstrumentModel (ignored).

        Raises
        ------
        AttributeError
            Always, as the unit is read-only.
        """
        raise AttributeError(
            f'Unit is read-only. Use convert_unit to change the unit between allowed types '
            f'or create a new {self.__class__.__name__} with the desired unit.'
        )

    @property
    def energy_offset(self) -> Parameter:
        """
        Get the energy offset template parameter of the instrument model.

        Returns
        -------
        Parameter
            The energy offset template parameter of the instrument model.
        """
        return self._energy_offset

    @energy_offset.setter
    def energy_offset(self, value: Numeric) -> None:
        """
        Set the offset parameter of the instrument model.

        Parameters
        ----------
        value : Numeric
            The new value for the energy offset parameter. Will be copied to all Q values.

        Raises
        ------
        TypeError
            If value is not a number.
        """
        if not isinstance(value, Numeric):
            raise TypeError(f'energy_offset must be a number, got {type(value).__name__}')
        self._energy_offset.value = value

        self._on_energy_offset_change()

    # --------------------------------------------------------------
    # Other methods
    # --------------------------------------------------------------

    def clear_Q(self, confirm: bool = False) -> None:
        """
        Clear the Q values of the InstrumentModel and any associated ResolutionModel and
        BackgroundModel, removing all component collections and their associated Parameters.

        Parameters
        ----------
        confirm : bool, default=False
            Confirmation to clear Q values.

        Raises
        ------
        ValueError
            If confirm is not True.
        """
        if not confirm:
            raise ValueError(
                'Clearing Q values requires confirmation. Set confirm=True to proceed.'
            )
        self._Q = None
        self.background_model.clear_Q(confirm=True)
        self.resolution_model.clear_Q(confirm=True)
        self._on_Q_change()

    def convert_unit(self, unit_str: str | sc.Unit) -> None:
        """
        Convert the unit of the InstrumentModel.

        Parameters
        ----------
        unit_str : str | sc.Unit
            The unit to convert to.

        Raises
        ------
        ValueError
            If unit_str is not a valid unit string or scipp Unit.
        """
        unit = _validate_unit(unit_str)
        if unit is None:
            raise ValueError('unit_str must be a valid unit string or scipp Unit')

        self._background_model.convert_unit(unit)
        self._resolution_model.convert_unit(unit)
        self._energy_offset.convert_unit(unit)
        for offset in self._energy_offsets:
            offset.convert_unit(unit)

        self._unit = unit

    def get_all_variables(self, Q_index: int | None = None) -> list[Parameter]:
        """
        Get all variables in the InstrumentModel.

        Parameters
        ----------
        Q_index : int | None, default=None
            The index of the Q value to get variables for. If None, get variables for all Q values.


        Raises
        ------
        TypeError
            If Q_index is not an int or None.
        IndexError
            If Q_index is out of bounds for the Q values in the InstrumentModel.

        Returns
        -------
        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.
        """
        if self._Q is None:
            return []

        if Q_index is None:
            variables = [self._energy_offsets[i] for i in range(len(self._Q))]
        else:
            if not isinstance(Q_index, int):
                raise TypeError(f'Q_index must be an int or None, got {type(Q_index).__name__}')
            if Q_index < 0 or Q_index >= len(self._Q):
                raise IndexError(
                    f'Q_index {Q_index} is out of bounds for Q of length {len(self._Q)}'
                )
            variables = [self._energy_offsets[Q_index]]

        variables.extend(self._background_model.get_all_variables(Q_index=Q_index))
        variables.extend(self._resolution_model.get_all_variables(Q_index=Q_index))

        return variables

    def fix_resolution_parameters(self) -> None:
        """Fix all parameters in the resolution model."""
        self.resolution_model.fix_all_parameters()

    def free_resolution_parameters(self) -> None:
        """Free all parameters in the resolution model."""
        self.resolution_model.free_all_parameters()

    def normalize_resolution(self) -> None:
        """Normalize the resolution model to have area 1."""
        self.resolution_model.normalize_area()

    def get_energy_offset(
        self,
        Q_index: int | None = None,
    ) -> Parameter | list[Parameter]:
        """
        Get the energy offset Parameter at a specific Q index.

        Parameters
        ----------
        Q_index : int | None, default=None
            The index of the Q value to get the energy offset for. If None, get the energy offset
            for all Q values.

        Raises
        ------
        ValueError
            If no Q values are set in the InstrumentModel.
        IndexError
            If Q_index is out of bounds.
        TypeError
            If Q_index is not an int or None.

        Returns
        -------
        Parameter | list[Parameter]
            The energy offset Parameter at the specified Q index, or a list of Parameters if
            Q_index is None.
        """
        if self._Q is None:
            raise ValueError('No Q values are set in the InstrumentModel.')

        if Q_index is None:
            return self._energy_offsets

        if not isinstance(Q_index, int):
            raise TypeError(f'Q_index must be an int or None, got {type(Q_index).__name__}')

        if Q_index < 0 or Q_index >= len(self._Q):
            raise IndexError(f'Q_index {Q_index} is out of bounds for Q of length {len(self._Q)}')

        return self._energy_offsets[Q_index]

    def fix_energy_offset(self, Q_index: int | None = None) -> 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
        ----------
        Q_index : int | None, default=None
            The index of the Q value to fix the energy offset for. If None, fix energy offsets for
            all Q values.
        """
        self._fix_or_free_energy_offset(Q_index, fixed=True)

    def free_energy_offset(self, Q_index: int | None = None) -> 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
        ----------
        Q_index : int | None, default=None
            The index of the Q value to free the energy offset for. If None, free energy offsets
            for all Q values.
        """
        self._fix_or_free_energy_offset(Q_index, fixed=False)

    # --------------------------------------------------------------
    # Private methods
    # --------------------------------------------------------------
    def _fix_or_free_energy_offset(self, Q_index: int | None = None, fixed: bool = True) -> None:
        """
        Fix or free energy offset parameters.

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

        Parameters
        ----------
        Q_index : int | None, default=None
            The index of the Q value to fix or free the energy offset for. If None, fix or free
            energy offsets for all Q values.
        fixed : bool, default=True
            Whether to fix (True) or free (False) the energy offset.

        Raises
        ------
        TypeError
            If Q_index is not an int or None.
        IndexError
            If Q_index is out of bounds for the Q values in the InstrumentModel.
        """

        if Q_index is None:
            for offset in self._energy_offsets:
                offset.fixed = fixed
        else:
            if not isinstance(Q_index, int):
                raise TypeError(f'Q_index must be an int or None, got {type(Q_index).__name__}')

            if Q_index < 0 or Q_index >= len(self._Q):
                raise IndexError(
                    f'Q_index {Q_index} is out of bounds for Q of length {len(self._Q)}'
                )
            self._energy_offsets[Q_index].fixed = fixed

    def _generate_energy_offsets(self) -> None:
        """Generate energy offset Parameters for each Q value."""
        if self._Q is None:
            self._energy_offsets = []
            return

        self._energy_offsets = [copy(self._energy_offset) for _ in self._Q]

    def _on_Q_change(self) -> None:
        """Handle changes to the Q values."""
        self._generate_energy_offsets()
        self.resolution_model.Q = self.Q
        self.background_model.Q = self.Q

    def _on_energy_offset_change(self) -> None:
        """Handle changes to the energy offset."""
        for offset in self._energy_offsets:
            offset.value = self._energy_offset.value

    def _on_resolution_model_change(self) -> None:
        """Handle changes to the resolution model."""
        self.resolution_model.Q = self.Q

    def _on_background_model_change(self) -> None:
        """Handle changes to the background model."""
        self.background_model.Q = self.Q

    # -------------------------------------------------------------
    # Dunder methods
    # -------------------------------------------------------------

    def __repr__(self) -> str:
        """
        Return a string representation of the InstrumentModel.

        Returns
        -------
        str
            A string representation of the InstrumentModel.
        """

        return (
            f'{self.__class__.__name__}('
            f'unique_name={self.unique_name!r}, '
            f'unit={self.unit}, '
            f'Q_len={None if self._Q is None else len(self._Q)}, '
            f'resolution_model={self._resolution_model!r}, '
            f'background_model={self._background_model!r}'
            f')'
        )

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
np.ndarray | None	The Q values of the InstrumentModel, or None if not set.

unit property writable

Get the unit of the InstrumentModel.

Returns:

Type	Description
str | sc.Unit	The unit of the InstrumentModel.

energy_offset property writable

Get the energy offset template parameter of the instrument model.

Returns:

Type	Description
Parameter	The energy offset template parameter of the instrument model.

__init__(display_name='MyInstrumentModel', unique_name=None, Q=None, resolution_model=None, background_model=None, energy_offset=None, unit='meV')

Initialize an InstrumentModel.

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 | None	The resolution model of the instrument. 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
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.

Source code in src/easydynamics/sample_model/instrument_model.py

def __init__(
    self,
    display_name: str = 'MyInstrumentModel',
    unique_name: str | None = None,
    Q: Q_type | None = None,
    resolution_model: ResolutionModel | None = None,
    background_model: BackgroundModel | None = None,
    energy_offset: Numeric | None = None,
    unit: str | sc.Unit = 'meV',
) -> None:
    """
    Initialize an InstrumentModel.

    Parameters
    ----------
    display_name : str, default='MyInstrumentModel'
        The display name of the InstrumentModel.
    unique_name : str | None, default=None
        The unique name of the InstrumentModel.
    Q : Q_type | None, default=None
        The Q values where the instrument is modelled.
    resolution_model : ResolutionModel | None, default=None
        The resolution model of the instrument. If None, an empty resolution model is created
        and no resolution convolution is carried out.
    background_model : BackgroundModel | None, default=None
        The background model of the instrument. If None, an empty background model is created,
        and the background evaluates to 0.
    energy_offset : Numeric | None, default=None
        Template energy offset of the instrument. Will be copied to each Q value. If None, the
        energy offset will be 0.
    unit : str | sc.Unit, default='meV'
        The unit of the energy axis.

    Raises
    ------
    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.
    """
    super().__init__(
        display_name=display_name,
        unique_name=unique_name,
    )

    self._unit = _validate_unit(unit)

    if resolution_model is None:
        self._resolution_model = ResolutionModel()
    else:
        if not isinstance(resolution_model, ResolutionModel):
            raise TypeError(
                f'resolution_model must be a ResolutionModel or None, '
                f'got {type(resolution_model).__name__}'
            )
        self._resolution_model = resolution_model

    if background_model is None:
        self._background_model = BackgroundModel()
    else:
        if not isinstance(background_model, BackgroundModel):
            raise TypeError(
                f'background_model must be a BackgroundModel or None, '
                f'got {type(background_model).__name__}'
            )
        self._background_model = background_model

    if energy_offset is None:
        energy_offset = 0.0

    if not isinstance(energy_offset, Numeric):
        raise TypeError('energy_offset must be a number or None')

    self._energy_offset = Parameter(
        name='energy_offset',
        value=float(energy_offset),
        unit=self.unit,
        fixed=False,
    )
    self._Q = _validate_and_convert_Q(Q)
    self._on_Q_change()

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.

Source code in src/easydynamics/sample_model/instrument_model.py

def clear_Q(self, confirm: bool = False) -> None:
    """
    Clear the Q values of the InstrumentModel and any associated ResolutionModel and
    BackgroundModel, removing all component collections and their associated Parameters.

    Parameters
    ----------
    confirm : bool, default=False
        Confirmation to clear Q values.

    Raises
    ------
    ValueError
        If confirm is not True.
    """
    if not confirm:
        raise ValueError(
            'Clearing Q values requires confirmation. Set confirm=True to proceed.'
        )
    self._Q = None
    self.background_model.clear_Q(confirm=True)
    self.resolution_model.clear_Q(confirm=True)
    self._on_Q_change()

convert_unit(unit_str)

Convert the unit of the InstrumentModel.

Parameters:

Name	Type	Description	Default
unit_str	str | sc.Unit	The unit to convert to.	required

Raises:

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

Source code in src/easydynamics/sample_model/instrument_model.py

def convert_unit(self, unit_str: str | sc.Unit) -> None:
    """
    Convert the unit of the InstrumentModel.

    Parameters
    ----------
    unit_str : str | sc.Unit
        The unit to convert to.

    Raises
    ------
    ValueError
        If unit_str is not a valid unit string or scipp Unit.
    """
    unit = _validate_unit(unit_str)
    if unit is None:
        raise ValueError('unit_str must be a valid unit string or scipp Unit')

    self._background_model.convert_unit(unit)
    self._resolution_model.convert_unit(unit)
    self._energy_offset.convert_unit(unit)
    for offset in self._energy_offsets:
        offset.convert_unit(unit)

    self._unit = 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

Raises:

Type	Description
TypeError	If Q_index is not an int or None.
IndexError	If Q_index is out of bounds for the Q values in the InstrumentModel.

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.

Source code in src/easydynamics/sample_model/instrument_model.py

def get_all_variables(self, Q_index: int | None = None) -> list[Parameter]:
    """
    Get all variables in the InstrumentModel.

    Parameters
    ----------
    Q_index : int | None, default=None
        The index of the Q value to get variables for. If None, get variables for all Q values.


    Raises
    ------
    TypeError
        If Q_index is not an int or None.
    IndexError
        If Q_index is out of bounds for the Q values in the InstrumentModel.

    Returns
    -------
    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.
    """
    if self._Q is None:
        return []

    if Q_index is None:
        variables = [self._energy_offsets[i] for i in range(len(self._Q))]
    else:
        if not isinstance(Q_index, int):
            raise TypeError(f'Q_index must be an int or None, got {type(Q_index).__name__}')
        if Q_index < 0 or Q_index >= len(self._Q):
            raise IndexError(
                f'Q_index {Q_index} is out of bounds for Q of length {len(self._Q)}'
            )
        variables = [self._energy_offsets[Q_index]]

    variables.extend(self._background_model.get_all_variables(Q_index=Q_index))
    variables.extend(self._resolution_model.get_all_variables(Q_index=Q_index))

    return variables

fix_resolution_parameters()

Fix all parameters in the resolution model.

Source code in src/easydynamics/sample_model/instrument_model.py

def fix_resolution_parameters(self) -> None:
    """Fix all parameters in the resolution model."""
    self.resolution_model.fix_all_parameters()

free_resolution_parameters()

Free all parameters in the resolution model.

Source code in src/easydynamics/sample_model/instrument_model.py

def free_resolution_parameters(self) -> None:
    """Free all parameters in the resolution model."""
    self.resolution_model.free_all_parameters()

normalize_resolution()

Normalize the resolution model to have area 1.

Source code in src/easydynamics/sample_model/instrument_model.py

def normalize_resolution(self) -> None:
    """Normalize the resolution model to have area 1."""
    self.resolution_model.normalize_area()

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.
IndexError	If Q_index is out of bounds.
TypeError	If Q_index is not an int or None.

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.

Source code in src/easydynamics/sample_model/instrument_model.py

def get_energy_offset(
    self,
    Q_index: int | None = None,
) -> Parameter | list[Parameter]:
    """
    Get the energy offset Parameter at a specific Q index.

    Parameters
    ----------
    Q_index : int | None, default=None
        The index of the Q value to get the energy offset for. If None, get the energy offset
        for all Q values.

    Raises
    ------
    ValueError
        If no Q values are set in the InstrumentModel.
    IndexError
        If Q_index is out of bounds.
    TypeError
        If Q_index is not an int or None.

    Returns
    -------
    Parameter | list[Parameter]
        The energy offset Parameter at the specified Q index, or a list of Parameters if
        Q_index is None.
    """
    if self._Q is None:
        raise ValueError('No Q values are set in the InstrumentModel.')

    if Q_index is None:
        return self._energy_offsets

    if not isinstance(Q_index, int):
        raise TypeError(f'Q_index must be an int or None, got {type(Q_index).__name__}')

    if Q_index < 0 or Q_index >= len(self._Q):
        raise IndexError(f'Q_index {Q_index} is out of bounds for Q of length {len(self._Q)}')

    return self._energy_offsets[Q_index]

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

Source code in src/easydynamics/sample_model/instrument_model.py

def fix_energy_offset(self, Q_index: int | None = None) -> 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
    ----------
    Q_index : int | None, default=None
        The index of the Q value to fix the energy offset for. If None, fix energy offsets for
        all Q values.
    """
    self._fix_or_free_energy_offset(Q_index, fixed=True)

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

Source code in src/easydynamics/sample_model/instrument_model.py

def free_energy_offset(self, Q_index: int | None = None) -> 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
    ----------
    Q_index : int | None, default=None
        The index of the Q value to free the energy offset for. If None, free energy offsets
        for all Q values.
    """
    self._fix_or_free_energy_offset(Q_index, fixed=False)

__repr__()

Return a string representation of the InstrumentModel.

Returns:

Type	Description
str	A string representation of the InstrumentModel.

Source code in src/easydynamics/sample_model/instrument_model.py

def __repr__(self) -> str:
    """
    Return a string representation of the InstrumentModel.

    Returns
    -------
    str
        A string representation of the InstrumentModel.
    """

    return (
        f'{self.__class__.__name__}('
        f'unique_name={self.unique_name!r}, '
        f'unit={self.unit}, '
        f'Q_len={None if self._Q is None else len(self._Q)}, '
        f'resolution_model={self._resolution_model!r}, '
        f'background_model={self._background_model!r}'
        f')'
    )

model_base

ModelBase

Bases: EasyDynamicsModelBase

Base class for Sample Models.

Contains common functionality for models with components and Q dependence.

Source code in src/easydynamics/sample_model/model_base.py

class ModelBase(EasyDynamicsModelBase):
    """
    Base class for Sample Models.

    Contains common functionality for models with components and Q dependence.
    """

    def __init__(
        self,
        display_name: str = 'MyModelBase',
        unique_name: str | None = None,
        unit: str | sc.Unit | None = 'meV',
        components: ModelComponent | ComponentCollection | None = None,
        Q: Q_type | None = None,
    ) -> None:
        """
        Initialize the ModelBase.

        Parameters
        ----------
        display_name : str, default='MyModelBase'
            Display name of the model.
        unique_name : str | None, default=None
            Unique name of the model. If None, a unique name will be generated.
        unit : str | sc.Unit | None, default='meV'
            Unit of the model.
        components : ModelComponent | ComponentCollection | None, default=None
            Template components of the model. If None, no components are added. These components
            are copied into ComponentCollections for each Q value.
        Q : Q_type | None, default=None
            Q values for the model. If None, Q is not set.

        Raises
        ------
        TypeError
            If components is not a ModelComponent or ComponentCollection.
        """
        super().__init__(
            unit=unit,
            display_name=display_name,
            unique_name=unique_name,
        )
        self._Q = _validate_and_convert_Q(Q)

        if components is not None and not isinstance(
            components, (ModelComponent, ComponentCollection)
        ):
            raise TypeError(
                f'Components must be a ModelComponent, a ComponentCollection or None, '
                f'got {type(components).__name__}'
            )

        self._components = ComponentCollection()
        if isinstance(components, (ModelComponent, ComponentCollection)):
            self.append_component(components)

        self._generate_component_collections()

    def evaluate(
        self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray
    ) -> list[np.ndarray]:
        """
        Evaluate the sample model at all Q for the given x values.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            Energy axis values to evaluate the model at. If a scipp Variable or DataArray is
            provided, the unit of the model will be converted to match the unit of x for
            evaluation, and the result will be returned in the same unit as x.

        Raises
        ------
        ValueError
            If there are no components in the model to evaluate.

        Returns
        -------
        list[np.ndarray]
            A list of numpy arrays containing the evaluated model values for each Q. The length of
            the list will match the number of Q values in the model.
        """

        if not self._component_collections:
            raise ValueError(
                'No components in the model to evaluate. '
                'Run generate_component_collections() first'
            )
        return [collection.evaluate(x) for collection in self._component_collections]

    # ------------------------------------------------------------------
    # Component management
    # ------------------------------------------------------------------
    def append_component(self, component: ModelComponent | ComponentCollection) -> None:
        """
        Append a ModelComponent or ComponentCollection to the SampleModel.

        Parameters
        ----------
        component : ModelComponent | ComponentCollection
            The ModelComponent or ComponentCollection to append.
        """
        self._components.append_component(component)
        self._on_components_change()

    def remove_component(self, name: str) -> None:
        """
        Remove a ModelComponent from the SampleModel by its name.

        Parameters
        ----------
        name : str
            The name of the ModelComponent to remove.
        """
        self._components.pop(name)
        self._on_components_change()

    def clear_components(self) -> None:
        """Clear all ModelComponents from the SampleModel."""
        self._components.clear()
        self._on_components_change()

    # ------------------------------------------------------------------
    # Properties
    # ------------------------------------------------------------------

    @property
    def unit(self) -> str | sc.Unit | None:
        """
        Get the unit of the SampleModel.

        Returns
        -------
        str | sc.Unit | None
            The unit of the SampleModel.
        """

        return self._unit

    @unit.setter
    def unit(self, _unit_str: str) -> None:
        """
        Unit is read-only and cannot be set directly.

        Parameters
        ----------
        _unit_str : str
            The new unit to set (ignored).

        Raises
        ------
        AttributeError
            Always raised to indicate that the unit is read-only.
        """
        raise AttributeError(
            f'Unit is read-only. Use convert_unit to change the unit between allowed types '
            f'or create a new {self.__class__.__name__} with the desired unit.'
        )

    @property
    def components(self) -> list[ModelComponent]:
        """
        Get the components of the SampleModel.

        Returns
        -------
        list[ModelComponent]
            The components of the SampleModel.
        """
        return self._components

    @components.setter
    def components(self, value: ModelComponent | ComponentCollection | None) -> None:
        """
        Set the components of the SampleModel.

        Parameters
        ----------
        value : ModelComponent | ComponentCollection | None
            The new components to set. If None, all components will be cleared.

        Raises
        ------
        TypeError
            If value is not a ModelComponent, ComponentCollection, or None.
        """
        if not isinstance(value, (ModelComponent, ComponentCollection, type(None))):
            raise TypeError('Components must be a ModelComponent or a ComponentCollection')

        self.clear_components()
        if value is not None:
            self.append_component(value)

    @property
    def Q(self) -> np.ndarray | None:
        """
        Get the Q values of the SampleModel.

        Returns
        -------
        np.ndarray | None
            The Q values of the SampleModel, or None if not set.
        """
        return self._Q

    @Q.setter
    def Q(self, value: Q_type | None) -> None:
        """
        Set the Q values of the SampleModel.

        If Q is already set, it throws an error if the new Q values are not similar to the old
        ones. To change Q values, first run clear_Q().

        Parameters
        ----------
        value : Q_type | None
            The new Q values to set. If None, Q values are not changed.

        Raises
        ------
        ValueError
            If the new Q values are not similar to the old ones when Q is already set.
        """
        if value is None:
            return
        old_Q = self._Q
        new_Q = _validate_and_convert_Q(value)

        if old_Q is None:
            self._Q = new_Q
            self._on_Q_change()
            return

        if len(old_Q) != len(new_Q) or not np.allclose(old_Q, new_Q):
            raise ValueError(
                'New Q values are not similar to the old ones. '
                'To change Q values, first run clear_Q().'
            )

    def clear_Q(self, confirm: bool = False) -> None:
        """
        Clear the Q values of the SampleModel, removing all component collections and their
        associated Parameters.

        Parameters
        ----------
        confirm : bool, default=False
            Confirmation to clear Q values.

        Raises
        ------
        ValueError
            If confirm is not True.
        """
        if not confirm:
            raise ValueError(
                'Clearing Q values requires confirmation. Set confirm=True to proceed.'
            )
        self._Q = None
        self._on_Q_change()

    # ------------------------------------------------------------------
    # Other methods
    # ------------------------------------------------------------------

    def convert_unit(self, unit: str | sc.Unit) -> None:
        """
        Convert the unit of the ComponentCollection and all its components.

        Parameters
        ----------
        unit : str | sc.Unit
            The new unit to convert to.

        Raises
        ------
        TypeError
            If the provided unit is not a string or sc.Unit.
        Exception
            If the provided unit is not compatible with the current unit.
        """

        old_unit = self._unit

        if not isinstance(unit, (str, sc.Unit)):
            raise TypeError(f'Unit must be a string or sc.Unit, got {type(unit).__name__}')
        try:
            for component in self.components:
                component.convert_unit(unit)
            self._unit = unit
        except Exception as e:
            # Attempt to rollback on failure
            try:
                for component in self.components:
                    component.convert_unit(old_unit)
            except Exception:  # noqa: S110
                pass  # Best effort rollback
            raise e
        self._on_components_change()

    def fix_all_parameters(self) -> None:
        """Fix all Parameters in all ComponentCollections."""
        for par in self.get_all_variables():
            par.fixed = True

    def free_all_parameters(self) -> None:
        """Free all Parameters in all ComponentCollections."""
        for par in self.get_all_variables():
            par.fixed = False

    def get_all_variables(self, Q_index: int | None = None) -> list[Parameter]:
        """
        Get all Parameters and Descriptors from all ComponentCollections in the ModelBase.
        Parameters Ignores the Parameters and Descriptors in self._components as these are just
        templates.

        Parameters
        ----------
        Q_index : int | None, default=None
            If None, get variables for all ComponentCollections. If int, get variables for the
            ComponentCollection at this index.

        Raises
        ------
        TypeError
            If Q_index is not an int or None.
        IndexError
            If Q_index is out of bounds for the number of ComponentCollections.

        Returns
        -------
        list[Parameter]
            A list of all Parameters and Descriptors from the ComponentCollections in the
            ModelBase.
        """

        if Q_index is None:
            all_vars = [
                var
                for collection in self._component_collections
                for var in collection.get_all_variables()
            ]
        else:
            if not isinstance(Q_index, int):
                raise TypeError(f'Q_index must be an int or None, got {type(Q_index).__name__}')
            if Q_index < 0 or Q_index >= len(self._component_collections):
                raise IndexError(
                    f'Q_index {Q_index} is out of bounds for component collections '
                    f'of length {len(self._component_collections)}'
                )
            all_vars = self._component_collections[Q_index].get_all_variables()
        return all_vars

    def get_component_collection(self, Q_index: int) -> ComponentCollection:
        """
        Get the ComponentCollection at the given Q index.

        Parameters
        ----------
        Q_index : int
            The index of the desired ComponentCollection.

        Raises
        ------
        TypeError
            If Q_index is not an int.
        IndexError
            If Q_index is out of bounds for the number of ComponentCollections.

        Returns
        -------
        ComponentCollection
            The ComponentCollection at the.
        """
        if not isinstance(Q_index, int):
            raise TypeError(f'Q_index must be an int, got {type(Q_index).__name__}')
        if Q_index < 0 or Q_index >= len(self._component_collections):
            raise IndexError(
                f'Q_index {Q_index} is out of bounds for component collections '
                f'of length {len(self._component_collections)}'
            )
        return self._component_collections[Q_index]

    def normalize_area(self) -> None:
        """Normalize the area of the model across all Q values."""
        for collection in self._component_collections:
            collection.normalize_area()

    # ------------------------------------------------------------------
    # Private methods
    # ------------------------------------------------------------------

    def _generate_component_collections(self) -> None:
        """Generate ComponentCollections for each Q value."""

        if self._Q is None:
            self._component_collections = []
            return

        self._component_collections = []
        for _ in self._Q:
            self._component_collections.append(copy(self._components))

    def _on_Q_change(self) -> None:
        """Handle changes to the Q values."""
        self._generate_component_collections()

    def _on_components_change(self) -> None:
        """Handle changes to the components."""
        self._generate_component_collections()

    # ------------------------------------------------------------------
    # dunder methods
    # ------------------------------------------------------------------

    def __repr__(self) -> str:
        """
        Return a string representation of the ModelBase.

        Returns
        -------
        str
            A string representation of the ModelBase.
        """
        return (
            f'{self.__class__.__name__}(unique_name={self.unique_name}, '
            f'unit={self.unit}), Q = {self.Q}, components = {self.components}'
        )

unit property writable

Get the unit of the SampleModel.

Returns:

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

components property writable

Get the components of the SampleModel.

Returns:

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

Q property writable

Get the Q values of the SampleModel.

Returns:

Type	Description
np.ndarray | None	The Q values of the SampleModel, or None if not set.

__init__(display_name='MyModelBase', unique_name=None, unit='meV', components=None, Q=None)

Initialize the ModelBase.

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
unit	str | sc.Unit | None	Unit of the model.	'meV'
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.

Source code in src/easydynamics/sample_model/model_base.py

def __init__(
    self,
    display_name: str = 'MyModelBase',
    unique_name: str | None = None,
    unit: str | sc.Unit | None = 'meV',
    components: ModelComponent | ComponentCollection | None = None,
    Q: Q_type | None = None,
) -> None:
    """
    Initialize the ModelBase.

    Parameters
    ----------
    display_name : str, default='MyModelBase'
        Display name of the model.
    unique_name : str | None, default=None
        Unique name of the model. If None, a unique name will be generated.
    unit : str | sc.Unit | None, default='meV'
        Unit of the model.
    components : ModelComponent | ComponentCollection | None, default=None
        Template components of the model. If None, no components are added. These components
        are copied into ComponentCollections for each Q value.
    Q : Q_type | None, default=None
        Q values for the model. If None, Q is not set.

    Raises
    ------
    TypeError
        If components is not a ModelComponent or ComponentCollection.
    """
    super().__init__(
        unit=unit,
        display_name=display_name,
        unique_name=unique_name,
    )
    self._Q = _validate_and_convert_Q(Q)

    if components is not None and not isinstance(
        components, (ModelComponent, ComponentCollection)
    ):
        raise TypeError(
            f'Components must be a ModelComponent, a ComponentCollection or None, '
            f'got {type(components).__name__}'
        )

    self._components = ComponentCollection()
    if isinstance(components, (ModelComponent, ComponentCollection)):
        self.append_component(components)

    self._generate_component_collections()

evaluate(x)

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. If a scipp Variable or DataArray is provided, the unit of the model will be converted to match the unit of x for evaluation, and the result will be returned in the same unit as x.	required

Raises:

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

Returns:

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

Source code in src/easydynamics/sample_model/model_base.py

def evaluate(
    self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray
) -> list[np.ndarray]:
    """
    Evaluate the sample model at all Q for the given x values.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        Energy axis values to evaluate the model at. If a scipp Variable or DataArray is
        provided, the unit of the model will be converted to match the unit of x for
        evaluation, and the result will be returned in the same unit as x.

    Raises
    ------
    ValueError
        If there are no components in the model to evaluate.

    Returns
    -------
    list[np.ndarray]
        A list of numpy arrays containing the evaluated model values for each Q. The length of
        the list will match the number of Q values in the model.
    """

    if not self._component_collections:
        raise ValueError(
            'No components in the model to evaluate. '
            'Run generate_component_collections() first'
        )
    return [collection.evaluate(x) for collection in self._component_collections]

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

Source code in src/easydynamics/sample_model/model_base.py

def append_component(self, component: ModelComponent | ComponentCollection) -> None:
    """
    Append a ModelComponent or ComponentCollection to the SampleModel.

    Parameters
    ----------
    component : ModelComponent | ComponentCollection
        The ModelComponent or ComponentCollection to append.
    """
    self._components.append_component(component)
    self._on_components_change()

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

Source code in src/easydynamics/sample_model/model_base.py

def remove_component(self, name: str) -> None:
    """
    Remove a ModelComponent from the SampleModel by its name.

    Parameters
    ----------
    name : str
        The name of the ModelComponent to remove.
    """
    self._components.pop(name)
    self._on_components_change()

clear_components()

Clear all ModelComponents from the SampleModel.

Source code in src/easydynamics/sample_model/model_base.py

def clear_components(self) -> None:
    """Clear all ModelComponents from the SampleModel."""
    self._components.clear()
    self._on_components_change()

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.

Source code in src/easydynamics/sample_model/model_base.py

def clear_Q(self, confirm: bool = False) -> None:
    """
    Clear the Q values of the SampleModel, removing all component collections and their
    associated Parameters.

    Parameters
    ----------
    confirm : bool, default=False
        Confirmation to clear Q values.

    Raises
    ------
    ValueError
        If confirm is not True.
    """
    if not confirm:
        raise ValueError(
            'Clearing Q values requires confirmation. Set confirm=True to proceed.'
        )
    self._Q = None
    self._on_Q_change()

convert_unit(unit)

Convert the unit of the ComponentCollection and all its components.

Parameters:

Name	Type	Description	Default
unit	str | sc.Unit	The new unit to convert to.	required

Raises:

Type	Description
TypeError	If the provided unit is not a string or sc.Unit.
Exception	If the provided unit is not compatible with the current unit.

Source code in src/easydynamics/sample_model/model_base.py

def convert_unit(self, unit: str | sc.Unit) -> None:
    """
    Convert the unit of the ComponentCollection and all its components.

    Parameters
    ----------
    unit : str | sc.Unit
        The new unit to convert to.

    Raises
    ------
    TypeError
        If the provided unit is not a string or sc.Unit.
    Exception
        If the provided unit is not compatible with the current unit.
    """

    old_unit = self._unit

    if not isinstance(unit, (str, sc.Unit)):
        raise TypeError(f'Unit must be a string or sc.Unit, got {type(unit).__name__}')
    try:
        for component in self.components:
            component.convert_unit(unit)
        self._unit = unit
    except Exception as e:
        # Attempt to rollback on failure
        try:
            for component in self.components:
                component.convert_unit(old_unit)
        except Exception:  # noqa: S110
            pass  # Best effort rollback
        raise e
    self._on_components_change()

fix_all_parameters()

Fix all Parameters in all ComponentCollections.

Source code in src/easydynamics/sample_model/model_base.py

def fix_all_parameters(self) -> None:
    """Fix all Parameters in all ComponentCollections."""
    for par in self.get_all_variables():
        par.fixed = True

free_all_parameters()

Free all Parameters in all ComponentCollections.

Source code in src/easydynamics/sample_model/model_base.py

def free_all_parameters(self) -> None:
    """Free all Parameters in all ComponentCollections."""
    for par in self.get_all_variables():
        par.fixed = False

get_all_variables(Q_index=None)

Get all Parameters and Descriptors from all ComponentCollections in the ModelBase. Parameters 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

Raises:

Type	Description
TypeError	If Q_index is not an int or None.
IndexError	If Q_index is out of bounds for the number of ComponentCollections.

Returns:

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

Source code in src/easydynamics/sample_model/model_base.py

def get_all_variables(self, Q_index: int | None = None) -> list[Parameter]:
    """
    Get all Parameters and Descriptors from all ComponentCollections in the ModelBase.
    Parameters Ignores the Parameters and Descriptors in self._components as these are just
    templates.

    Parameters
    ----------
    Q_index : int | None, default=None
        If None, get variables for all ComponentCollections. If int, get variables for the
        ComponentCollection at this index.

    Raises
    ------
    TypeError
        If Q_index is not an int or None.
    IndexError
        If Q_index is out of bounds for the number of ComponentCollections.

    Returns
    -------
    list[Parameter]
        A list of all Parameters and Descriptors from the ComponentCollections in the
        ModelBase.
    """

    if Q_index is None:
        all_vars = [
            var
            for collection in self._component_collections
            for var in collection.get_all_variables()
        ]
    else:
        if not isinstance(Q_index, int):
            raise TypeError(f'Q_index must be an int or None, got {type(Q_index).__name__}')
        if Q_index < 0 or Q_index >= len(self._component_collections):
            raise IndexError(
                f'Q_index {Q_index} is out of bounds for component collections '
                f'of length {len(self._component_collections)}'
            )
        all_vars = self._component_collections[Q_index].get_all_variables()
    return all_vars

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

Raises:

Type	Description
TypeError	If Q_index is not an int.
IndexError	If Q_index is out of bounds for the number of ComponentCollections.

Returns:

Type	Description
ComponentCollection	The ComponentCollection at the.

Source code in src/easydynamics/sample_model/model_base.py

def get_component_collection(self, Q_index: int) -> ComponentCollection:
    """
    Get the ComponentCollection at the given Q index.

    Parameters
    ----------
    Q_index : int
        The index of the desired ComponentCollection.

    Raises
    ------
    TypeError
        If Q_index is not an int.
    IndexError
        If Q_index is out of bounds for the number of ComponentCollections.

    Returns
    -------
    ComponentCollection
        The ComponentCollection at the.
    """
    if not isinstance(Q_index, int):
        raise TypeError(f'Q_index must be an int, got {type(Q_index).__name__}')
    if Q_index < 0 or Q_index >= len(self._component_collections):
        raise IndexError(
            f'Q_index {Q_index} is out of bounds for component collections '
            f'of length {len(self._component_collections)}'
        )
    return self._component_collections[Q_index]

normalize_area()

Normalize the area of the model across all Q values.

Source code in src/easydynamics/sample_model/model_base.py

def normalize_area(self) -> None:
    """Normalize the area of the model across all Q values."""
    for collection in self._component_collections:
        collection.normalize_area()

__repr__()

Return a string representation of the ModelBase.

Returns:

Type	Description
str	A string representation of the ModelBase.

Source code in src/easydynamics/sample_model/model_base.py

def __repr__(self) -> str:
    """
    Return a string representation of the ModelBase.

    Returns
    -------
    str
        A string representation of the ModelBase.
    """
    return (
        f'{self.__class__.__name__}(unique_name={self.unique_name}, '
        f'unit={self.unit}), Q = {self.Q}, components = {self.components}'
    )

resolution_model

ResolutionModel

Bases: ModelBase

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

Source code in src/easydynamics/sample_model/resolution_model.py

class ResolutionModel(ModelBase):
    """
    ResolutionModel represents a model of the instrment resolution in an experiment at various Q.
    """

    def __init__(
        self,
        display_name: str = 'MyResolutionModel',
        unique_name: str | None = None,
        unit: str | sc.Unit = 'meV',
        components: ModelComponent | ComponentCollection | None = None,
        Q: Q_type | None = None,
    ) -> None:
        """
        Initialize a ResolutionModel.

        Parameters
        ----------
        display_name : str, default='MyResolutionModel'
            Display name of the model.
        unique_name : str | None, default=None
            Unique name of the model. If None, a unique name will be generated.
        unit : str | sc.Unit, default='meV'
            Unit of the model.
        components : ModelComponent | ComponentCollection | None, default=None
            Template components of the model. If None, no components are added. These components
            are copied into ComponentCollections for each Q value.
        Q : Q_type | None, default=None
            Q values for the model. If None, Q is not set.
        """

        super().__init__(
            display_name=display_name,
            unique_name=unique_name,
            unit=unit,
            components=components,
            Q=Q,
        )

    def append_component(self, component: ModelComponent | ComponentCollection) -> None:
        """
        Append a component to the ResolutionModel.

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

        Parameters
        ----------
        component : ModelComponent | ComponentCollection
            Component(s) to append.

        Raises
        ------
        TypeError
            If the component is a DeltaFunction or Polynomial.
        """
        components = component if isinstance(component, ComponentCollection) else (component,)

        for comp in components:
            if isinstance(comp, (DeltaFunction, Polynomial)):
                raise TypeError(
                    f'Component in ResolutionModel cannot be a {comp.__class__.__name__}'
                )

        super().append_component(component)

__init__(display_name='MyResolutionModel', unique_name=None, unit='meV', components=None, Q=None)

Initialize a ResolutionModel.

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
unit	str | sc.Unit	Unit of the model.	'meV'
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

Source code in src/easydynamics/sample_model/resolution_model.py

def __init__(
    self,
    display_name: str = 'MyResolutionModel',
    unique_name: str | None = None,
    unit: str | sc.Unit = 'meV',
    components: ModelComponent | ComponentCollection | None = None,
    Q: Q_type | None = None,
) -> None:
    """
    Initialize a ResolutionModel.

    Parameters
    ----------
    display_name : str, default='MyResolutionModel'
        Display name of the model.
    unique_name : str | None, default=None
        Unique name of the model. If None, a unique name will be generated.
    unit : str | sc.Unit, default='meV'
        Unit of the model.
    components : ModelComponent | ComponentCollection | None, default=None
        Template components of the model. If None, no components are added. These components
        are copied into ComponentCollections for each Q value.
    Q : Q_type | None, default=None
        Q values for the model. If None, Q is not set.
    """

    super().__init__(
        display_name=display_name,
        unique_name=unique_name,
        unit=unit,
        components=components,
        Q=Q,
    )

append_component(component)

Append a component to the ResolutionModel.

Does not allow DeltaFunction or Polynomial 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 or Polynomial.

Source code in src/easydynamics/sample_model/resolution_model.py

def append_component(self, component: ModelComponent | ComponentCollection) -> None:
    """
    Append a component to the ResolutionModel.

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

    Parameters
    ----------
    component : ModelComponent | ComponentCollection
        Component(s) to append.

    Raises
    ------
    TypeError
        If the component is a DeltaFunction or Polynomial.
    """
    components = component if isinstance(component, ComponentCollection) else (component,)

    for comp in components:
        if isinstance(comp, (DeltaFunction, Polynomial)):
            raise TypeError(
                f'Component in ResolutionModel cannot be a {comp.__class__.__name__}'
            )

    super().append_component(component)

sample_model

SampleModel

Bases: ModelBase

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.

Source code in src/easydynamics/sample_model/sample_model.py

class SampleModel(ModelBase):
    """
    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.
    """

    def __init__(
        self,
        display_name: str = 'MySampleModel',
        unique_name: str | None = None,
        unit: str | sc.Unit = 'meV',
        components: ModelComponent | ComponentCollection | None = None,
        Q: Q_type | None = None,
        diffusion_models: DiffusionModelBase | list[DiffusionModelBase] | None = None,
        temperature: float | None = None,
        temperature_unit: str | sc.Unit = 'K',
        detailed_balance_settings: DetailedBalanceSettings | None = None,
    ) -> None:
        """
        Initialize the SampleModel.

        Parameters
        ----------
        display_name : str, default='MySampleModel'
            Display name of the model.
        unique_name : str | None, default=None
            Unique name of the model. If None, a unique name will be generated.
        unit : str | sc.Unit, default='meV'
            Unit of the model. If None,.
        components : ModelComponent | ComponentCollection | None, default=None
            Template components of the model. If None, no components are added. These components
            are copied into ComponentCollections for each Q value.
        Q : Q_type | None, default=None
            Q values for the model. If None, Q is not set.
        diffusion_models : DiffusionModelBase | list[DiffusionModelBase] | None, default=None
            Diffusion models to include in the SampleModel. If None, no diffusion models are added.
        temperature : float | None, default=None
            Temperature for detailed balancing. If None, no detailed balancing is applied. By
            default, None.
        temperature_unit : str | sc.Unit, default='K'
            Unit of the temperature.
        detailed_balance_settings : DetailedBalanceSettings | None, default=None
            Settings for detailed balancing.

        Raises
        ------
        TypeError
            If diffusion_models is not a DiffusionModelBase, a list of DiffusionModelBase, or None,
            or if temperature is not a number or None, or if detailed_balance_settings is not a
            DetailedBalanceSettings instance.
        ValueError
            If temperature is negative.
        """
        if diffusion_models is None:
            self._diffusion_models = []
        elif isinstance(diffusion_models, DiffusionModelBase):
            self._diffusion_models = [diffusion_models]
        else:
            if not isinstance(diffusion_models, list) or not all(
                isinstance(dm, DiffusionModelBase) for dm in diffusion_models
            ):
                raise TypeError(
                    'diffusion_models must be a DiffusionModelBase, '
                    'a list of DiffusionModelBase or None'
                )
            self._diffusion_models = diffusion_models

        super().__init__(
            display_name=display_name,
            unique_name=unique_name,
            unit=unit,
            components=components,
            Q=Q,
        )

        if temperature is None:
            self._temperature = None
        else:
            if not isinstance(temperature, Numeric):
                raise TypeError('temperature must be a number or None')

            if temperature < 0:
                raise ValueError('temperature must be non-negative')
            self._temperature = Parameter(
                name='Temperature',
                value=temperature,
                unit=temperature_unit,
                display_name='Temperature',
                fixed=True,
            )
        self._temperature_unit = temperature_unit

        if detailed_balance_settings is None:
            self._detailed_balance_settings = DetailedBalanceSettings()
        elif isinstance(detailed_balance_settings, DetailedBalanceSettings):
            self._detailed_balance_settings = detailed_balance_settings
        else:
            raise TypeError('detailed_balance_settings must be a DetailedBalanceSettings or None')

    # ------------------------------------------------------------------
    # Component management
    # ------------------------------------------------------------------

    def append_diffusion_model(self, diffusion_model: DiffusionModelBase) -> None:
        """
        Append a DiffusionModel to the SampleModel.

        Parameters
        ----------
        diffusion_model : DiffusionModelBase
            The DiffusionModel to append.

        Raises
        ------
        TypeError
            If the diffusion_model is not a DiffusionModelBase.
        """

        if not isinstance(diffusion_model, DiffusionModelBase):
            raise TypeError(
                f'diffusion_model must be a DiffusionModelBase, got {type(diffusion_model).__name__}'  # noqa: E501
            )

        self._diffusion_models.append(diffusion_model)
        self._generate_component_collections()

    def remove_diffusion_model(self, name: str) -> None:
        """
        Remove a DiffusionModel from the SampleModel by name.

        Parameters
        ----------
        name : str
            The name of the DiffusionModel to remove.

        Raises
        ------
        ValueError
            If no DiffusionModel with the given name is found.
        """
        for i, dm in enumerate(self._diffusion_models):
            if dm.name == name:
                del self._diffusion_models[i]
                self._generate_component_collections()
                return
        raise ValueError(
            f'No DiffusionModel with name {name} found. \n'
            f'The available names are: {[dm.name for dm in self._diffusion_models]}'
        )

    def clear_diffusion_models(self) -> None:
        """Clear all DiffusionModels from the SampleModel."""
        self._diffusion_models.clear()
        self._generate_component_collections()

    # ------------------------------------------------------------------
    # Properties
    # ------------------------------------------------------------------

    @property
    def diffusion_models(self) -> list[DiffusionModelBase]:
        """
        Get the diffusion models of the SampleModel.

        Returns
        -------
        list[DiffusionModelBase]
            The diffusion models of the SampleModel.
        """
        return self._diffusion_models

    @diffusion_models.setter
    def diffusion_models(
        self, value: DiffusionModelBase | list[DiffusionModelBase] | None
    ) -> None:
        """
        Set the diffusion models of the SampleModel.

        Parameters
        ----------
        value : DiffusionModelBase | list[DiffusionModelBase] | None
            The diffusion model(s) to set. Can be a single DiffusionModelBase, a list of
            DiffusionModelBase, or None to clear all diffusion models.

        Raises
        ------
        TypeError
            If value is not a DiffusionModelBase, a list of DiffusionModelBase, or None.
        """

        if value is None:
            self._diffusion_models = []
            return
        if isinstance(value, DiffusionModelBase):
            self._diffusion_models = [value]
            return
        if not isinstance(value, list) or not all(
            isinstance(dm, DiffusionModelBase) for dm in value
        ):
            raise TypeError(
                'diffusion_models must be a DiffusionModelBase, a list of DiffusionModelBase, '
                'or None'
            )
        self._diffusion_models = value
        self._on_diffusion_models_change()

    @property
    def temperature(self) -> Parameter | None:
        """
        Get the temperature of the SampleModel.

        Returns
        -------
        Parameter | None
            The temperature Parameter of the SampleModel, or None if not set.
        """
        return self._temperature

    @temperature.setter
    def temperature(self, value: Numeric | None) -> None:
        """
        Set the temperature of the SampleModel.

        Parameters
        ----------
        value : Numeric | None
            The temperature value to set. Can be a number or None to unset the temperature.

        Raises
        ------
        TypeError
            If value is not a number or None.
        ValueError
            If value is negative.
        """
        if value is None:
            self._temperature = None
            return

        if not isinstance(value, Numeric):
            raise TypeError('temperature must be a number or None')

        if value < 0:
            raise ValueError('temperature must be non-negative')

        if self._temperature is None:
            self._temperature = Parameter(
                name='Temperature',
                value=value,
                unit=self._temperature_unit,
                display_name='Temperature',
                fixed=True,
            )
        else:
            self._temperature.value = value

    @property
    def temperature_unit(self) -> str | sc.Unit:
        """
        Get the temperature unit of the SampleModel.

        Returns
        -------
        str | sc.Unit
            The unit of the temperature Parameter.
        """
        return self._temperature_unit

    @temperature_unit.setter
    def temperature_unit(self, _value: str | sc.Unit) -> None:
        """
        The temperature unit of the SampleModel is read-only.

        Parameters
        ----------
        _value : str | sc.Unit
            The unit to set for the temperature Parameter.

        Raises
        ------
        AttributeError
            Always, as temperature_unit is read-only.
        """

        raise AttributeError(
            f'Temperature_unit is read-only. Use convert_temperature_unit to change the unit between allowed types '  # noqa: E501
            f'or create a new {self.__class__.__name__} with the desired unit.'
        )

    def convert_temperature_unit(self, unit: str | sc.Unit) -> None:
        """
        Convert the unit of the temperature Parameter.

        Parameters
        ----------
        unit : str | sc.Unit
            The unit to convert the temperature Parameter to.

        Raises
        ------
        ValueError
            If temperature is not set or conversion fails.
        Exception
            If the provided unit is invalid or cannot be converted.
        """

        if self.temperature is None:
            raise ValueError('Temperature is not set, cannot convert unit.')

        old_unit = self.temperature.unit

        try:
            self.temperature.convert_unit(unit)
            self._temperature_unit = unit
        except Exception:
            # Attempt to rollback on failure
            with suppress(Exception):
                self.temperature.convert_unit(old_unit)
            raise

    @property
    def normalize_detailed_balance(self) -> bool:
        """
        Get whether to divide the detailed balance factor by temperature.

        Returns
        -------
        bool
            True if the detailed balance factor is divided by temperature, False otherwise.
        """
        return self.detailed_balance_settings.normalize_detailed_balance

    @normalize_detailed_balance.setter
    def normalize_detailed_balance(self, value: bool) -> None:
        """
        Set whether to divide the detailed balance factor by temperature.

        Parameters
        ----------
        value : bool
            True to divide the detailed balance factor by temperature, False otherwise.

        Raises
        ------
        TypeError
            If value is not a bool.
        """
        if not isinstance(value, bool):
            raise TypeError('normalize_detailed_balance must be True or False')
        self.detailed_balance_settings.normalize_detailed_balance = value

    @property
    def use_detailed_balance(self) -> bool:
        """
        Get whether to apply detailed balance to the model.

        Returns
        -------
        bool
            True if detailed balance is applied, False otherwise.
        """
        return self.detailed_balance_settings.use_detailed_balance

    @use_detailed_balance.setter
    def use_detailed_balance(self, value: bool) -> None:
        """
        Set whether to apply detailed balance to the model.

        Parameters
        ----------
        value : bool
            True to apply detailed balance, False otherwise.

        Raises
        ------
        TypeError
            If value is not a bool.
        """
        if not isinstance(value, bool):
            raise TypeError('use_detailed_balance must be True or False')
        self.detailed_balance_settings.use_detailed_balance = value

    @property
    def detailed_balance_settings(self) -> DetailedBalanceSettings:
        """
        Get the DetailedBalanceSettings of the SampleModel.

        Returns
        -------
        DetailedBalanceSettings
            The DetailedBalanceSettings of the SampleModel.
        """
        return self._detailed_balance_settings

    @detailed_balance_settings.setter
    def detailed_balance_settings(self, value: DetailedBalanceSettings) -> None:
        """
        Set the DetailedBalanceSettings of the SampleModel.

        Parameters
        ----------
        value : DetailedBalanceSettings
            The DetailedBalanceSettings to set.

        Raises
        ------
        TypeError
            If value is not a DetailedBalanceSettings.
        """
        if not isinstance(value, DetailedBalanceSettings):
            raise TypeError('detailed_balance_settings must be a DetailedBalanceSettings')
        self._detailed_balance_settings = value

    # ------------------------------------------------------------------
    # Other methods
    # ------------------------------------------------------------------

    def evaluate(
        self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray
    ) -> list[np.ndarray]:
        """
        Evaluate the sample model at all Q for the given x values.

        Parameters
        ----------
        x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
            The x values to evaluate the model at. Can be a number, list, numpy array, scipp
            Variable, or scipp DataArray.

        Returns
        -------
        list[np.ndarray]
            List of evaluated model values for each Q.
        """

        y = super().evaluate(x)

        if self.temperature is not None and self.detailed_balance_settings.use_detailed_balance:
            DBF = detailed_balance_factor(
                energy=x,
                temperature=self.temperature,
                divide_by_temperature=self.detailed_balance_settings.normalize_detailed_balance,
                energy_unit=self.unit,
            )
            y = [yi * DBF for yi in y]

        return y

    def get_all_variables(self, Q_index: int | None = None) -> list[Parameter]:
        """
        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
        ----------
        Q_index : int | None, default=None
            If specified, only get variables from the ComponentCollection at the given Q index. If
            None, get variables from all ComponentCollections.

        Returns
        -------
        list[Parameter]
            List of all Parameters and Descriptors, including temperature if set and all variables
            from diffusion models.
        """

        all_vars = super().get_all_variables(Q_index=Q_index)
        if self.temperature is not None:
            all_vars.append(self.temperature)

        for diffusion_model in self._diffusion_models:
            all_vars.extend(diffusion_model.get_all_variables())

        return all_vars

    # ------------------------------------------------------------------
    # Private methods
    # ------------------------------------------------------------------

    def _generate_component_collections(self) -> None:
        """
        Generate ComponentCollections from the DiffusionModels for each Q and add the components
        from self._components.
        """
        super()._generate_component_collections()

        if self.Q is None:
            return
        # Generate components from diffusion models
        # and add to component collections
        for diffusion_model in self._diffusion_models:
            diffusion_collections = diffusion_model.create_component_collections(
                Q=self.Q,
                component_name=diffusion_model.name,
            )
            for target, source in zip(
                self._component_collections,
                diffusion_collections,
                strict=True,
            ):
                for component in source:
                    target.append_component(component)

    def _on_diffusion_models_change(self) -> None:
        """Handle changes to the diffusion models."""
        self._generate_component_collections()

    # ------------------------------------------------------------------
    # dunder methods
    # ------------------------------------------------------------------

    def __repr__(self) -> str:
        """
        Return a string representation of the SampleModel.

        Returns
        -------
        str
            A string representation of the SampleModel.
        """

        return (
            f'{self.__class__.__name__}(unique_name={self.unique_name}, unit={self.unit}), '
            f'Q = {self.Q}, \n '
            f'components = {self.components}, diffusion_models = {self.diffusion_models}, '
            f'temperature = {self.temperature}, '
            f'detailed_balance_settings = {self.detailed_balance_settings}'
        )

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 of the SampleModel.

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 to apply detailed balance to the model.

Returns:

Type	Description
bool	True if detailed balance is applied, False otherwise.

detailed_balance_settings property writable

Get the DetailedBalanceSettings of the SampleModel.

Returns:

Type	Description
DetailedBalanceSettings	The DetailedBalanceSettings of the SampleModel.

__init__(display_name='MySampleModel', unique_name=None, unit='meV', components=None, Q=None, diffusion_models=None, temperature=None, temperature_unit='K', detailed_balance_settings=None)

Initialize the SampleModel.

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
unit	str | sc.Unit	Unit of the model. If None,.	'meV'
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
diffusion_models	DiffusionModelBase | list[DiffusionModelBase] | None	Diffusion models to include in the SampleModel. If None, no diffusion models are added.	None
temperature	float | None	Temperature for detailed balancing. If None, no detailed balancing is applied. By default, None.	None
temperature_unit	str | sc.Unit	Unit of the temperature.	'K'
detailed_balance_settings	DetailedBalanceSettings | None	Settings for detailed balancing.	None

Raises:

Type	Description
TypeError	If diffusion_models is not a DiffusionModelBase, a list of DiffusionModelBase, or None, or if temperature is not a number or None, or if detailed_balance_settings is not a DetailedBalanceSettings instance.
ValueError	If temperature is negative.

Source code in src/easydynamics/sample_model/sample_model.py

def __init__(
    self,
    display_name: str = 'MySampleModel',
    unique_name: str | None = None,
    unit: str | sc.Unit = 'meV',
    components: ModelComponent | ComponentCollection | None = None,
    Q: Q_type | None = None,
    diffusion_models: DiffusionModelBase | list[DiffusionModelBase] | None = None,
    temperature: float | None = None,
    temperature_unit: str | sc.Unit = 'K',
    detailed_balance_settings: DetailedBalanceSettings | None = None,
) -> None:
    """
    Initialize the SampleModel.

    Parameters
    ----------
    display_name : str, default='MySampleModel'
        Display name of the model.
    unique_name : str | None, default=None
        Unique name of the model. If None, a unique name will be generated.
    unit : str | sc.Unit, default='meV'
        Unit of the model. If None,.
    components : ModelComponent | ComponentCollection | None, default=None
        Template components of the model. If None, no components are added. These components
        are copied into ComponentCollections for each Q value.
    Q : Q_type | None, default=None
        Q values for the model. If None, Q is not set.
    diffusion_models : DiffusionModelBase | list[DiffusionModelBase] | None, default=None
        Diffusion models to include in the SampleModel. If None, no diffusion models are added.
    temperature : float | None, default=None
        Temperature for detailed balancing. If None, no detailed balancing is applied. By
        default, None.
    temperature_unit : str | sc.Unit, default='K'
        Unit of the temperature.
    detailed_balance_settings : DetailedBalanceSettings | None, default=None
        Settings for detailed balancing.

    Raises
    ------
    TypeError
        If diffusion_models is not a DiffusionModelBase, a list of DiffusionModelBase, or None,
        or if temperature is not a number or None, or if detailed_balance_settings is not a
        DetailedBalanceSettings instance.
    ValueError
        If temperature is negative.
    """
    if diffusion_models is None:
        self._diffusion_models = []
    elif isinstance(diffusion_models, DiffusionModelBase):
        self._diffusion_models = [diffusion_models]
    else:
        if not isinstance(diffusion_models, list) or not all(
            isinstance(dm, DiffusionModelBase) for dm in diffusion_models
        ):
            raise TypeError(
                'diffusion_models must be a DiffusionModelBase, '
                'a list of DiffusionModelBase or None'
            )
        self._diffusion_models = diffusion_models

    super().__init__(
        display_name=display_name,
        unique_name=unique_name,
        unit=unit,
        components=components,
        Q=Q,
    )

    if temperature is None:
        self._temperature = None
    else:
        if not isinstance(temperature, Numeric):
            raise TypeError('temperature must be a number or None')

        if temperature < 0:
            raise ValueError('temperature must be non-negative')
        self._temperature = Parameter(
            name='Temperature',
            value=temperature,
            unit=temperature_unit,
            display_name='Temperature',
            fixed=True,
        )
    self._temperature_unit = temperature_unit

    if detailed_balance_settings is None:
        self._detailed_balance_settings = DetailedBalanceSettings()
    elif isinstance(detailed_balance_settings, DetailedBalanceSettings):
        self._detailed_balance_settings = detailed_balance_settings
    else:
        raise TypeError('detailed_balance_settings must be a DetailedBalanceSettings or None')

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.

Source code in src/easydynamics/sample_model/sample_model.py

def append_diffusion_model(self, diffusion_model: DiffusionModelBase) -> None:
    """
    Append a DiffusionModel to the SampleModel.

    Parameters
    ----------
    diffusion_model : DiffusionModelBase
        The DiffusionModel to append.

    Raises
    ------
    TypeError
        If the diffusion_model is not a DiffusionModelBase.
    """

    if not isinstance(diffusion_model, DiffusionModelBase):
        raise TypeError(
            f'diffusion_model must be a DiffusionModelBase, got {type(diffusion_model).__name__}'  # noqa: E501
        )

    self._diffusion_models.append(diffusion_model)
    self._generate_component_collections()

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.

Source code in src/easydynamics/sample_model/sample_model.py

def remove_diffusion_model(self, name: str) -> None:
    """
    Remove a DiffusionModel from the SampleModel by name.

    Parameters
    ----------
    name : str
        The name of the DiffusionModel to remove.

    Raises
    ------
    ValueError
        If no DiffusionModel with the given name is found.
    """
    for i, dm in enumerate(self._diffusion_models):
        if dm.name == name:
            del self._diffusion_models[i]
            self._generate_component_collections()
            return
    raise ValueError(
        f'No DiffusionModel with name {name} found. \n'
        f'The available names are: {[dm.name for dm in self._diffusion_models]}'
    )

clear_diffusion_models()

Clear all DiffusionModels from the SampleModel.

Source code in src/easydynamics/sample_model/sample_model.py

def clear_diffusion_models(self) -> None:
    """Clear all DiffusionModels from the SampleModel."""
    self._diffusion_models.clear()
    self._generate_component_collections()

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.

Source code in src/easydynamics/sample_model/sample_model.py

def convert_temperature_unit(self, unit: str | sc.Unit) -> None:
    """
    Convert the unit of the temperature Parameter.

    Parameters
    ----------
    unit : str | sc.Unit
        The unit to convert the temperature Parameter to.

    Raises
    ------
    ValueError
        If temperature is not set or conversion fails.
    Exception
        If the provided unit is invalid or cannot be converted.
    """

    if self.temperature is None:
        raise ValueError('Temperature is not set, cannot convert unit.')

    old_unit = self.temperature.unit

    try:
        self.temperature.convert_unit(unit)
        self._temperature_unit = unit
    except Exception:
        # Attempt to rollback on failure
        with suppress(Exception):
            self.temperature.convert_unit(old_unit)
        raise

evaluate(x)

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. Can be a number, list, numpy array, scipp Variable, or scipp DataArray.	required

Returns:

Type	Description
list[np.ndarray]	List of evaluated model values for each Q.

Source code in src/easydynamics/sample_model/sample_model.py

def evaluate(
    self, x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray
) -> list[np.ndarray]:
    """
    Evaluate the sample model at all Q for the given x values.

    Parameters
    ----------
    x : Numeric | list | np.ndarray | sc.Variable | sc.DataArray
        The x values to evaluate the model at. Can be a number, list, numpy array, scipp
        Variable, or scipp DataArray.

    Returns
    -------
    list[np.ndarray]
        List of evaluated model values for each Q.
    """

    y = super().evaluate(x)

    if self.temperature is not None and self.detailed_balance_settings.use_detailed_balance:
        DBF = detailed_balance_factor(
            energy=x,
            temperature=self.temperature,
            divide_by_temperature=self.detailed_balance_settings.normalize_detailed_balance,
            energy_unit=self.unit,
        )
        y = [yi * DBF for yi in y]

    return y

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]	List of all Parameters and Descriptors, including temperature if set and all variables from diffusion models.

Source code in src/easydynamics/sample_model/sample_model.py

def get_all_variables(self, Q_index: int | None = None) -> list[Parameter]:
    """
    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
    ----------
    Q_index : int | None, default=None
        If specified, only get variables from the ComponentCollection at the given Q index. If
        None, get variables from all ComponentCollections.

    Returns
    -------
    list[Parameter]
        List of all Parameters and Descriptors, including temperature if set and all variables
        from diffusion models.
    """

    all_vars = super().get_all_variables(Q_index=Q_index)
    if self.temperature is not None:
        all_vars.append(self.temperature)

    for diffusion_model in self._diffusion_models:
        all_vars.extend(diffusion_model.get_all_variables())

    return all_vars

__repr__()

Return a string representation of the SampleModel.

Returns:

Type	Description
str	A string representation of the SampleModel.

Source code in src/easydynamics/sample_model/sample_model.py

def __repr__(self) -> str:
    """
    Return a string representation of the SampleModel.

    Returns
    -------
    str
        A string representation of the SampleModel.
    """

    return (
        f'{self.__class__.__name__}(unique_name={self.unique_name}, unit={self.unit}), '
        f'Q = {self.Q}, \n '
        f'components = {self.components}, diffusion_models = {self.diffusion_models}, '
        f'temperature = {self.temperature}, '
        f'detailed_balance_settings = {self.detailed_balance_settings}'
    )