src.pydasa.analysis.simulation

Module for Monte Carlo Simulation execution and analysis in PyDASA.

This module provides the MonteCarlo class for performing Monte Carlo simulations on dimensionless coefficients derived from dimensional analysis.

Classes:

MonteCarlo: Performs Monte Carlo simulations on dimensionless coefficients.

IMPORTANT: Based on the theory from:

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

Classes

MonteCarlo

MonteCarlo class for stochastic analysis in PyDASA.

Module Contents

class src.pydasa.analysis.simulation.MonteCarlo

Bases: pydasa.core.basic.Foundation, pydasa.elements.specs.numerical.BoundsSpecs

MonteCarlo class for stochastic analysis in PyDASA.

Performs Monte Carlo simulations on dimensionless coefficients to analyze the coefficient’s distribution and sensitivity to input parameter variations.

Parameters:

• Foundation – Foundation class for validation of symbols and frameworks.

• BoundsSpecs – Value bounds for statistical properties (mean, median, dev, min, max).

# Core Identification

name

User-friendly name of the Monte Carlo simulation.

Type:

str

Return type:

str

description

Brief summary of the simulation.

Type:

str

_idx

Index/precedence of the simulation.

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

_cat

Category of analysis (SYM, NUM, HYB).

Type:

str

# Coefficient and Expression Management

_coefficient

Coefficient for the simulation.

Type:

Optional[Coefficient]

_pi_expr

LaTeX expression to analyze.

Type:

str

_sym_func

Sympy function of the simulation.

Type:

Callable

_exe_func

Executable function for numerical evaluation.

Type:

Callable

# Variable Management

_variables

Variable symbols in the expression.

Type:

Dict[str, Variable]

_symbols

Python symbols for the variables.

Type:

Dict[str, Any]

_aliases

Variable aliases for use in code.

Type:

Dict[str, Any]

_latex_to_py

Mapping from LaTeX to Python variable names.

Type:

Dict[str, str]

_py_to_latex

Mapping from Python to LaTeX variable names.

Type:

Dict[str, str]

# Simulation Configuration

_experiments

Number of simulation experiments to run. Default is -1.

Type:

int

_distributions

Variable sampling distributions.

Type:

Dict[str, Dict[str, Any]]

_simul_cache

Working sampled values cache.

Type:

Dict[str, NDArray[np.float64]]

# Results and Input data

_data

Input data dictionary mapping variable names to arrays.

Type:

Dict[str, NDArray[np.float64]]

_results

Raw simulation results.

Type:

Optional[np.ndarray]

# Statistics (inherited from BoundsSpecs

_mean, _median, _dev, _min, _max)

_mean

Mean value of simulation results.

Type:

float

_median

Median value of simulation results.

Type:

float

_dev

Standard deviation of simulation results.

Type:

float

_min

Minimum value in simulation results.

Type:

float

_max

Maximum value in simulation results.

Type:

float

_count

Number of valid simulation results (MonteCarlo-specific).

Type:

int

_statistics

Statistical summary.

Type:

Optional[Dict[str, float]]

description: str = ''

Brief summary of the simulation.

__post_init__()

__post_init__() Initializes the Monte Carlo simulation.

Return type:

None

set_coefficient(coef)

set_coefficient() Configure analysis from a coefficient.

Parameters:

coef (Coefficient) – Dimensionless coefficient to analyze.

Raises:

ValueError – If the coefficient doesn’t have a valid expression.

Return type:

None

run(iters=None, mode=SimulationMode.DIST.value)

run() Execute the Monte Carlo simulation.

Parameters:

• iters (int, optional) – Number of iterations to run. If None, uses _experiments.

• mode (str, optional) – Simulation mode. Either ‘DIST’ to sample from distributions, or ‘DATA’ to use pre-existing Variable._data. Defaults to ‘DIST’.

Raises:

ValueError – If simulation is not ready or encounters errors during execution.

Return type:

None

get_confidence_interval(conf=0.95)

get_confidence_interval() Calculate the confidence interval.

Parameters:

conf (float, optional) – Confidence level for the interval. Defaults to 0.95.

Raises:

ValueError – If no results are available or if the confidence level is invalid.

Returns:

Lower and upper bounds of the confidence interval.

Return type:

Tuple[float, float]

extract_results()

extract_results() Extract simulation results.

Returns:

Dictionary containing simulation results.

Return type:

Dict[str, NDArray[np.float64]]

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

variables Get the variables involved in the simulation.

Returns:

Dictionary of variable symbols and Variable objects.

Return type:

Dict[str, Variable]

property coefficient: pydasa.dimensional.buckingham.Coefficient | None

coefficient Get the coefficient associated with the simulation.

Returns:

The associated Coefficient object, or None.

Return type:

Optional[Coefficient]

property results: numpy.typing.NDArray[numpy.float64]

results Raw simulation results.

Returns:

Copy of the simulation results.

Return type:

NDArray[np.float64]

Raises:

ValueError – If no results are available.

property data: Dict[str, numpy.typing.NDArray[numpy.float64]]

data Get the input data dictionary.

Returns:

Copy of input data mapping variable names to arrays.

Return type:

Dict[str, NDArray[np.float64]]

Raises:

ValueError – If no data is available.

property statistics: Dict[str, float | int | None]

statistics Get the statistical analysis of simulation results.

Raises:

ValueError – If no results are available.

Returns:

Dictionary containing statistical properties.

Return type:

Dict[str, Union[float, int, None]]

property experiments: int

experiments Number of simulation experiments.

Returns:

Current number of experiments.

Return type:

int

property distributions: Dict[str, Dict[str, Any]]

distributions Get the variable distributions.

Returns:

Current variable distributions.

Return type:

Dict[str, Dict[str, Any]]

property dependencies: Dict[str, List[str]]

dependencies Get variable dependencies.

Returns:

Dictionary of variable dependencies.

Return type:

Dict[str, List[str]]

property cat: str

mode Get simulation execution category.

Returns:

Current simulation category (DIST or DATA).

Return type:

str

property count: int

count Number of valid simulation results.

Returns:

Result count.

Return type:

int

Raises:

ValueError – If no results are available.

property summary: Dict[str, float | int | None]

summary Get the statistical analysis of simulation results.

Returns:

Dictionary containing statistical properties. It returns NaN values and -1 count if simulation hasn’t run yet.

Return type:

Dict[str, Union[float, int, None]]

clear()

clear() Reset all attributes to default values.

Return type:

None

to_dict()

to_dict() Convert simulation to dictionary representation.

Return type:

Dict[str, Any]

classmethod from_dict(data)

from_dict() Create simulation from dictionary representation.

Parameters:

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

Returns:

New simulation instance.

Return type:

MonteCarlo