pydasa 0.4.7__py3-none-any.whl

pydasa/elements/specs/numerical.py

@@ -0,0 +1,469 @@
+# -*- coding: utf-8 -*-
+"""
+Module numerical.py
+===========================================
+
+Numerical perspective for variable representation.
+
+This module defines the NumericalSpecs class representing the computational
+value ranges and discretization properties of a variable.
+
+Classes:
+    **NumericalSpecs**: Numerical variable specifications
+
+*IMPORTANT:* Based on the theory from:
+
+    # H.Gorter, *Dimensionalanalyse: Eine Theoririe der physikalischen Dimensionen mit Anwendungen*
+"""
+# native python modules
+# dataclass imports
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Optional
+
+# third-party numerical imports
+import numpy as np
+
+# custom modules
+from pydasa.validations.decorators import validate_type
+
+
+@dataclass
+class NumericalSpecs:
+    """Numerical perspective: computational value ranges. Answers the question: "What VALUES can this variable take?"
+
+    This perspective focuses on:
+        - Concrete bounds (minimum, maximum)
+        - Central tendency (mean value)
+        - Variation (standard deviation)
+        - Discretization for simulations (step size, range arrays)
+        - Unit conversions (original ↔ standardized)
+        - Variable dependencies (calculated variables)
+
+    Attributes:
+        # From NumericalSpecs:
+        # Value ranges (original units)
+            _min (Optional[float]): Minimum value in original units.
+            _max (Optional[float]): Maximum value in original units.
+            _mean (Optional[float]): Mean value in original units.
+            _dev (Optional[float]): Standard deviation in original units.
+        # Value ranges (standardized units)
+            _std_min (Optional[float]): Minimum value in standard units.
+            _std_max (Optional[float]): Maximum value in standard units.
+            _std_mean (Optional[float]): Mean value in standard units.
+            _std_dev (Optional[float]): Standard deviation in standard units.
+            _step (Optional[float]): Step size for simulations.
+            _std_range (np.ndarray): Range for numerical analysis in standardized units and discretization.
+    """
+
+    # Value ranges (original units)
+    # :attr: _min
+    _min: Optional[float] = None
+    """Minimum value in original units."""
+
+    # :attr: _max
+    _max: Optional[float] = None
+    """Maximum value in original units."""
+
+    # :attr: _mean
+    _mean: Optional[float] = None
+    """Mean value in original units."""
+
+    # :attr: _dev
+    _dev: Optional[float] = None
+    """Standard deviation in original units."""
+
+    # Value ranges (standardized units)
+    # :attr: _std_min
+    _std_min: Optional[float] = None
+    """Minimum value in standard units."""
+
+    # :attr: _std_max
+    _std_max: Optional[float] = None
+    """Maximum value in standard units."""
+
+    # :attr: _std_mean
+    _std_mean: Optional[float] = None
+    """Mean value in standard units."""
+
+    # :attr: _std_dev
+    _std_dev: Optional[float] = None
+    """Standard deviation in standard units."""
+
+    # :attr: _step
+    _step: Optional[float] = None
+    """Step size for simulations."""
+
+    # :attr: _std_range
+    _std_range: np.ndarray = field(default_factory=lambda: np.array([]))
+    """Range array for analysis."""
+
+    # Value Ranges (Original Units)
+
+    @property
+    def min(self) -> Optional[float]:
+        """*min* Get minimum range value.
+
+        Returns:
+            Optional[float]: Minimum range value.
+        """
+        return self._min
+
+    @min.setter
+    @validate_type(int, float)
+    def min(self, val: Optional[float]) -> None:
+        """*min* Sets minimum range value.
+
+        Args:
+            val (Optional[float]): Minimum range value.
+
+        Raises:
+            ValueError: If value not a valid number.
+            ValueError: If value is greater than max.
+        """
+        if val is not None and self._max is not None and val > self._max:
+            _msg = f"Minimum {val} cannot be greater than maximum {self._max}."
+            raise ValueError(_msg)
+
+        self._min = val
+
+        # TODO reassert this code later, seems redundant with _prepare_dims()
+        # Update range if all values are available
+        if all([self._min is not None,
+                self._max is not None,
+                self._step is not None]):
+            self._range = np.arange(self._min,
+                                    self._max,
+                                    self._step)
+
+    @property
+    def max(self) -> Optional[float]:
+        """*max* Get the maximum range value.
+
+        Returns:
+            Optional[float]: Maximum range value.
+        """
+        return self._max
+
+    @max.setter
+    @validate_type(int, float)
+    def max(self, val: Optional[float]) -> None:
+        """*max* Sets the maximum range value.
+
+        Args:
+            val (Optional[float]): Maximum range value.
+
+        Raises:
+            ValueError: If value is not a valid number.
+            ValueError: If value is less than min.
+        """
+        # Check if both values exist before comparing
+        if val is not None and self._min is not None and val < self._min:
+            _msg = f"Maximum {val} cannot be less than minimum {self._min}."
+            raise ValueError(_msg)
+
+        self._max = val
+
+        # TODO reassert this code later, seems redundant with _prepare_dims()
+        # Update range if all values are available
+        if all([self._min is not None,
+                self._max is not None,
+                self._step is not None]):
+            self._range = np.arange(self._min,
+                                    self._max,
+                                    self._step)
+
+    @property
+    def mean(self) -> Optional[float]:
+        """*mean* Get the Variable average value.
+
+        Returns:
+            Optional[float]: Variable average value.
+        """
+        return self._mean
+
+    @mean.setter
+    @validate_type(int, float)
+    def mean(self, val: Optional[float]) -> None:
+        """*mean* Sets the Variable mean value.
+
+        Args:
+            val (Optional[float]): Variable mean value.
+
+        Raises:
+            ValueError: If value not a valid number.
+            ValueError: If value is outside min-max range.
+        """
+        # Only validate range if val is not None
+        if val is not None:
+            low = (self._min is not None and val < self._min)
+            high = (self._max is not None and val > self._max)
+            if low or high:
+                _msg = f"Mean {val} "
+                _msg += f"must be between {self._min} and {self._max}."
+                raise ValueError(_msg)
+
+        self._mean = val
+
+    @property
+    def dev(self) -> Optional[float]:
+        """*dev* Get the Variable standard deviation.
+
+        Returns:
+            Optional[float]: Variable standard deviation.
+        """
+        return self._dev
+
+    @dev.setter
+    def dev(self, val: Optional[float]) -> None:
+        """*dev* Sets the Variable standard deviation.
+
+        Args:
+            val (Optional[float]): Variable standard deviation.
+        Raises:
+            ValueError: If value not a valid number.
+        """
+        if val is not None and not isinstance(val, (int, float)):
+            raise ValueError("Standard deviation must be a number.")
+
+        self._dev = val
+
+    # Value Ranges (Standardized Units)
+
+    @property
+    def std_min(self) -> Optional[float]:
+        """*std_min* Get the standardized minimum range value.
+
+        Returns:
+            Optional[float]: standardized minimum range value.
+        """
+        return self._std_min
+
+    @std_min.setter
+    def std_min(self, val: Optional[float]) -> None:
+        """*std_min* Sets the standardized minimum range value.
+
+        Args:
+            val (Optional[float]): standardized minimum range value.
+
+        Raises:
+            ValueError: If value not a valid number.
+            ValueError: If value is greater than std_max.
+        """
+        if val is not None and not isinstance(val, (int, float)):
+            raise ValueError("Standardized minimum must be a number")
+
+        # Check if both values exist before comparing
+        if val is not None and self._std_max is not None and val > self._std_max:
+            _msg = f"Standard minimum {val} cannot be greater"
+            _msg += f" than standard maximum {self._std_max}."
+            raise ValueError(_msg)
+
+        self._std_min = val
+
+        # TODO reassert this code later, seems redundant with _prepare_dims()
+        # Update range if all values are available
+        if all([self._std_min is not None,
+                self._std_max is not None,
+                self._step is not None]):
+            self._std_range = np.arange(self._std_min,
+                                        self._std_max,
+                                        self._step)
+
+    @property
+    def std_max(self) -> Optional[float]:
+        """*std_max* Get the standardized maximum range value.
+
+        Returns:
+            Optional[float]: standardized maximum range value.
+        """
+        return self._std_max
+
+    @std_max.setter
+    def std_max(self, val: Optional[float]) -> None:
+        """*std_max* Sets the standardized maximum range value.
+
+        Raises:
+            ValueError: If value is not a valid number.
+            ValueError: If value is less than std_min.
+        """
+        if val is not None and not isinstance(val, (int, float)):
+            raise ValueError("Standardized maximum must be a number")
+
+        # Check if both values exist before comparing
+        if val is not None and self._std_min is not None and val < self._std_min:
+            _msg = f"Standard maximum {val} cannot be less"
+            _msg += f" than standard minimum {self._std_min}."
+            raise ValueError(_msg)
+
+        self._std_max = val
+
+        # TODO reassert this code later, seems redundant with _prepare_dims()
+        # Update range if all values are available
+        if all([self._std_min is not None,
+                self._std_max is not None,
+                self._step is not None]):
+            self._std_range = np.arange(self._std_min,
+                                        self._std_max,
+                                        self._step)
+
+    @property
+    def std_mean(self) -> Optional[float]:
+        """*std_mean* Get standardized mean value.
+
+        Returns:
+            Optional[float]: standardized mean.
+        """
+        return self._std_mean
+
+    @std_mean.setter
+    def std_mean(self, val: Optional[float]) -> None:
+        """*std_mean* Sets the standardized mean value.
+
+        Args:
+            val (Optional[float]): standardized mean value.
+
+        Raises:
+            ValueError: If value is not a valid number.
+            ValueError: If value is outside std_min-std_max range.
+        """
+        if val is not None and not isinstance(val, (int, float)):
+            raise ValueError("Standardized mean must be a number")
+
+        # Only validate range if val is not None
+        if val is not None:
+            low = (self._std_min is not None and val < self._std_min)
+            high = (self._std_max is not None and val > self._std_max)
+
+            if low or high:
+                _msg = f"Standard mean {val} "
+                _msg += f"must be between {self._std_min} and {self._std_max}."
+                raise ValueError(_msg)
+
+        self._std_mean = val
+
+    @property
+    def std_dev(self) -> Optional[float]:
+        """*std_dev* Get standardized standard deviation.
+
+        Returns:
+            Optional[float]: Standardized standard deviation.
+        """
+        return self._std_dev
+
+    @std_dev.setter
+    def std_dev(self, val: Optional[float]) -> None:
+        """*std_dev* Sets the standardized standard deviation.
+
+        Args:
+            val (Optional[float]): Standardized standard deviation.
+
+        Raises:
+            ValueError: If value is not a valid number.
+            ValueError: If value is outside std_min-std_max range.
+        """
+        if val is not None and not isinstance(val, (int, float)):
+            raise ValueError(
+                "Standardized standard deviation must be a number")
+
+        # Standard deviation should be non-negative
+        if val is not None and val < 0:
+            raise ValueError(f"Standard deviation {val} cannot be negative.")
+
+        self._std_dev = val
+
+    @property
+    def step(self) -> Optional[float]:
+        """*step* Get standardized step size.
+
+        Returns:
+            Optional[float]: Step size (always standardized).
+        """
+        return self._step
+
+    @step.setter
+    def step(self, val: Optional[float]) -> None:
+        """*step* Set standardized step size.
+
+        Args:
+            val (Optional[float]): Step size (always standardized).
+
+        Raises:
+            ValueError: If step is not a valid number.
+            ValueError: If step is zero.
+            ValueError: If step is greater than range.
+        """
+        if val is not None and not isinstance(val, (int, float)):
+            raise ValueError("Step must be a number.")
+
+        if val == 0:
+            raise ValueError("Step cannot be zero.")
+
+        # Validate step against range (only if min/max are set)
+        if val is not None and self._std_min is not None and self._std_max is not None:
+            range_size = self._std_max - self._std_min
+            if val >= range_size:
+                _msg = f"Step {val} must be less than range: {range_size}."
+                raise ValueError(_msg)
+
+        self._step = val
+
+        # TODO reassert this code later, seems redundant with _prepare_dims()
+        # Update range if all values are available
+        if all([self._std_min is not None,
+                self._std_max is not None,
+                self._step is not None]):
+            self._std_range = np.arange(self._std_min,
+                                        self._std_max,
+                                        self._step)
+
+    @property
+    def std_range(self) -> np.ndarray:
+        """*std_range* Get standardized range array.
+
+        Returns:
+            np.ndarray: Range array for range (always standardized).
+        """
+        return self._std_range
+
+    @std_range.setter
+    def std_range(self, val: Optional[np.ndarray]) -> None:
+        """*std_range* Set standardized range array.
+
+        Args:
+            val (Optional[np.ndarray]): Data array for range (always standardized).
+
+        Raises:
+            ValueError: If value is not a numpy array.
+        """
+        # TODO reassert this code later, seems redundant with _prepare_dims()
+        if val is None:
+            # Generate range from min, max, step
+            if all([self._std_min is not None,
+                    self._std_max is not None,
+                    self._step is not None]):
+                self._std_range = np.arange(self._std_min,
+                                            self._std_max,
+                                            self._step)
+
+        # TODO check this latter, might be a hindrance
+        elif not isinstance(val, np.ndarray):
+            _msg = f"Range must be a numpy array, got {type(val)}"
+            raise ValueError(_msg)
+
+        else:
+            self._std_range = val
+
+    def clear(self) -> None:
+        """*clear()* Reset numerical attributes to default values.
+
+        Resets all value ranges and step size.
+        """
+        self._min = None
+        self._max = None
+        self._mean = None
+        self._std_min = None
+        self._std_max = None
+        self._std_mean = None
+        self._step = None
+        self._std_range = np.array([])

