pydasa 0.4.7__py3-none-any.whl

pydasa/elements/parameter.py

@@ -0,0 +1,218 @@
+# -*- coding: utf-8 -*-
+"""
+Module parameter.py
+===========================================
+
+Module for representing **Variable** entities in Dimensional Analysis for *PyDASA*.
+
+Classes:
+    **Variable**: Represents a Variable with dimensional properties, value ranges, and validation.
+
+*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, fields
+# data type imports
+from typing import Dict, Any
+# numerical imports
+import numpy as np
+
+# custom modules
+# Import the four compositional perspectives
+from pydasa.elements.specs import ConceptualSpecs
+from pydasa.elements.specs import SymbolicSpecs
+from pydasa.elements.specs import NumericalSpecs
+from pydasa.elements.specs import StatisticalSpecs
+# pattern interpreter imports
+from pydasa.serialization.parser import latex_to_python
+
+
+@dataclass
+class Variable(ConceptualSpecs, SymbolicSpecs, NumericalSpecs, StatisticalSpecs):
+    """**Variable** class for Dimensional Analysis in *PyDASA*.
+
+    A comprehensive implementation that combines Parameter and Variable functionality
+    for use in dimensional analysis calculations, simulations, and sensitivity analysis.
+
+    This class composes four philosophical perspectives through multiple inheritance:
+    - **ConceptualSpecs**: Identity and classification (what IS this variable?)
+    - **SymbolicSpecs**: Mathematical representation (how do we WRITE it?)
+    - **NumericalSpecs**: Computational values (what VALUES can it take?)
+    - **StatisticalSpecs**: Probabilistic modeling (how do we MODEL uncertainty?)
+
+    All attributes, properties, and methods are inherited from the spec classes.
+    This class only provides integration logic and utility methods.
+
+    Attributes:
+        # From Foundation (via ConceptualSpecs)
+        _name (str): User-friendly name of the variable.
+        description (str): Brief summary of the variable.
+        _idx (int): Index/precedence in the dimensional matrix.
+        _sym (str): Symbol representation (LaTeX or alphanumeric).
+        _alias (str): Python-compatible alias for use in code.
+        _fwk (str): Frameworks context (PHYSICAL, COMPUTATION, SOFTWARE, CUSTOM).
+
+        # From ConceptualSpecs - Identity and Classification
+        _cat (str): Category (INPUT, OUT, CTRL).
+        _schema (Schema): Reference to the dimensional framework or FDUs list.
+        relevant (bool): Flag indicating if variable is relevant for analysis.
+
+        # From SymbolicSpecs - Dimensional Properties
+        _dims (str): Dimensional expression (e.g., "L*T^-1").
+        _units (str): Units of measure (e.g., "m/s").
+        _sym_exp (str): Sympy-compatible expression.
+        _dim_col (List[int]): Dimensional column for matrix operations.
+
+        # From SymbolicSpecs - Standardized Dimensional Properties
+        _std_dims (str): Standardized dimensional expression.
+        _std_units (str): Standardized units of measure.
+
+        # From NumericalSpecs - Value Ranges (Original Units)
+        _min (float): Minimum value in original units.
+        _max (float): Maximum value in original units.
+        _mean (float): Mean value in original units.
+        _dev (float): Standard deviation in original units.
+
+        # From NumericalSpecs - Value Ranges (Standardized Units)
+        _std_min (float): Minimum value in standard units.
+        _std_max (float): Maximum value in standard units.
+        _std_mean (float): Mean value in standard units.
+        _std_dev (float): Standard deviation in standard units.
+        _step (float): Step size for simulations.
+        _std_range (np.ndarray): Range array for analysis.
+
+        # From StatisticalSpecs - Distribution Specifications
+        _dist_type (str): Type of distribution (e.g., 'uniform', 'normal').
+        _dist_params (Dict[str, Any]): Parameters for the distribution.
+        _depends (List[str]): List of variable names that this variable depends on.
+        _dist_func (Callable): Callable representing the distribution function.
+    """
+
+    def __post_init__(self) -> None:
+        """*__post_init__()* Initializes the variable and validates its properties.
+
+        Performs validation of core properties and processes dimensional expressions.
+        Sets up range arrays if all required values are provided.
+
+        Raises:
+            ValueError: If dimensional expression is invalid.
+        """
+        # Initialize from base class (ConceptualSpecs -> Foundation)
+        # This also sets up the schema based on framework
+        super().__post_init__()
+
+        if not self._sym:
+            self._sym = f"V_{self._idx}" if self._idx >= 0 else "V_{}"
+
+        # if custom schema is provided and dimensions exist
+        if self._schema and len(self._dims) > 0 and self._dims != "n.a.":
+            #     if not self._schema.validate_dims(self._dims):
+            #         raise ValueError(f"Invalid dimensions for {self._fwk}")
+            # # Process dimensions if provided
+            # if len(self._dims) > 0 and self._dims != "n.a.":
+            _schema = self._schema
+            if not self._validate_exp(self._dims, _schema.fdu_regex):
+                _msg = f"Invalid dimensions {self._dims} for '{self._sym}'."
+                _msg += f"Check FDU precedence list: {_schema.fdu_lt}."
+                raise ValueError(_msg)
+            self._prepare_dims()
+
+        # Set the Python alias if not specified
+        if not self._alias:
+            self._alias = latex_to_python(self._sym)
+
+        # TODO reassert this code later, seems redundant
+        # Set up range array if all required values are provided
+        if all([self._std_min, self._std_max, self._step]):
+            self._std_range = np.arange(self._std_min,
+                                        self._std_max,
+                                        self._step)
+
+    # NOTE: All methods below are inherited from spec classes:
+    # - All properties (cat, dims, units, min, max, etc.) are inherited from respective specs
+
+    def clear(self) -> None:
+        """*clear()* Reset all attributes to default values.
+
+        Resets all variable properties to their initial state by calling
+        clear() on all composed perspective classes.
+        """
+        # Call clear on all parent classes
+        ConceptualSpecs.clear(self)
+        SymbolicSpecs.clear(self)
+        NumericalSpecs.clear(self)
+        StatisticalSpecs.clear(self)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """*to_dict()* Convert variable to dictionary representation.
+
+        Returns:
+            Dict[str, Any]: Dictionary representation of variable.
+        """
+        result = {}
+
+        # Get all dataclass fields
+        for f in fields(self):
+            attr_name = f.name
+            attr_value = getattr(self, attr_name)
+
+            # Skip numpy arrays (not JSON serializable without special handling)
+            if isinstance(attr_value, np.ndarray):
+                # Convert to list for JSON compatibility
+                attr_value = attr_value.tolist()
+
+            # Skip callables (can't be serialized)
+            if callable(attr_value) and attr_name == "_dist_func":
+                continue
+
+            # Remove leading underscore from private attributes
+            if attr_name.startswith("_"):
+                clean_name = attr_name[1:]  # Remove first character
+            else:
+                clean_name = attr_name
+
+            result[clean_name] = attr_value
+
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Variable:
+        """*from_dict()* Create variable from dictionary representation.
+
+        Args:
+            data (Dict[str, Any]): Dictionary representation of variable.
+
+        Returns:
+            Variable: New variable instance.
+        """
+        # Get all valid field names from the dataclass
+        field_names = {f.name for f in fields(cls)}
+
+        # Map keys without underscores to keys with underscores
+        mapped_data = {}
+
+        for key, value in data.items():
+            # Try the key as-is first (handles both _idx and name)
+            if key in field_names:
+                mapped_data[key] = value
+            # Try adding underscore prefix (handles idx -> _idx)
+            elif f"_{key}" in field_names:
+                mapped_data[f"_{key}"] = value
+            # Try removing underscore prefix (handles _name -> name if needed)
+            elif key.startswith("_") and key[1:] in field_names:
+                mapped_data[key[1:]] = value
+            else:
+                # Use as-is for unknown keys (will be validated by dataclass)
+                mapped_data[key] = value
+
+        # Convert lists back to numpy arrays for range attributes
+        for range_key in ["std_range", "_std_range"]:
+            if range_key in mapped_data and isinstance(mapped_data[range_key], list):
+                mapped_data[range_key] = np.array(mapped_data[range_key])
+
+        return cls(**mapped_data)

pydasa/elements/specs/__init__.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+"""
+Variable specifications module.
+
+Four compositional perspectives for variable representation:
+- ConceptualSpecs: Identity and classification
+- SymbolicSpecs: Mathematical notation and dimensions
+- NumericalSpecs: Computational values and ranges
+- StatisticalSpecs: Probabilistic distributions
+"""
+
+from .conceptual import ConceptualSpecs
+from .symbolic import SymbolicSpecs
+from .numerical import NumericalSpecs
+from .statistical import StatisticalSpecs
+
+__all__ = [
+    'ConceptualSpecs',
+    'SymbolicSpecs',
+    'NumericalSpecs',
+    'StatisticalSpecs',
+]

pydasa/elements/specs/conceptual.py

@@ -0,0 +1,161 @@
+# -*- coding: utf-8 -*-
+"""
+Module conceptual.py
+===========================================
+
+Conceptual perspective for variable representation.
+
+This module defines the ConceptualSpecs class representing the abstract
+identity and classification of a variable.
+
+Classes:
+    **ConceptualSpecs**: Conceptual 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
+from typing import Optional, List
+
+# custom modules
+from pydasa.core.basic import Foundation
+from pydasa.dimensional.vaschy import Schema
+from pydasa.core.setup import Frameworks
+from pydasa.core.setup import VarCardinality
+from pydasa.core.setup import PYDASA_CFG
+from pydasa.validations.decorators import validate_choices
+
+
+@dataclass
+class ConceptualSpecs(Foundation):
+    """Conceptual perspective: variable identity and classification.
+
+    Answers the fundamental question: "What IS this variable?". This perspective focuses on:
+        - What category does it belong to? (INPUT, OUTPUT, CONTROL)
+        - Which framework is it part of? (PHYSICAL, COMPUTATION, SOFTWARE, CUSTOM)
+        - Is it relevant for the current analysis?
+        - What dimensional framework does it use?
+
+    Attributes:
+        # From Foundation
+            _name (str): User-friendly name of the variable.
+            description (str): Brief summary of the variable.
+            _idx (int): Index/precedence in the dimensional matrix.
+            _sym (str): Symbol representation (LaTeX or alphanumeric).
+            _alias (str): Python-compatible alias for use in code.
+            _fwk (str): Frameworks context (PHYSICAL, COMPUTATION, SOFTWARE, CUSTOM).
+        # From ConceptualSpecs
+            _schema (Optional[Schema]): Reference to the dimensional framework schema.
+            _cat (str): Category of the variable (INPUT, OUTPUT, CONTROL).
+            relevant (bool): Flag indicating if variable is relevant for analysis.
+    """
+
+    # Private attributes
+    # :attr: _schema
+    _schema: Optional[Schema] = None
+    """Reference to the dimensional framework schema."""
+
+    # Category attribute (INPUT, OUT, CTRL)
+    # :attr: _cat
+    _cat: str = VarCardinality.IN.value
+    """Category of the variable (INPUT, OUT, CTRL)."""
+
+    # Flags
+    # :attr: relevant
+    relevant: bool = False
+    """Flag indicating if variable is relevant for analysis."""
+
+    def __post_init__(self) -> None:
+        """*__post_init__()* Initializes the conceptual properties.
+
+        Sets up the schema reference based on framework if not explicitly provided.
+
+        Raises:
+            ValueError: If framework configuration is invalid.
+        """
+        # Initialize from base class
+        super().__post_init__()
+
+        # If no schema provided, create default or use global
+        if self._schema is None and self._fwk != Frameworks.CUSTOM.value:
+            self._schema = Schema(_fwk=self._fwk)
+
+    def _validate_in_list(self, value: str, prec_lt: List[str]) -> bool:
+        """*_validate_in_list()* Validates if a value exists in a list of allowed values.
+
+        Args:
+            value (str): Value to validate.
+            prec_lt (List[str]): List of allowed values.
+
+        Returns:
+            bool: True if the value is in the list, False otherwise.
+        """
+        if value in [None, ""]:
+            return False
+        return value in prec_lt
+
+    # Property getters and setters
+    # Identification and Classification
+
+    @property
+    def cat(self) -> str:
+        """*cat* Get the category of the variable.
+
+        Returns:
+            str: Category (INPUT, OUT, CTRL).
+        """
+        return self._cat
+
+    @cat.setter
+    @validate_choices(PYDASA_CFG.parameter_cardinality)
+    def cat(self, val: str) -> None:
+        """*cat* Set the category of the variable.
+
+        Args:
+            val (str): Category (INPUT, OUT, CTRL).
+
+        Raises:
+            ValueError: If category is invalid.
+        """
+        # if val.upper() not in PYDASA_CFG.parameter_cardinality:
+        #     _msg = f"Invalid category: {val}. "
+        #     _msg += "Category must be one of the following: "
+        #     _msg += f"{', '.join(_param_keys)}."
+        #     raise ValueError(_msg)
+        self._cat = val.upper()
+
+    @property
+    def schema(self) -> Optional[Schema]:
+        """*schema* Get the dimensional schema reference.
+
+        Returns:
+            Optional[Schema]: The dimensional framework schema.
+        """
+        return self._schema
+
+    @schema.setter
+    def schema(self, val: Optional[Schema]) -> None:
+        """*schema* Set the dimensional schema reference.
+
+        Args:
+            val (Optional[Schema]): The dimensional framework schema.
+        """
+        self._schema = val
+
+    def clear(self) -> None:
+        """*clear()* Reset conceptual attributes to default values.
+
+        Resets category, schema, and relevance flag.
+        """
+        # Reset base class attributes
+        super().clear()
+
+        # Reset variable-specific attributes
+        self._cat = VarCardinality.IN.value
+        self._schema = None
+        self.relevant = False