src.pydasa.analysis.scenario ============================ .. py:module:: src.pydasa.analysis.scenario .. autoapi-nested-parse:: Module scenario.py =========================================== This module provides the *Sensitivity* class for performing sensitivity analysis on dimensional coefficients derived from dimensional analysis in **PyDASA**. **IMPORTANT** - Based on the theory from H. Görtler, *Dimensionalanalyse: Eine Theoririe der physikalischen Dimensionen mit Anwendungen* Classes ------- .. autoapisummary:: src.pydasa.analysis.scenario.Sensitivity Module Contents --------------- .. py:class:: Sensitivity Bases: :py:obj:`pydasa.core.basic.Foundation` Performs sensitivity analysis on dimensional coefficients in **PyDASA** to determine which variables have the most significant impact on the system behavior. Inherits from: - **Foundation**: basic class for validation of symbols and frameworks and allow to use the attributes `name`, `description`, `idx`, `sym`, `alias`, `fwk`, and `cat`. .. attribute:: name User-friendly name of the sensitivity analysis. :type: str .. attribute:: description Brief summary of the sensitivity analysis. :type: str .. attribute:: idx Index/precedence of the sensitivity analysis. :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 .. py:attribute:: _cat :type: str :value: 'SYM' Category of the sensitivity analysis (SYM, NUM). .. py:attribute:: _pi_expr :type: Optional[str] :value: None LaTeX expression to analyze. .. py:attribute:: _sym_func :type: Optional[sympy.Expr] :value: None Sympy expression of the sensitivity (symbolic form). .. py:attribute:: _exe_func :type: Optional[Union[Callable, Dict[str, Callable]]] :value: None Executable function(s) for numerical evaluation (compiled from symbolic form). .. py:attribute:: _variables :type: Dict[str, pydasa.elements.parameter.Variable] Variable symbols in the expression. .. py:attribute:: _var_names :type: List[str] :value: [] List of variable names extracted from the expression (ordered). .. py:attribute:: _schema :type: pydasa.dimensional.vaschy.Schema Dimensional framework schema for FDU management. .. py:attribute:: _coefficient :type: Optional[pydasa.dimensional.buckingham.Coefficient] :value: None Specifications of the dimensionless coefficient to analyse. .. py:attribute:: _symbols :type: Dict[sympy.Symbol, sympy.Symbol] Python symbols for the variables. .. py:attribute:: _aliases :type: Dict[str, sympy.Symbol] Variable aliases for use in code. .. py:attribute:: _latex_to_py :type: Dict[str, str] Mapping from LaTeX symbols to Python-compatible names. .. py:attribute:: _py_to_latex :type: Dict[str, str] Mapping from Python-compatible names to LaTeX symbols. .. py:attribute:: _var_bounds :type: List[List[float]] :value: [] Min/max bounds for each variable. .. py:attribute:: _var_values :type: Dict[str, float] Values for symbolic analysis. .. py:attribute:: _var_domains :type: Optional[numpy.ndarray] :value: None Sample domain (inputs) for numerical analysis. .. py:attribute:: _var_ranges :type: Optional[numpy.ndarray] :value: None Sample value range (results) for numerical analysis. .. py:attribute:: _experiments :type: int :value: -1 Number of experiments/samples for analysis. .. py:attribute:: _results :type: Dict[str, Any] Analysis results. .. py:method:: _validate_sym_expr(val) Confirm that the input symbolic expression is a `SymPy` expression. :param val: Possible expression/value to validate. :type val: Any :raises ValueError: If value is not a valid `SymPy` expression. .. py:method:: _validate_exec_func(val) Confirm executable function is type `Callable` or `dict` of `Callable`. :param val: Possible executable function/value to validate. :type val: Any :raises ValueError: If value is not a callable or dict of callables. .. py:method:: _validate_analysis_ready() Confirm if the sensitivity analysis is ready to be performed. :raises ValueError: If the variables are missing. :raises ValueError: If the python-compatible variables are missing. :raises ValueError: If the symbolic expression is missing. .. py:method:: set_coefficient(coef) Configure the sensitivity analysis from a coefficient. :param coef: Dimensionless coefficient to analyze. :type coef: Coefficient :raises ValueError: If the coefficient doesn't have a valid expression. .. py:method:: _parse_expression(expr) Parse the `LaTeX` expression into a valid `SymPy` function. :param expr: LaTeX expression to parse. :type expr: str :raises ValueError: If the expression cannot be parsed. :raises TypeError: If parsed result is not a valid SymPy expression. .. py:method:: analyze_symbolically(vals) Perform the symbolic sensitivity analysis for the coefficient. :param vals: Dictionary mapping variable names to values. :type vals: Dict[str, float] :returns: Sensitivity results for each variable. :rtype: Dict[str, float] .. py:method:: analyze_numerically(vals, bounds, iters = -1) Perform the numerical sensitivity analysis for the coefficient. :param vals: List of variable names to analyze. :type vals: List[str] :param bounds: Bounds for each variable [min, max]. :type bounds: List[List[float]] :param iters: Number of iterations to use. Defaults to -1. :type iters: int, optional :returns: Detailed sensitivity analysis results. :rtype: Dict[str, Any] .. py:property:: cat :type: str Get the analysis category. :returns: Category (SYM, NUM). :rtype: str .. py:property:: pi_expr :type: Optional[str] Get the coefficient expression to analyze. :returns: LaTeX expression. :rtype: Optional[str] .. py:property:: sym_func :type: Optional[sympy.Expr] Get the symbolic expression. :returns: SymPy symbolic expression. :rtype: Optional[sp.Expr] .. py:property:: exe_func :type: Optional[Union[Callable, Dict[str, Callable]]] Get the executable function. :returns: Executable function for numerical evaluation. :rtype: Optional[Union[Callable, Dict[str, Callable]]] .. py:property:: variables :type: Dict[str, pydasa.elements.parameter.Variable] Get the coefficient's variable dictionary. :returns: Variables dictionary. :rtype: Dict[str, Variable] .. py:property:: schema :type: pydasa.dimensional.vaschy.Schema Get the dimensional schema. :returns: Current dimensional schema. :rtype: Schema .. py:property:: symbols :type: Dict[sympy.Symbol, sympy.Symbol] Get the Python symbols for the variables. :returns: Dictionary mapping variable names to sympy symbols. :rtype: Dict[sp.Symbol, sp.Symbol] .. py:property:: aliases :type: Dict[str, sympy.Symbol] Get the Python aliases for the variables. :returns: Python-compatible variable names. :rtype: Dict[str, sp.Symbol] .. py:property:: var_names :type: List[str] Get the list of variable names extracted from the expression. :returns: Ordered list of variable names. :rtype: List[str] .. py:property:: coefficient :type: Optional[pydasa.dimensional.buckingham.Coefficient] Get the dimensionless coefficient specification. :returns: Coefficient specification. :rtype: Optional[Coefficient] .. py:property:: latex_to_py :type: Dict[str, str] Get the mapping from LaTeX symbols to Python compatible names. :returns: LaTeX to Python symbol mapping. :rtype: Dict[str, str] .. py:property:: py_to_latex :type: Dict[str, str] Get the mapping from Python compatible names to LaTeX symbols. :returns: Python to LaTeX symbol mapping. :rtype: Dict[str, str] .. py:property:: var_bounds :type: List[List[float]] Get the min/max bounds for each variable. :returns: Bounds for each variable. :rtype: List[List[float]] .. py:property:: var_values :type: Dict[str, float] Get the values for symbolic analysis. :returns: Variable values for symbolic analysis. :rtype: Dict[str, float] .. py:property:: var_domains :type: Optional[numpy.ndarray] Get the sample domain for numerical analysis. :returns: Sample domain (inputs) or None if not computed. :rtype: Optional[np.ndarray] .. py:property:: var_ranges :type: Optional[numpy.ndarray] Get the sample value range for numerical analysis. :returns: Sample value range (results) or None if not computed. :rtype: Optional[np.ndarray] .. py:property:: results :type: Dict[str, Any] Get the analysis results. :returns: Analysis results dictionary. :rtype: Dict[str, Any] .. py:property:: experiments :type: int Get the number of experiments for analysis. :returns: Number of experiments. :rtype: int .. py:method:: clear() Reset all attributes to default values. Resets all sensitivity analysis properties to their initial state. .. py:method:: to_dict() Convert the sensitivity analysis into a valid Python dictionary representation. :returns: Dictionary representation of sensitivity analysis. :rtype: Dict[str, Any] .. py:method:: from_dict(data) :classmethod: Creates a sensitivity analysis instance from dictionary representation. :param data: Dictionary representation of sensitivity analysis. :type data: Dict[str, Any] :returns: New sensitivity analysis instance. :rtype: Sensitivity