pydasa 0.4.7__py3-none-any.whl

pydasa/context/conversion.py

@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+"""
+Configuration module for...
+
+# TODO: Add description of the module.
+
+*IMPORTANT:* Based on the theory from:
+
+    # H.Gorter, *Dimensionalanalyse: Eine Theoririe der physikalischen Dimensionen mit Anwendungen*
+"""
+# TODO add UnitConverter for one variable/parameter

pydasa/context/system.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""
+Module domain.py
+===========================================
+
+Configuration module for...
+
+# TODO: Add description of the module.
+
+Classes:
+    **UnitManager**: Manages units and their conversions, including validation and error handling.
+
+*IMPORTANT:* Based on the theory from:
+
+    # H.Gorter, *Dimensionalanalyse: Eine Theoririe der physikalischen Dimensionen mit Anwendungen*
+"""
+# TODO add UnitManager class

pydasa/context/units.py

@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+"""
+Module units.py
+===========================================
+
+This module provides the Measurement class for handling physical measurements with units, values, and validation.
+
+Classes:
+    **Measurement**: Represents a physical measurement with a value, unit, and validation logic.
+
+*IMPORTANT:* Based on the theory from:
+
+    # H.Gorter, *Dimensionalanalyse: Eine Theoririe der physikalischen Dimensionen mit Anwendungen*
+"""
+# TODO complete implementation of Measurement class

pydasa/core/__init__.py

@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+"""
+Package data
+===========================================
+
+Data persistence and I/O operations for PyDASA.
+
+This package provides functions for reading and writing data to files,
+handling different data formats, and ensuring compatibility with the
+data structures used in PyDASA.
+"""
+
+from pydasa.core.io import load, save, load_json, save_json
+
+__all__ = ['load', 'save', 'load_json', 'save_json']

pydasa/core/basic.py

@@ -0,0 +1,287 @@
+# -*- coding: utf-8 -*-
+"""
+Module basic.py
+===========================================
+
+This module provides base classes with common validation logic used across FDU, Parameter, and Variable classes to eliminate code duplication.
+
+Classes:
+    **Foundation**: enforces common validation logic.
+    **IdxBasis**: enforces index/precedence validation logic.
+    **SymBasis**: enforces symbol and framework validation logic.
+
+*IMPORTANT:* Based on the theory from:
+
+    # H.Gorter, *Dimensionalanalyse: Eine Theoririe der physikalischen Dimensionen mit Anwendungen*
+"""
+# native python modules
+# forward references + postpone eval type hints
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Optional
+
+# indicate it is an abstract base class
+from abc import ABC
+
+# import global variables
+from pydasa.core.setup import Frameworks
+from pydasa.core.setup import PYDASA_CFG
+from pydasa.validations.patterns import LATEX_RE
+
+# import validation decorators
+from pydasa.validations.decorators import validate_type
+from pydasa.validations.decorators import validate_emptiness
+from pydasa.validations.decorators import validate_choices
+from pydasa.validations.decorators import validate_pattern
+from pydasa.validations.decorators import validate_index
+
+
+@dataclass
+class SymBasis(ABC):
+    """**SymBasis** Foundation class for entities with symbols and framework functionalities.
+
+    Attributes:
+        _sym (str): Symbol representation.
+        _alias (str): Python-compatible alias for use in code.
+        _fwk (str): Frameworks context.
+    """
+
+    # :attr: _sym
+    _sym: str = ""
+    """Symbol representation (LaTeX or alphanumeric)."""
+
+    # :attr: _fwk
+    _fwk: str = Frameworks.PHYSICAL.value
+    """Frameworks context (PHYSICAL, COMPUTATION, SOFTWARE, CUSTOM)."""
+
+    # :attr: _alias
+    _alias: str = ""
+    """Python-compatible alias for symbol, used in executable code. e.g.: `\\rho_{1}` -> `rho_1`."""
+
+    def __post_init__(self) -> None:
+        """*__post_init__()* Post-initialization processing with symbol and framework validation.
+        """
+        # super().__post_init__()
+        # Validate the symbol and framework
+        if not self._sym:
+            self._sym = self._sym.strip()
+        if not self._fwk:
+            self._fwk = self._fwk.strip()
+        if not self._alias:
+            self._alias = self._alias.strip()
+
+    @property
+    def sym(self) -> str:
+        """*sym* Get the symbol.
+
+        Returns:
+            str: Symbol value.
+        """
+        return self._sym
+
+    @sym.setter
+    @validate_type(str)
+    @validate_emptiness()
+    @validate_pattern(LATEX_RE, allow_alnum=True)
+    def sym(self, val: str) -> None:
+        """*sym* Set the symbol with validation.
+
+        Args:
+            val (str): Symbol value.
+
+        Raises:
+            ValueError: If symbol format is invalid.
+        """
+        self._sym = val
+
+    @property
+    def fwk(self) -> str:
+        """*fwk* Get the framework.
+
+        Returns:
+            str: Frameworks value.
+        """
+        return self._fwk
+
+    @fwk.setter
+    @validate_type(str)
+    @validate_choices(PYDASA_CFG.frameworks)
+    def fwk(self, val: str) -> None:
+        """*fwk* Set the framework with validation.
+
+        Args:
+            val (str): Frameworks value.
+
+        Raises:
+            ValueError: If framework is not supported.
+        """
+        self._fwk = val
+
+    @property
+    def alias(self) -> Optional[str]:
+        """*alias* Get the Python variable synonym.
+
+        Returns:
+            Optional[str]: Python variable name. e.g.: `\\rho_{1}` -> `rho_1`.
+        """
+        return self._alias
+
+    @alias.setter
+    @validate_type(str)
+    @validate_emptiness()
+    def alias(self, val: str) -> None:
+        """*alias* Set the Python variable synonym.
+
+        Args:
+            val (str): Python variable name. e.g.: `\\rho_{1}` -> `rho_1`.
+
+        Raises:
+            ValueError: If variable name is empty.
+        """
+        self._alias = val
+
+    def clear(self) -> None:
+        """*clear()* Reset symbol and framework attributes to default values.
+
+        Resets the entity's symbol-related properties to their initial state.
+        """
+        # Reset symbol attributes
+        self._sym = ""
+        self._alias = ""
+        self._fwk = Frameworks.PHYSICAL.value
+
+
+@dataclass
+class IdxBasis(SymBasis):
+    """**IdxBasis** Foundation class for entities with index/precedence functionality.
+
+    Attributes:
+        _idx (int): Index/precedence value
+    """
+
+    # :attr: _idx
+    _idx: int = -1
+    """Unique identifier/index for ordering in dimensional matrix."""
+
+    def __post_init__(self) -> None:
+        """*__post_init__()* Post-initialization processing with symbol and framework validation.
+        """
+        super().__post_init__()
+        if self._idx != -1:
+            self.idx = self._idx
+
+    @property
+    def idx(self) -> int:
+        """*idx* Get the index/precedence value.
+
+        Returns:
+            int: Index value.
+        """
+        return self._idx
+
+    @idx.setter
+    @validate_type(int, allow_none=False)
+    @validate_index()
+    def idx(self, val: int) -> None:
+        """*idx* Set the index/precedence value.
+
+        Args:
+            val (int): Index value (must be non-negative).
+
+        Raises:
+            ValueError: If index is not a non-negative integer.
+        """
+        self._idx = val
+
+    def clear(self) -> None:
+        """*clear()* Reset index and inherited attributes to default values.
+
+        Resets the entity's index and symbol-related properties to their initial state.
+        """
+        # Reset parent class attributes
+        super().clear()
+
+        # Reset index attribute
+        self._idx = -1
+
+
+@dataclass
+class Foundation(IdxBasis):
+    """**Foundation** Foundation class for all dimensional analysis entities.
+
+    Provides common validation logic and attributes shared by FDU, Variable, and Coeffcient classes.
+
+    Attributes:
+        name (str): User-friendly name
+        description (str): Brief summary or description
+    """
+
+    # :attr: _name
+    _name: str = ""
+    """User-friendly name of the entity."""
+
+    # :attr: description
+    description: str = ""
+    """Brief summary or description of the entity."""
+
+    def __post_init__(self) -> None:
+        """*__post_init__()* Post-initialization processing with description capitalization.
+        """
+        if self.description:
+            self.description = self.description.strip()
+
+    @property
+    def name(self) -> str:
+        """*name* Get the name.
+
+        Returns:
+            str: Name value.
+        """
+        return self._name
+
+    @name.setter
+    @validate_type(str, allow_none=False)
+    def name(self, val: str) -> None:
+        """*name* Set the name with validation.
+
+        Args:
+            val (str): Name value.
+
+        Raises:
+            ValueError: If name is not a non-empty string.
+        """
+        self._name = val.strip()
+
+    def clear(self) -> None:
+        """*clear()* Reset all attributes to default values.
+
+        Resets the entity's properties to their initial state.
+        """
+        # Reset parent class attributes
+        super().clear()
+
+        # Reset name and description attributes
+        self.name = ""
+        self.description = ""
+
+    def __str__(self) -> str:
+        """*__str__()* String representation showing all non-private attributes.
+
+        Returns:
+            str: Formatted string representation.
+        """
+        attr_list = []
+        for attr, val in vars(self).items():
+            if attr.startswith("__"):
+                continue
+            attr_name = attr.lstrip("_")
+            attr_list.append(f"{attr_name}={repr(val)}")
+        return f"{self.__class__.__name__}({', '.join(attr_list)})"
+
+    def __repr__(self) -> str:
+        """*__repr__()* Detailed string representation.
+
+        Returns:
+            str: String representation.
+        """
+        return self.__str__()

pydasa/core/cfg/default.json

@@ -0,0 +1,136 @@
+{
+    "frameworks": {
+    "PHYSICAL": {
+        "name": "Physical Framework",
+        "description": "Traditional physical dimensional framework (e.g., Length, Mass, Time).",
+        "fdus": {
+        "L": {
+            "unit": "m",
+            "name": "Length",
+            "description": "Distance between two points in space."
+        },
+        "M": {
+            "unit": "kg",
+            "name": "Mass",
+            "description": "Amount of matter in an object."
+        },
+        "T": {
+            "unit": "s",
+            "name": "Time",
+            "description": "Duration of an event or interval."
+        },
+        "K": {
+            "unit": "K",
+            "name": "Temperature",
+            "description": "Measure of average kinetic energy of particles."
+        },
+        "I": {
+            "unit": "A",
+            "name": "Electric Current",
+            "description": "Flow of electric charge."
+        },
+        "N": {
+            "unit": "mol",
+            "name": "Amount of Substance",
+            "description": "Quantity of entities (e.g., atoms, molecules)."
+        },
+        "C": {
+            "unit": "cd",
+            "name": "Luminous Intensity",
+            "description": "Perceived power of light in a given direction."
+        }
+        }
+    },
+    "COMPUTATION": {
+        "name": "Computation Framework",
+        "description": "Computer science dimensional framework (e.g., Time, Space, Complexity).",
+        "fdus": {
+        "T": {
+            "unit": "s",
+            "name": "Time",
+            "description": "Duration of an event or interval."
+        },
+        "S": {
+            "unit": "bit",
+            "name": "Space",
+            "description": "Physical extent in three dimensions."
+        },
+        "N": {
+            "unit": "op",
+            "name": "Complexity",
+            "description": "Measure of interconnectedness or intricacy in a system."
+        }
+        }
+    },
+    "SOFTWARE": {
+        "name": "Software Framework",
+        "description": "Software architecture dimensional framework (e.g., Time, Data, Connectivity).",
+        "fdus": {
+        "T": {
+            "unit": "s",
+            "name": "Time",
+            "description": "Duration of an event or interval."
+        },
+        "D": {
+            "unit": "bit",
+            "name": "Data",
+            "description": "Information processed by a system."
+        },
+        "E": {
+            "unit": "req",
+            "name": "Effort",
+            "description": "Measure of computational effort/complexity."
+        },
+        "C": {
+            "unit": "node",
+            "name": "Connectivity",
+            "description": "Measure of interconnections between components."
+        },
+        "A": {
+            "unit": "process",
+            "name": "Capacity",
+            "description": "Maximum amount of data that can be stored/processed."
+        }
+        }
+    },
+    "CUSTOM": {
+        "name": "Custom Framework",
+        "description": "User-defined dimensional framework for specific use cases.",
+        "fdus": {}
+    }
+    },
+    "variable_cardinality": {
+    "IN": {
+        "name": "Input Variables",
+        "description": "Variables that influence the system (e.g., known inputs)."
+    },
+    "OUT": {
+        "name": "Output Variables",
+        "description": "Variable that represent the results of the analysis."
+    },
+    "CTRL": {
+        "name": "Control Variables",
+        "description": "Variables used to control or constrain the system (e.g., constants)."
+    }
+    },
+    "coefficient_cardinality": {
+    "COMPUTED": {
+        "name": "Computed Coefficients",
+        "description": "Coefficients directly calculated using the Dimensional Matrix."
+    },
+    "DERIVED": {
+        "name": "Derived Coefficients",
+        "description": "Coefficients obtained by combining or manipulating Computed Coefficients."
+    }
+    },
+    "analytic_modes": {
+    "SYM": {
+        "name": "Symbolic Mode",
+        "description": "Analysis for symbolic processable parameters (e.g., 'z = x + y')."
+    },
+    "NUM": {
+        "name": "Numeric Mode",
+        "description": "Analysis for numeric variable ranges (e.g., 1.0, 2.5)."
+    }
+    }
+}

pydasa/core/constants.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""
+Module constants.py
+===========================================
+
+This module specifies the Fundamental Dimensional Units (FDUs) available by default in *PyDASA*. The default framework are the Physical FDUs.
+
+The three main types of FDUs are:
+    1. Physical FDUs: in `PHY_FDU_PREC_DT` representing the standard physical dimensions.
+    2. Digital FDUs: in `COMPU_FDU_PREC_DT` representing dimensions relevant to computation.
+    3. Software Architecture FDUs: in `SOFT_FDU_PREC_DT` representing dimensions specific to software architecture.
+
+The fourth FDU framework is:
+    4. Custom FDUs: user-defined FDUs that can be specified as needed.
+"""
+# python native modules
+
+# global variables
+
+# Default config folder name + settings
+# :attr: DFLT_CFG_FOLDER
+DFLT_CFG_FOLDER: str = "cfg"
+# :attr: DFLT_CFG_FILE
+DFLT_CFG_FILE: str = "default.json"
+"""
+*PyDASA* default configuration folder and file names.
+"""

