Source code for tensorwaves.interfaces

"""Defines top-level interfaces of tensorwaves."""

from abc import ABC, abstractmethod
from typing import Optional, Tuple, Union


[docs]class Function(ABC):
    """Interface of a callable function.

    The parameters of the model are separated from the domain variables. This
    follows the mathematical definition, in which a function defines its domain
    and parameters. However specific points in the domain are not relevant.
    Hence while the domain variables are the argument of the evaluation
    (see :func:`~Function.__call__`), the parameters are controlled via a
    getter and setter (see :func:`~Function.parameters`). The reason for this
    separation is to facilitate the events when parameters have changed.
    """

[docs]    @abstractmethod
    def __call__(self, dataset: dict) -> list:
        """Evaluate the function.

        Args:
            dataset: a `dict` with domain variable names as keys.

        Return:
            `list` or `numpy.array` of values.

        """

    @property
    @abstractmethod
    def parameters(self) -> dict:
        """Get `dict` of parameters."""

[docs]    @abstractmethod
    def update_parameters(self, new_parameters: dict) -> None:
        """Update the collection of parameters."""


[docs]class Estimator(ABC):
    """Estimator for discrepancy model and data."""

[docs]    @abstractmethod
    def __call__(self) -> float:
        """Evaluate discrepancy."""

[docs]    @abstractmethod
    def gradient(self) -> list:
        """Compute the gradient of the data set."""

    @property
    @abstractmethod
    def parameters(self) -> dict:
        """Get `dict` of parameters."""

[docs]    @abstractmethod
    def update_parameters(self, new_parameters: dict) -> None:
        """Update the collection of parameters."""


[docs]class Kinematics(ABC):
    """Abstract interface for computation of kinematic variables."""

[docs]    @abstractmethod
    def convert(self, events: dict) -> dict:
        """Convert a set of momentum tuples (events) to kinematic variables."""

[docs]    @abstractmethod
    def is_within_phase_space(self, events: dict) -> Tuple[bool]:
        """Check which events lie within phase space."""

    @property
    @abstractmethod
    def phase_space_volume(self) -> float:
        """Compute volume of the phase space."""


[docs]class Optimizer(ABC):
    """Optimize a fit model to a data set."""

[docs]    @abstractmethod
    def optimize(self, estimator: Estimator, initial_parameters: dict) -> dict:
        """Execute optimization."""


[docs]class UniformRealNumberGenerator(ABC):
    """Abstract class for generating uniform real numbers."""

[docs]    @abstractmethod
    def __call__(
        self, size: int, min_value: float = 0.0, max_value: float = 1.0
    ) -> Union[float, list]:
        """Generate random floats in the range from [min_value,max_value)."""

    @property  # type: ignore
    @abstractmethod
    def seed(self) -> Optional[float]:
        """Get random seed. `None` if you want indeterministic behavior."""

    @seed.setter  # type: ignore
    @abstractmethod
    def seed(self, value: Optional[float]) -> None:
        """Set random seed. Use `None` for indeterministic behavior."""


[docs]class PhaseSpaceGenerator(ABC):
    """Abstract class for generating phase space samples."""

[docs]    @abstractmethod
    def generate(self, size: int, rng: UniformRealNumberGenerator) -> dict:
        """Generate phase space sample."""
TensorWaves

Source code for tensorwaves.interfaces
