ADR suggestion: user defined component

[henrikjacobsenfys]

I haven't found the right name yet - UserComponent? CustomComponent?

Basically, users will have needs that I cannot predict. One asked for an exponential function, but what's next? I want to allow them to define their own function.

Syntax

I think the most straightforward thing is that the users define a function in a file, e.g.

def my_function(x,a,b,c):
    y=ax+bx^2+c

They then create a CustomComponent like this:

my_component = CustomComponent(function=my_function,a=1.0,b=2.0,c=3.0)

And use it like any other component.

Implementation

CustomComponent should then inject the **kwargs like the old ObjBase did and create Parameters and setters and getters out of the variables.

It will inherit from ModelComponent, and it's evaulate method will then have to pass the Parameter.value from each of its Parameters to my_function.

It'll of course need checks on the inputs.

This is a rough idea, and I'd love to receive feedback.

[rozyczko]

CustomComponent should then inject the **kwargs

We should stop using the kwargs magic and do modern introspection to check the signature and discover parameter names.
Using inspect.signature really should be used for custom method sig checks.

I think CustomComponent is more descriptive. UserComponent describes who made it, which isn't really that useful.

You need to rethink the serialization for Custom Components. These will be arbitrary functions which might not easily go through our to_dict.

[henrikjacobsenfys]

I vibe coded this, looks interesting:

# SPDX-FileCopyrightText: 2025 EasyScience contributors <https://github.com/easyscience>
# SPDX-License-Identifier: BSD-3-Clause

from __future__ import annotations

import inspect
from typing import Callable

import numpy as np
import scipp as sc
from easyscience.variable import Parameter

from easydynamics.utils.utils import Numeric
from .model_component import ModelComponent


class CustomComponent(ModelComponent):
    r"""Model component defined by a user-provided Python function.

    The user supplies a callable with signature

    $$
    f(x, p_1, p_2, ..., p_n)
    $$

    where ``x`` is the independent variable and the remaining
    arguments are model parameters.

    Parameters are automatically converted into
    :class:`easyscience.variable.Parameter` objects. Their values are
    passed to the function during evaluation.

    Default values in the function signature are supported.

    Example
    -------
    >>> def exponential(x, A=1.0, tau=0.5):
    ...     return A * np.exp(-x / tau)
    ...
    >>> comp = CustomComponent(function=exponential)
    >>> comp.evaluate([0, 1, 2])

    Args:
        function (Callable): Callable with signature ``f(x, ...)``.
        unit (str | sc.Unit): Unit of the component. Default is ``"meV"``.
        display_name (str | None): Human-readable name. Default
            ``"CustomComponent"``.
        unique_name (str | None): Unique identifier. Default None.
        **kwargs: Optional initial parameter values.

    Raises:
        TypeError: If function is not callable.
        ValueError: If the function signature does not start with ``x``.
    """

    def __init__(
        self,
        function: Callable,
        unit: str | sc.Unit = "meV",
        display_name: str | None = "CustomComponent",
        unique_name: str | None = None,
        **kwargs,
    ):
        super().__init__(unit=unit, display_name=display_name, unique_name=unique_name)

        if not callable(function):
            raise TypeError("function must be callable")

        self.function = function

        sig = inspect.signature(function)
        params = list(sig.parameters.values())

        if not params or params[0].name != "x":
            raise ValueError("Function must have signature f(x, ...)")

        self._parameters = []
        self._param_names = []

        for p in params[1:]:
            value = kwargs.get(
                p.name,
                None if p.default is inspect.Parameter.empty else p.default,
            )

            if value is None:
                raise ValueError(
                    f"Parameter '{p.name}' must be provided or have a default value."
                )

            param = value if isinstance(value, Parameter) else Parameter(p.name, value)

            self._parameters.append(param)
            self._param_names.append(p.name)

            setattr(self, p.name, param)

    def evaluate(
        self,
        x: Numeric | list | np.ndarray | sc.Variable | sc.DataArray,
    ) -> np.ndarray:
        r"""Evaluate the custom component.

        Args:
            x (Numeric or list or np.ndarray or sc.Variable or sc.DataArray):
                Input values.

        Returns:
            np.ndarray: Evaluated function values.
        """

        x = self._prepare_x_for_evaluate(x)

        values = [p.value for p in self._parameters]

        return self.function(x, *values)

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

        params = ", ".join(
            f"{n}={p}" for n, p in zip(self._param_names, self._parameters)
        )

        return (
            f"CustomComponent(unique_name={self.unique_name}, unit={self._unit},\n"
            f" function={self.function.__name__},\n {params})"
        )

