src.pydasa.dimensional.model ============================ .. py:module:: src.pydasa.dimensional.model .. autoapi-nested-parse:: Module model.py ============================================ Module for **Matrix** to perform Dimensional Analysis in *PyDASA*. This module provides the Matrix class which implements matrix-based dimensional analysis following the Buckingham Pi theorem methodology. Classes: **Matrix**: Represents a dimensional matrix for performing dimensional analysis, including methods for matrix creation, solving, and coefficient generation. *IMPORTANT:* Based on the theory from: H. Gorter, *Dimensionalanalyse: Eine Theoririe der physikalischen Dimensionen mit Anwendungen* Attributes ---------- .. autoapisummary:: src.pydasa.dimensional.model.MAX_OUT src.pydasa.dimensional.model.MAX_IN Classes ------- .. autoapisummary:: src.pydasa.dimensional.model.Matrix Module Contents --------------- .. py:data:: MAX_OUT :type: int :value: 1 Maximum number of output variables allowed. .. py:data:: MAX_IN :type: int :value: 10 Maximum number of input variables allowed. .. py:class:: Matrix Bases: :py:obj:`pydasa.core.basic.Foundation` **Matrix** for Dimensional Analysis in *PyDASA*. Manages the dimensional matrix for performing analysis using the Buckingham Pi theorem methodology. :param Foundation: Foundation class for validation of symbols and frameworks. .. attribute:: # Core Identification .. attribute:: name User-friendly name of the dimensional model. :type: str .. attribute:: description Brief summary of the dimensional model. :type: str .. attribute:: _idx Index/precedence of the dimensional model. :type: int .. attribute:: _sym Symbol representation (LaTeX or alphanumeric). :type: str .. attribute:: _alias Python-compatible alias for use in code. :type: str .. attribute:: _fwk Frameworks context (PHYSICAL, COMPUTATION, SOFTWARE, CUSTOM). :type: str .. attribute:: # FDU Schema Management .. attribute:: _schema Dimensional domain managing FDUs. :type: Schema .. attribute:: working_fdus Active FDUs used in current analysis. :type: List[str] .. attribute:: # Variable Management .. attribute:: _variables All variables in the model. :type: Dict[str, Variable] .. attribute:: _relevance_lt Relevant variables for analysis. :type: Dict[str, Variable] .. attribute:: _output Output variable for analysis. :type: Optional[Variable] .. attribute:: # Variable Statistics .. attribute:: _n_var Total number of variables. :type: int .. attribute:: _n_relevant Number of relevant variables. :type: int .. attribute:: _n_in Number of input variables. :type: int .. attribute:: _n_out Number of output variables. :type: int .. attribute:: _n_ctrl Number of control variables. :type: int .. attribute:: # Matrix Representations .. attribute:: _dim_mtx Dimensional matrix (FDUs × Variables). :type: Optional[NDArray[np.float64]] .. attribute:: _dim_mtx_trans Transposed dimensional matrix. :type: Optional[NDArray[np.float64]] .. attribute:: _sym_mtx SymPy matrix for symbolic computation. :type: Optional[sp.Matrix] .. attribute:: _rref_mtx Row-Reduced Echelon Form matrix. :type: Optional[NDArray[np.float64]] .. attribute:: # Analysis Results .. attribute:: _pivot_cols Pivot columns in the RREF matrix. :type: List[int] .. attribute:: _coefficients Dimensionless Pi coefficients. :type: Dict[str, Coefficient] .. py:attribute:: description :type: str :value: '' Brief summary of the dimensional matrix and its purpose. .. py:attribute:: working_fdus :type: List[str] :value: [] List of active FDU symbols used in the current analysis. .. py:method:: __post_init__() *__post_init__()* Initialize the dimensional matrix. Validates variables, sets up the framework, identifies relevant variables, and prepares for dimensional analysis. .. py:method:: create_matrix() *create_matrix()* Builds the dimensional matrix. Creates the dimensional matrix by arranging variable dimensions as columns. Each row represents an FDU, each column a variable. :raises ValueError: If no relevant variables exist. :raises ValueError: If variables have invalid or missing dimensional columns. .. py:method:: solve_matrix() *solve_matrix()* Solves the dimensional matrix. Computes the Row-Reduced Echelon Form (RREF) of the matrix, identifies pivot columns, and generates dimensionless coefficients from the nullspace. :raises ValueError: If matrix hasn't been created yet. .. py:method:: derive_coefficient(expr, symbol = '', name = '', description = '', idx = -1) *derive_coefficient()* Creates a new coefficient derived from existing ones. Combines existing dimensionless coefficients using a mathematical expression. The new coefficient is marked as "DERIVED". :param expr: Mathematical expression using existing coefficients and numeric constants. Supports: *, /, ** (power), +, -, and numeric constants .. rubric:: Examples - "\Pi_{0} * \Pi_{1}" (multiplication: adds exponents) - "\Pi_{0} / \Pi_{1}" (division: subtracts exponents) - "\Pi_{0}**(-1)" (power: multiplies exponents) - "\Pi_{0} + \Pi_{1}" (addition: result is dimensionless) - "\Pi_{0} - \Pi_{1}" (subtraction: result is dimensionless) - "2 * \Pi_{0}" (constant multiplication: constant is dimensionless) - "0.5 * \Pi_{1} * \Pi_{0}**(-1)" (mixed expression with constant) - "1/\Pi_{2}" (invert the coefficient - changes both exponents and values) :type expr: str :param symbol: Symbol representation (LaTeX or alphanumeric) for the derived coefficient. Default to "" to keep the original (e.g., Pi_{0}). :type symbol: str :param name: Name for the derived coefficient. Defaults to "Derived-Pi-{idx}". :type name: str, optional :param description: Description of the coefficient. Defaults to "Derived from: {expr}". :type description: str, optional :param idx: Index for the coefficient. If -1, the next available index is used. :type idx: int, optional :returns: The newly created derived coefficient. :rtype: Coefficient :raises ValueError: If expression is invalid or references non-existent coefficients. :raises ValueError: If expression creates dimensionally inconsistent result. Example::: >>> # Create Reynolds number as ratio of two Pi groups >>> Re = model.derive_coefficient( ... expr="\Pi_{0} / \Pi_{1}", ... name="Reynolds Number", ... description="Ratio of inertial to viscous forces" ... ) >>> # Create a coefficient with constant multiplier >>> scaled = model.derive_coefficient( ... expr="2 * \Pi_{0}", ... name="Scaled Coefficient", ... description="Twice the original coefficient" ... ) .. py:method:: analyze() *analyze()* Performs complete dimensional analysis Executes the full analysis workflow: 1. Prepare analysis (validate variables, identify output) 2. Create dimensional matrix 3. Solve matrix (compute RREF and nullspace) 4. Generate dimensionless coefficients This is the main entry point for dimensional analysis. .. py:method:: clear() *clear()* Resets all dimensional matrix and analysis data. Clears all computed results while preserving the framework (_schema). Resets all attributes to the same state as __post_init__ leaves them. NOTE: Numpy arrays don't have .clear() method, so we reassign. Lists have .clear() method. .. py:property:: variables :type: Dict[str, pydasa.elements.parameter.Variable] *variables* Get the dictionary of variables. :returns: Copy of variables dictionary. :rtype: Dict[str, Variable] .. py:property:: schema :type: pydasa.dimensional.vaschy.Schema *schema* Get the dimensional schema. :returns: Current dimensional schema. :rtype: Schema .. py:property:: relevance_lt :type: Dict[str, pydasa.elements.parameter.Variable] *relevance_lt* Get dictionary of relevant variables. :returns: Dictionary of relevant variables. :rtype: Dict[str, Variable] .. py:property:: idx :type: int *idx* Get the index/precedence value. :returns: Index value. :rtype: int .. py:property:: sym :type: str *sym* Get the symbol. :returns: Symbol value. :rtype: str .. py:property:: alias :type: str *alias* Get the Python variable alias. :returns: Python variable name alias. :rtype: str .. py:property:: fwk :type: str *fwk* Get the framework. :returns: Framework value. :rtype: str .. py:property:: coefficients :type: Dict[str, pydasa.dimensional.buckingham.Coefficient] *coefficients* Get dictionary of dimensionless coefficients. :returns: Dictionary of dimensionless coefficients. :rtype: Dict[str, Coefficient] .. py:property:: output :type: Optional[pydasa.elements.parameter.Variable] *output* Get the output variable. :returns: The output variable, or None if not set. :rtype: Optional[Variable] .. py:property:: dim_mtx :type: Optional[numpy.typing.NDArray[numpy.float64]] *dim_mtx* Get the dimensional matrix. :returns: Dimensional matrix, or None. :rtype: Optional[NDArray[np.float64]] .. py:property:: rref_mtx :type: Optional[numpy.typing.NDArray[numpy.float64]] *rref_mtx* Get the RREF matrix. :returns: RREF matrix, or None. :rtype: Optional[NDArray[np.float64]] .. py:property:: pivot_cols :type: List[int] *pivot_cols* Get pivot column indices. :returns: Pivot column list. :rtype: List[int] .. py:method:: to_dict() *to_dict()* Convert model to dictionary representation. :returns: Dictionary representation of the model. :rtype: Dict[str, Any] .. py:method:: from_dict(data) :classmethod: *from_dict()* Create model from dictionary representation. :param data: Dictionary representation of the model. :type data: Dict[str, Any] :returns: New Matrix instance. :rtype: Matrix