pydasa/elements/specs/statistical.py

@@ -0,0 +1,229 @@
+# -*- coding: utf-8 -*-
+"""
+Module statistical.py
+===========================================
+
+Statistical perspective for variable representation.
+
+This module defines the StatisticalSpecs class representing the probabilistic
+distribution and sampling properties of a variable.
+
+Classes:
+    **StatisticalSpecs**: Statistical variable specifications
+
+*IMPORTANT:* Based on the theory from:
+
+    # H.Gorter, *Dimensionalanalyse: Eine Theoririe der physikalischen Dimensionen mit Anwendungen*
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, Callable, List, TYPE_CHECKING
+
+
+@dataclass
+class StatisticalSpecs:
+    """Statistical perspective: probabilistic distributions. Answers the question: "How do we MODEL uncertainty?"
+
+    This perspective focuses on:
+        - Probability distribution types (uniform, normal, beta, custom)
+        - Distribution parameters
+        - Random sampling mechanisms
+        - Monte Carlo simulation support
+        - Uncertainty quantification
+    """
+
+    # Type annotation for sym attribute (defined in Foundation, accessed via composition)
+    if TYPE_CHECKING:
+        _sym: str
+
+    # distribution specifications
+    # :attr: _dist_type
+    _dist_type: str = "uniform"
+    """Type of distribution (e.g., 'uniform', 'normal'). By default is 'uniform'."""
+
+    # :attr: _dist_params
+    _dist_params: Optional[Dict[str, Any]] = field(default_factory=dict)
+    """Parameters for the distribution (e.g., {'min': 0, 'max': 1} for uniform)."""
+
+    # :attr: _depends
+    _depends: List[str] = field(default_factory=list)
+    """List of variable names that this variable depends on. (e.g., for calculated variables like F = m*a)."""
+
+    # :attr: _dist_func
+    _dist_func: Optional[Callable[..., float]] = None
+    """Callable representing the distribution function defined externally by the user."""
+
+    def sample(self, *args) -> float:
+        """*sample()* Generate a random sample.
+
+        Args:
+            *args: Additional arguments for the distribution function.
+
+        Returns:
+            float: Random sample from distribution.
+
+        Raises:
+            ValueError: If no distribution has been set.
+        """
+        if self._dist_func is None:
+            _msg = f"No distribution set for variable '{self._sym}'. "
+            _msg += "Call set_function() first."
+            raise ValueError(_msg)
+
+        # if kwargs are provided, pass them to the function parameters
+        elif len(args) > 0:
+            return self._dist_func(*args)
+
+        # otherwise, execute without them
+        return self._dist_func()
+
+    def has_function(self) -> bool:
+        """*has_function()* Check if distribution is set.
+
+        Returns:
+            bool: True if distribution is configured.
+        """
+        return self._dist_func is not None
+
+    @property
+    def dist_type(self) -> str:
+        """*dist_type* Get the distribution type.
+
+        Returns:
+            str: Distribution type (e.g., 'uniform', 'normal').
+        """
+        return self._dist_type
+
+    @dist_type.setter
+    def dist_type(self, val: str) -> None:
+        """*dist_type* Set the distribution type.
+
+        Args:
+            val (str): Distribution type.
+
+        Raises:
+            ValueError: If distribution type is not supported.
+        """
+        # TODO improve this for later
+        supported_types = [
+            "uniform",
+            "normal",
+            "triangular",
+            "exponential",
+            "lognormal",
+            "custom",
+        ]
+        if val not in supported_types:
+            _msg = f"Unsupported distribution type: {val}. "
+            _msg += f"Supported types: {', '.join(supported_types)}"
+            raise ValueError(_msg)
+        self._dist_type = val
+
+    @property
+    def dist_params(self) -> Optional[Dict[str, Any]]:
+        """*dist_params* Get the distribution parameters.
+
+        Returns:
+            Optional[Dict[str, Any]: Distribution parameters.
+        """
+        return self._dist_params
+
+    @dist_params.setter
+    def dist_params(self, val: Optional[Dict[str, Any]]) -> None:
+        """*dist_params* Set the distribution parameters.
+
+        Args:
+            val (Optional[Dict[str, Any]): Distribution parameters.
+
+        Raises:
+            ValueError: If parameters are invalid for the distribution type.
+        """
+        if val is None:
+            self._dist_params = None
+            return None
+        # Validate parameters based on distribution type
+        if self._dist_type == "uniform":
+            if "min" not in val or "max" not in val:
+                _msg = f"Invalid keys for: {self._dist_type}: {val}"
+                _msg += f" {self._dist_type} needs 'min' and 'max' parameters."
+                _msg += f" Provided keys are: {list(val.keys())}."
+                raise ValueError(_msg)
+            if val["min"] >= val["max"]:
+                _msg = f"Invalid range for {self._dist_type}: {val}"
+                _msg += f" {self._dist_type} needs 'min' to be less than 'max'."
+                _msg += f" Provided: min={val['min']}, max={val['max']}."
+                raise ValueError(_msg)
+        elif self._dist_type == "normal":
+            if "mean" not in val or "std" not in val:
+                _msg = f"Invalid keys for: {self._dist_type}: {val}"
+                _msg += f" {self._dist_type} needs 'mean' and 'std' parameters."
+                _msg += f" Provided keys are: {list(val.keys())}."
+                raise ValueError(_msg)
+            if val["std"] < 0:
+                _msg = f"Invalid value for: {self._dist_type}: {val}"
+                _msg += f" {self._dist_type} requires 'std' to be positive."
+                _msg += f" Provided: std={val['std']}."
+                raise ValueError(_msg)
+        self._dist_params = val
+
+    @property
+    def dist_func(self) -> Optional[Callable[..., float]]:
+        """*dist_func* Get the distribution function.
+
+        Returns:
+            Optional[Callable]: Distribution function.
+        """
+        return self._dist_func
+
+    @dist_func.setter
+    def dist_func(self, val: Optional[Callable[..., float]]) -> None:
+        """*dist_func* Set the distribution function.
+
+        Args:
+            val (Optional[Callable]): Distribution function.
+
+        Raises:
+            TypeError: If value is not callable when provided.
+        """
+        if val is not None and not callable(val):
+            _msg = f"Distribution function must be callable, got {type(val)}"
+            raise TypeError(_msg)
+        self._dist_func = val
+
+    @property
+    def depends(self) -> List[str]:
+        """*depends* Get the list of variable dependencies.
+
+        Returns:
+            List[str]: List of variable names that this variable depends on.
+        """
+        return self._depends
+
+    @depends.setter
+    def depends(self, val: List[str]) -> None:
+        """*depends* Set the list of variable dependencies.
+
+        Args:
+            val (List[str]): List of variable names that this variable depends on.
+        Raises:
+            ValueError: If value is not a list of strings.
+        """
+        if not isinstance(val, list):
+            _msg = f"{val} must be a list of strings."
+            _msg += f" type {type(val)} found instead."
+            raise ValueError(_msg)
+        if not all(isinstance(v, str) for v in val):
+            _msg = f"{val} must be a list of strings."
+            _msg += f" Found types: {[type(v) for v in val]}."
+            raise ValueError(_msg)
+        self._depends = val
+
+    def clear(self) -> None:
+        """*clear()* Reset statistical attributes to default values.
+
+        Resets distribution type, parameters, and function.
+        """
+        self._dist_type = "uniform"
+        self._dist_params = {}
+        self._dist_func = None