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]

_name: str = 'Dimensional Matrix'#

User-friendly name of the dimensional matrix.

description: str = ''#

Brief summary of the dimensional matrix and its purpose.

_idx: int = -1#

Index/precedence of the dimensional model.

_sym: str = ''#

Symbol representation (LaTeX or alphanumeric).

_alias: str = ''#

Python-compatible alias for use in code.

_fwk: str = 'PHYSICAL'#

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

_schema: pydasa.dimensional.vaschy.Schema#

Dimensional domain managing Fundamental Dimensional Units (FDUs).

working_fdus: List[str] = []#

List of active FDU symbols used in the current analysis.

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

Dictionary of all parameters/variables in the model.

Keys are variable symbols (str), values are Variable instances.

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

Dictionary of relevant parameters/variables for dimensional analysis.

Filtered subset of _variables where Variable.relevant == True. Keys are variable symbols (str), values are Variable instances.

NOTE: called ‘relevant list’ by convention.

_output: pydasa.elements.parameter.Variable | None = None#

The single output variable for the dimensional analysis.

Must be a variable with cat == “OUT”.

_n_var: int = 0#

Total number of variables in the model.

_n_relevant: int = 0#

Number of variables marked as relevant for analysis.

_n_in: int = 0#

Number of input variables (cat == “IN” and relevant == True).

_n_out: int = 0#

Number of output variables (cat == “OUT” and relevant == True).

_n_ctrl: int = 0#

Number of control variables (cat == “CTRL” and relevant == True).

_dim_mtx: numpy.typing.NDArray[numpy.float64] | None = None#

Dimensional matrix as NumPy array.

Shape: (n_fdus, n_relevant_vars) Each column represents a variable’s dimensional formula. Each row represents an FDU’s exponent across all variables.

_dim_mtx_trans: numpy.typing.NDArray[numpy.float64] | None = None#

Transposed dimensional matrix.

Shape: (n_relevant_vars, n_fdus) Transpose of _dim_mtx for alternative operations.

_sym_mtx: sympy.Matrix | None#

SymPy Matrix representation for symbolic computation.

Used for RREF calculation and nullspace computation. Equivalent to _dim_mtx but in SymPy format.

_rref_mtx: numpy.typing.NDArray[numpy.float64] | None = None#

Row-Reduced Echelon Form (RREF) of the dimensional matrix.

Result of Gaussian elimination on _sym_mtx. Used to identify pivot columns and compute nullspace.

_nullspace: List[numpy.ndarray | sympy.Matrix] = []#

List of nullspace vectors of the dimensional matrix.

Can be list of arrays or list of sympy vectors

_pivot_cols: List[int] = []#

Indices of pivot columns in the RREF matrix.

Identifies which variables are dependent (pivot) vs. independent (free).

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

Dictionary of dimensionless Pi coefficients.

Keys are coefficient symbols (e.g., “Pi_{0}”), values are Coefficient instances. Generated from the nullspace of the dimensional matrix.

_prepare_analysis()#

_prepare_analysis() Prepare the model for dimensional analysis.

Sets up relevant variables, computes model statistics, identifies the output variable, and extracts working FDUs.

Raises:

ValueError – If variable configuration is invalid.

Return type:

None

_update_variable_stats()#

_update_variable_stats() Update variable statistics.

Computes the number of variables, inputs, outputs, and control variables. Validates the model constraints.

Raises:

ValueError – If model has invalid variable counts.

Return type:

None

_sort_by_category(vars_lt)#

_sort_by_category() Sorts variables by category.

Sorts variables in order: IN -> OUT -> CTRL. Updates variable indices to reflect sorted order.

Parameters:

vars_lt (Dict[str, Variable]) – Dictionary of variables to sort.

Returns:

Sorted dictionary of variables.

Return type:

Dict[str, Variable]

_find_output_variable()#

_find_output_variable() Identifies the output variable.

Finds the first variable with cat == “OUT” in the relevant list.

Return type:

None

_extract_fdus()#

_extract_fdus() Extracts FDUs from relevant variables.

Scans all relevant variables’ dimension strings to find which FDUs are actually used.

Returns:

List of unique FDU symbols used, in precedence order.

Return type:

List[str]

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

_generate_coefficients()#

_generate_coefficients() Generates dimensionless coefficients.

Creates Coefficient objects from each nullspace vector of the dimensional matrix. Each nullspace vector represents a dimensionless group (Pi coefficient).

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