and this:

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

    The user supplies a string expression depending on ``x`` and
    arbitrary parameters.

    Parameters are automatically detected and converted into
    :class:`easyscience.variable.Parameter` objects.

    Example
    -------
    >>> comp = ExpressionComponent("A * exp(-x/tau)")
    >>> comp.A.value = 2.0
    >>> comp.tau.value = 0.5
    >>> comp.evaluate([0,1,2])

    Args:
        expression (str): Mathematical expression using ``x``.
        unit (str | sc.Unit): Unit of the component. Default "meV".
        display_name (str | None): Human readable name.
        unique_name (str | None): Unique identifier.

    Raises:
        ValueError: If the expression does not contain ``x``.
    """

    _allowed_names = {
        "exp": np.exp,
        "sin": np.sin,
        "cos": np.cos,
        "log": np.log,
        "sqrt": np.sqrt,
        "abs": np.abs,
        "pi": np.pi,
    }

    def __init__(
        self,
        expression: str,
        unit: str | sc.Unit = "meV",
        display_name: str | None = "ExpressionComponent",
        unique_name: str | None = None,
    ):

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

        self.expression = expression

        names = self._extract_symbols(expression)

        if "x" not in names:
            raise ValueError("Expression must contain variable 'x'")

        self._param_names = sorted(n for n in names if n != "x")

        self._parameters = []

        for name in self._param_names:
            p = Parameter(name=name, value=1.0)
            setattr(self, name, p)
            self._parameters.append(p)

        self._code = compile(expression, "<expression>", "eval")

    def _extract_symbols(self, expression):

        tree = ast.parse(expression)

        return {
            node.id
            for node in ast.walk(tree)
            if isinstance(node, ast.Name)
        }

    def evaluate(self, x):

        x = self._prepare_x_for_evaluate(x)

        namespace = {"x": x}
        namespace.update(self._allowed_names)

        for p in self._parameters:
            namespace[p.name] = p.value

        return eval(self._code, {"__builtins__": {}}, namespace)

[henrikjacobsenfys]

second file didn't work, vibed it to this which seems to work

import ast

import numpy as np
import scipp as sc
from easyscience.variable import Parameter

from .model_component import ModelComponent


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

    The user supplies a string expression depending on ``x`` and
    arbitrary parameters.

    Parameters are automatically detected and converted into
    :class:`easyscience.variable.Parameter` objects.

    Example
    -------
    >>> comp = ExpressionComponent("A * exp(-x/tau)")
    >>> comp.A.value = 2.0
    >>> comp.tau.value = 0.5
    >>> comp.evaluate([0,1,2])

    Args:
        expression (str): Mathematical expression using ``x``.
        unit (str | sc.Unit): Unit of the component. Default "meV".
        display_name (str | None): Human readable name.
        unique_name (str | None): Unique identifier.

    Raises:
        ValueError: If the expression does not contain ``x``.
        ValueError: If the expression contains unsafe syntax.
    """

    _allowed_names = {
        "exp": np.exp,
        "sin": np.sin,
        "cos": np.cos,
        "log": np.log,
        "sqrt": np.sqrt,
        "abs": np.abs,
        "pi": np.pi,
    }

    _allowed_nodes = (
        ast.Expression,
        ast.BinOp,
        ast.UnaryOp,
        ast.Add,
        ast.Sub,
        ast.Mult,
        ast.Div,
        ast.Pow,
        ast.USub,
        ast.UAdd,
        ast.Call,
        ast.Name,
        ast.Load,
        ast.Constant,
    )

    def __init__(
        self,
        expression: str,
        unit: str | sc.Unit = "meV",
        display_name: str | None = "ExpressionComponent",
        unique_name: str | None = None,
    ):

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

        self.expression = expression

        tree = ast.parse(expression, mode="eval")

        self._validate_ast(tree)

        names = self._extract_symbols(tree)

        if "x" not in names:
            raise ValueError("Expression must contain variable 'x'")

        self._param_names = sorted(
            n for n in names if n != "x" and n not in self._allowed_names
        )

        self._parameters = []

        for name in self._param_names:
            p = Parameter(name=name, value=1.0)
            setattr(self, name, p)
            self._parameters.append(p)

        self._code = compile(tree, "<expression>", "eval")

    def _validate_ast(self, tree):
        """Ensure the AST contains only safe nodes."""
        for node in ast.walk(tree):

            if not isinstance(node, self._allowed_nodes):
                raise ValueError(
                    f"Unsupported syntax '{type(node).__name__}' in expression."
                )

            if isinstance(node, ast.Call):

                if not isinstance(node.func, ast.Name):
                    raise ValueError("Only simple function calls are allowed.")

                if node.func.id not in self._allowed_names:
                    raise ValueError(f"Function '{node.func.id}' is not allowed.")

    def _extract_symbols(self, tree):
        """Extract variable names used in the expression."""
        return {node.id for node in ast.walk(tree) if isinstance(node, ast.Name)}

    def evaluate(self, x):
        """Evaluate the expression for the given x values."""

        x = self._prepare_x_for_evaluate(x)

        namespace = {"x": x}

        namespace.update(self._allowed_names)

        for p in self._parameters:
            namespace[p.name] = p.value

        return eval(self._code, {"__builtins__": {}}, namespace)