src.pydasa.dimensional.model#

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:

  1. Gorter, Dimensionalanalyse: Eine Theoririe der physikalischen Dimensionen mit Anwendungen

Attributes#

MAX_OUT

Maximum number of output variables allowed.

MAX_IN

Maximum number of input variables allowed.

Classes#

Matrix

Matrix for Dimensional Analysis in PyDASA. Manages the dimensional matrix for performing analysis using the Buckingham Pi theorem methodology.

Module Contents#

src.pydasa.dimensional.model.MAX_OUT: int = 1#

Maximum number of output variables allowed.

src.pydasa.dimensional.model.MAX_IN: int = 10#

Maximum number of input variables allowed.

class src.pydasa.dimensional.model.Matrix#

Bases: pydasa.core.basic.Foundation

Matrix for Dimensional Analysis in PyDASA. Manages the dimensional matrix for performing analysis using the Buckingham Pi theorem methodology.

Parameters:

Foundation – Foundation class for validation of symbols and frameworks.

# Core Identification
name#

User-friendly name of the dimensional model.

Type:

str

Return type:

str

description#

Brief summary of the dimensional model.

Type:

str

_idx#

Index/precedence of the dimensional model.

Type:

int

_sym#

Symbol representation (LaTeX or alphanumeric).

Type:

str

_alias#

Python-compatible alias for use in code.

Type:

str

_fwk#

Frameworks context (PHYSICAL, COMPUTATION, SOFTWARE, CUSTOM).

Type:

str

# FDU Schema Management
_schema#

Dimensional domain managing FDUs.

Type:

Schema

working_fdus#

Active FDUs used in current analysis.

Type:

List[str]

# Variable Management
_variables#

All variables in the model.

Type:

Dict[str, Variable]

_relevance_lt#

Relevant variables for analysis.

Type:

Dict[str, Variable]

_output#

Output variable for analysis.

Type:

Optional[Variable]

# Variable Statistics
_n_var#

Total number of variables.

Type:

int

_n_relevant#

Number of relevant variables.

Type:

int

_n_in#

Number of input variables.

Type:

int

_n_out#

Number of output variables.

Type:

int

_n_ctrl#

Number of control variables.

Type:

int

# Matrix Representations
_dim_mtx#

Dimensional matrix (FDUs × Variables).

Type:

Optional[NDArray[np.float64]]

_dim_mtx_trans#

Transposed dimensional matrix.

Type:

Optional[NDArray[np.float64]]

_sym_mtx#

SymPy matrix for symbolic computation.

Type:

Optional[sp.Matrix]

_rref_mtx#

Row-Reduced Echelon Form matrix.

Type:

Optional[NDArray[np.float64]]

# Analysis Results
_pivot_cols#

Pivot columns in the RREF matrix.

Type:

List[int]

_coefficients#

Dimensionless Pi coefficients.

Type:

Dict[str, Coefficient]

description: str = ''#

Brief summary of the dimensional matrix and its purpose.

working_fdus: List[str] = []#

List of active FDU symbols used in the current analysis.

__post_init__()#

__post_init__() Initialize the dimensional matrix.

Validates variables, sets up the framework, identifies relevant variables, and prepares for dimensional analysis.

Return type:

None

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.

  • ValueError – If variables have invalid or missing dimensional columns.

Return type:

None

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.

Return type:

None

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”.

Parameters:

  • expr (str) –

    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)

  • symbol (str) – Symbol representation (LaTeX or alphanumeric) for the derived coefficient. Default to “” to keep the original (e.g., Pi_{0}).

  • name (str, optional) – Name for the derived coefficient. Defaults to “Derived-Pi-{idx}”.

  • description (str, optional) – Description of the coefficient. Defaults to “Derived from: {expr}”.

  • idx (int, optional) – Index for the coefficient. If -1, the next available index is used.

Returns:

The newly created derived coefficient.

Return type:

Coefficient

Raises:

  • ValueError – If expression is invalid or references non-existent coefficients.

  • 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"
... )
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.

Return type:

None

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.

Return type:

None

property variables: Dict[str, pydasa.elements.parameter.Variable]#

variables Get the dictionary of variables.

Returns:

Copy of variables dictionary.

Return type:

Dict[str, Variable]

property schema: pydasa.dimensional.vaschy.Schema#

schema Get the dimensional schema.

Returns:

Current dimensional schema.

Return type:

Schema

property relevance_lt: Dict[str, pydasa.elements.parameter.Variable]#

relevance_lt Get dictionary of relevant variables.

Returns:

Dictionary of relevant variables.

Return type:

Dict[str, Variable]

property idx: int#

idx Get the index/precedence value.

Returns:

Index value.

Return type:

int

property sym: str#

sym Get the symbol.

Returns:

Symbol value.

Return type:

str

property alias: str#

alias Get the Python variable alias.

Returns:

Python variable name alias.

Return type:

str

property fwk: str#

fwk Get the framework.

Returns:

Framework value.

Return type:

str

property coefficients: Dict[str, pydasa.dimensional.buckingham.Coefficient]#

coefficients Get dictionary of dimensionless coefficients.

Returns:

Dictionary of dimensionless coefficients.

Return type:

Dict[str, Coefficient]

property output: pydasa.elements.parameter.Variable | None#

output Get the output variable.

Returns:

The output variable, or None if not set.

Return type:

Optional[Variable]

property dim_mtx: numpy.typing.NDArray[numpy.float64] | None#

dim_mtx Get the dimensional matrix.

Returns:

Dimensional matrix, or None.

Return type:

Optional[NDArray[np.float64]]

property rref_mtx: numpy.typing.NDArray[numpy.float64] | None#

rref_mtx Get the RREF matrix.

Returns:

RREF matrix, or None.

Return type:

Optional[NDArray[np.float64]]

property pivot_cols: List[int]#

pivot_cols Get pivot column indices.

Returns:

Pivot column list.

Return type:

List[int]

to_dict()#

to_dict() Convert model to dictionary representation.

Returns:

Dictionary representation of the model.

Return type:

Dict[str, Any]

classmethod from_dict(data)#

from_dict() Create model from dictionary representation.

Parameters:

data (Dict[str, Any]) – Dictionary representation of the model.

Returns:

New Matrix instance.

Return type:

Matrix