pydasa/core/io.py

@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+"""
+Module io.py
+===========================================
+
+Generic I/O operations for PyDASA.
+
+This module provides functions for reading and writing data to files, handling different data formats (JSON, CSV, etc.), and ensuring compatibility with the data structures used in PyDASA.
+
+*IMPORTANT:* based on the implementations proposed by the following authors/books:
+
+    #. Algorithms, 4th Edition, Robert Sedgewick and Kevin Wayne.
+    #. Data Structure and Algorithms in Python, M.T. Goodrich, R. Tamassia, M.H. Goldwasser.
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+# global variable to define supported formats
+READ = "r"
+WRITE = "w"
+PATTERN = "utf-8"
+AVAIL_FMT = [".json"]
+
+
+def load_json(file_path: str | Path) -> dict[str, Any]:
+    """*load_json()* reads a JSON file and returns its content as a dictionary.
+
+    Args:
+        file_path (str | Path): Path to the JSON file.
+
+    Returns:
+        dict[str, Any]: Dictionary with the JSON content.
+    """
+    file_path = Path(file_path)
+    with open(file_path, READ, encoding=PATTERN) as f:
+        return json.load(f)
+
+
+def save_json(data: dict[str, Any],
+              file_path: str | Path,
+              indent: int = 4) -> None:
+    """*save_json()* writes a dictionary to a JSON file.
+
+    Args:
+        data (dict[str, Any]): Dictionary to be saved.
+        file_path (str | Path): Path to the output JSON file.
+        indent (int, optional): Indentation level. Defaults to 4.
+    """
+    file_path = Path(file_path)
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(file_path, WRITE, encoding=PATTERN) as f:
+        json.dump(data, f, indent=indent, ensure_ascii=False)
+
+
+def load(file_path: str | Path) -> dict[str, Any]:
+    """*load()* generic load function - detects format from file extension.
+
+    Args:
+        file_path (str | Path): Input file path.
+
+    Raises:
+        ValueError: If unsupported file format.
+
+    Returns:
+        dict[str, Any]: Loaded data as a dictionary.
+    """
+    file_path = Path(file_path)
+    suffix = file_path.suffix.lower()
+
+    if suffix in AVAIL_FMT:
+        return load_json(file_path)
+    else:
+        _msg = f"Unsupported file format: {suffix}. "
+        _msg += f"Supported: {', '.join(AVAIL_FMT)}"
+        raise ValueError(_msg)
+
+
+def save(data: dict[str, Any],
+         file_path: str | Path, **kwargs) -> None:
+    """*save()* generic save function - detects format from file extension.
+
+    Args:
+        data (dict[str, Any]): Data to be saved.
+        file_path (str | Path): Output file path.
+        **kwargs: Additional keyword arguments for specific save functions.
+
+    Raises:
+        ValueError: If unsupported file format.
+    """
+    file_path = Path(file_path)
+    suffix = file_path.suffix.lower()
+
+    if suffix in AVAIL_FMT:
+        indent = kwargs.get("indent", 4)
+        save_json(data, file_path, indent=indent)
+    else:
+        _msg = f"Unsupported file format: {suffix}. "
+        _msg += f"Supported: {', '.join(AVAIL_FMT)}"
+        raise ValueError(_msg)