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]]

_name: str = ''#

User-friendly name of the Monte Carlo simulation.

description: str = ''#

Brief summary of the simulation.

_idx: int = -1#

Index/precedence of the simulation.

_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).

_cat: str = 'DIST'#

Category of analysis (DIST, DATA).

_coefficient: pydasa.dimensional.buckingham.Coefficient#

Coefficient for the simulation.

_pi_expr: str | None = None#

LaTeX expression to analyze.

_sym_func: sympy.Expr | sympy.Basic | None = None#

Sympy expression object for the coefficient (Mul, Add, Pow, Symbol, etc.).

_exe_func: Callable[Ellipsis, float | numpy.ndarray] | None = None#

Compiled executable function for evaluation of the coefficient.

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

Dictionary of variables in the expression.

_symbols: Dict[str, sympy.Symbol]#

Map from variable names (strings) to sympy Symbols.

_aliases: Dict[str, sympy.Symbol]#

Map from Variable aliases to sympy Symbols.

_latex_to_py: Dict[str, str]#

Map from LaTeX symbols to Python-compatible names.

_py_to_latex: Dict[str, str]#

Map from Python-compatible names to LaTeX symbols.

_var_symbols: List[str] = []#

List of variable names extracted from expression.

_experiments: int = -1#

Number of simulation iterations to run.

_distributions: Dict[str, Dict[str, Any]]#

Variable sampling distributions and specifications that includes: - ‘dtype’: Distribution type name. - ‘params’: Distribution parameters (mean, std_dev, etc.). - ‘func’: Function for sampling, usually in Lambda format. - ‘depends’: List of variables this variable depends on.

_dependencies: Dict[str, List[str]]#

Variable dependencies for simulations.

_simul_cache: Dict[str, numpy.typing.NDArray[numpy.float64]]#

Working sampled values during each simulation iteration. Memory cache.

_data: Dict[str, numpy.typing.NDArray[numpy.float64]]#

Input data dictionary mapping variable names to their value arrays.

_results: numpy.typing.NDArray[numpy.float64]#

Raw simulation results.

_mean: float | None#

Mean value of simulation results.

_median: float | None#

Median value of simulation results.

_dev: float | None#

Standard deviation of simulation results.

_min: float | None#

Minimum value in simulation results.

_max: float | None#

Maximum value in simulation results.

_count: int = -1#

Number of valid simulation results.

_statistics: Dict[str, float | int | None] | None = None#

Statistical summary of the Monte Carlo simulation results.

_validate_dist(value, field_name)#

_validate_dist() Custom validator to ensure all distributions have callable ‘func’.

Parameters:

  • value (Dict[str, Dict[str, Any]]) – The distributions dictionary to validate.

  • field_name (str) – Name of the field being validated.

Raises:

ValueError – If distributions don’t have callable ‘func’ functions.

Return type:

None

_validate_readiness()#

_validate_readiness() Checks if the simulation can be performed.

Raises:

ValueError – If the simulation is not ready due to missing variables, executable function, or invalid number of iterations.

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

_collect_dataset(vars)#

_collect_dataset() Consolidate dataset from all variables for ‘DATA’ simulation mode.

Parameters:

vars (Dict[str, Variable]) – Dictionary of variables to collect data from.

Returns:

Dictionary mapping variable symbols to their data arrays.

Return type:

Dict[str, NDArray[np.float64]]

Raises:
_generate_dataset(vars)#

_generate_dataset() Generate dataset by sampling from variable distributions for ‘DIST’ mode.

Parameters:

vars (Dict[str, Variable]) – Dictionary of variables to generate samples for.

Returns:

Dictionary mapping variable symbols to sampled arrays.

Return type:

Dict[str, NDArray[np.float64]]

Raises:

ValueError – If sampling fails or encounters errors.

_parse_expression(expr)#

_parse_expression() Parse the LaTeX expression into a sympy function.

Parameters:

expr (str) – LaTeX expression to parse.

Raises:

ValueError – If the expression cannot be parsed.

Return type:

None

_generate_sample(var, memory)#

_generate_sample() Generate a sample for a given variable.

Parameters:

  • var (Variable) – The variable to generate a sample for.

  • memory (Dict[str, float]) – The current iteration values.

Returns:

The generated sample.

Return type:

float

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

run() Execute the Monte Carlo simulation.

Parameters:

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

  • mode (str | SimulationMode, 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

_reset_memory()#

_reset_memory() Reset results and inputs arrays.

Return type:

None

_reset_statistics()#

_reset_statistics() Reset all statistical attributes to default values.

Return type:

None

_calculate_statistics()#

_calculate_statistics() Calculate statistical properties of simulation results.

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]

_validate_cache_locations(var_syms, idx)#

_validate_cache_locations() Check if cache locations are valid for variable(s) at the iteration.

Parameters:

  • var_syms (Union[str, List[str]]) – Variable symbol(s) to check.

  • idx (int) – Iteration index to check.

Returns:

True if all cache locations are valid (including NaN placeholders), False otherwise.

Return type:

bool

_get_cached_value(var_sym, idx)#

_get_cached_value() Retrieve cached value for variable at the iteration.

Parameters:

  • var_sym (str) – Variable symbol.

  • idx (int) – Iteration index.

Returns:

Cached value if valid, None otherwise.

Return type:

Optional[float]

_set_cached_value(var_sym, idx, val)#

_set_cached_value() Store value in cache for variable at the iteration.

Parameters:

  • var_sym (str) – Variable symbol.

  • idx (int) – Iteration index.

  • val (Union[float, Dict]) – Value to cache. It can be a normal number (float) or a memory cache correction (dict).

Raises:

ValueError – If cache location is invalid.

Return type:

None

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

On this page

This Page