src.pydasa.workflows.practical ============================== .. py:module:: src.pydasa.workflows.practical .. autoapi-nested-parse:: Module practical.py =========================================== Module for **MonteCarloSimulation** to manage the Monte Carlo experiments in *PyDASA*. This module provides classes for managing Monte Carlo simulations of the dimensionless coefficients. Classes: **MonteCarloSimulation**: Manages Monte Carlo simulation runs, including configuration and execution of the experiments. *IMPORTANT:* Based on the theory from: # H.Gorter, *Dimensionalanalyse: Eine Theoririe der physikalischen Dimensionen mit Anwendungen* Classes ------- .. autoapisummary:: src.pydasa.workflows.practical.MonteCarloSimulation Module Contents --------------- .. py:class:: MonteCarloSimulation Bases: :py:obj:`pydasa.core.basic.Foundation`, :py:obj:`pydasa.workflows.basic.WorkflowBase` **MonteCarloSimulation** class for managing Monte Carlo simulations in *PyDASA*. Manages the creation, configuration, and execution of Monte Carlo simulations of dimensionless coefficients. :param Foundation: Inherits common validation logic. :type Foundation: Foundation :param WorkflowBase: Inherits workflow basic functionalities. :type WorkflowBase: WorkflowBase .. attribute:: # From Foundation _name (str): User-friendly name of the Monte Carlo simulation handler. description (str): Brief summary of the Monte Carlo simulation handler. _idx (int): Index/precedence of the simulation handler. _sym (str): Symbol representation (LaTeX or alphanumeric). _alias (str): Python-compatible alias for use in code. _fwk (str): Frameworks context (PHYSICAL, COMPUTATION, SOFTWARE, CUSTOM). :type: Identification and Classification .. attribute:: # From WorkflowBase _variables (Dict[str, Variable]): All available parameters/variables in the model (*Variable*). Accepts Variable instances or dicts. _schema (Optional[Schema]): Dimensional framework schema for the workflow. After __post_init__, this will always be a Schema instance (inherited but not actively used in MonteCarloSimulation). _coefficients (Dict[str, Coefficient]): All available coefficients in the model (*Coefficient*). Accepts Coefficient instances or dicts. _results (Dict[str, Dict[str, Any]]): Consolidated results from Monte Carlo simulations. _is_solved (bool): Flag indicating if the simulation workflow has been completed. :type: Common Workflow Components .. attribute:: # Specific to MonteCarloSimulation _cat (str): Category of simulation run (DIST, DATA). _distributions (Dict[str, Dict[str, Any]]): All distribution functions used in the simulations (specific name, parameters, and function). _experiments (int): Number of simulations to run. Default is -1. _simulations (Dict[str, MonteCarlo]): All Monte Carlo simulations performed for each coefficient. _shared_cache (Dict[str, NDArray[np.float64]]): In-memory cache for simulation data shared between coefficients. .. py:attribute:: _cat :type: str :value: 'DIST' Category of simulation run (DIST, DATA). .. py:attribute:: _distributions :type: Dict[str, Dict[str, Any]] Variable sampling distributions and specifications for simulations (specific name, parameters, and function). .. py:attribute:: _experiments :type: int :value: -1 Number of simulation to run. .. py:attribute:: _shared_cache :type: Dict[str, numpy.typing.NDArray[numpy.float64]] In-memory cache for simulation data between coefficients. .. py:attribute:: _simulations :type: Dict[str, pydasa.analysis.simulation.MonteCarlo] Dictionary of Monte Carlo simulations. .. py:method:: configure_distributions() *configure_distributions()* Configures sampling distributions for all variables. Sets up distribution specifications (type, parameters, functions) for each variable that will be used during Monte Carlo simulation. :raises ValueError: If variables are not defined. :raises ValueError: If distribution specifications are invalid. .. py:method:: configure_simulations() *configure_simulations()* Configures Monte Carlo simulation objects for each coefficient. Creates MonteCarlo instances for each coefficient with appropriate distributions and dependencies. Requires distributions to be configured first. :raises ValueError: If distributions are not configured. :raises ValueError: If coefficients or variables are not defined. .. py:method:: create_simulations() *create_simulations()* Configures distributions and simulations if not already set. This is a convenience method that orchestrates the full configuration process. It calls configure_distributions() and configure_simulations() in sequence. :raises ValueError: If variables or coefficients are not defined. :raises ValueError: If distribution specifications are invalid. .. py:method:: _validate_coefficient_vars(coef, pi_sym) *_validate_coefficient_vars()* Validates and returns coefficient's var_dims. :param coef: The coefficient to validate. :type coef: Coefficient :param pi_sym: The coefficient symbol for error messages. :type pi_sym: str :returns: The validated var_dims dictionary. :rtype: Dict[str, Any] :raises ValueError: If var_dims is None or missing. .. py:method:: _config_distributions() *_config_distributions()* Creates the Monte Carlo distributions for each variable. :raises ValueError: If the distribution specifications are invalid. .. py:method:: _get_distributions(var_keys) *_get_distributions()* Retrieves the distribution specifications for a list of variable keys. :param var_keys: List of variable keys. :type var_keys: List[str] :returns: Dictionary of distribution specifications. :rtype: Dict[str, Dict[str, Any]] :raises ValueError: If required distributions are missing. .. py:method:: _get_dependencies(var_keys) *_get_dependencies()* Retrieves variable dependencies for a list of variable keys. :param var_keys: List of variable keys. :type var_keys: List[str] :returns: Dictionary mapping variable symbols to their dependencies. :rtype: Dict[str, List[str]] .. py:method:: _init_shared_cache() *_init_shared_cache()* Initialize shared cache for all variables. .. py:method:: _config_simulations() *_config_simulations()* Sets up Monte Carlo simulation objects for each coefficient to be analyzed. Creates a MonteCarlo instance for each coefficient with appropriate distributions and dependencies. :raises ValueError: If coefficients or variables are not properly configured. .. py:method:: run(iters = None) *run()* Runs the Monte Carlo simulations. :param iters: Number of iterations (experiments) to run. If None, uses self._experiments value. Defaults to None. :type iters: Optional[int] :raises ValueError: If simulations are not configured. :raises ValueError: If a required simulation is not found. .. py:method:: run_simulation(iters = None) *run_simulation()* Convenience method to configure and run Monte Carlo simulations. This method combines create_simulations() and run() into a single call. It automatically sets up distributions and simulations if needed, then runs the simulation. :param iters: Number of iterations (experiments) to run. If None, uses self._experiments value. Defaults to None. :type iters: Optional[int] Example:: >>> mc_handler = MonteCarloSimulation(...) >>> mc_handler.run_simulation(iters=10000) .. py:method:: get_simulation(name) *get_simulation()* Get a simulation by name. :param name: Name of the simulation. :type name: str :returns: The requested simulation. :rtype: MonteCarlo :raises ValueError: If the simulation doesn't exist. .. py:method:: get_distribution(name) *get_distribution()* Get the distribution by name. :param name: Name of the distribution. :type name: str :returns: The requested distribution. :rtype: Dict[str, Any] :raises ValueError: If the distribution doesn't exist. .. py:method:: get_results(name) *get_results()* Get the results of a simulation by name. :param name: Name of the simulation. :type name: str :returns: The results of the requested simulation. :rtype: Dict[str, Any] :raises ValueError: If the results for the simulation don't exist. .. py:property:: cat :type: str *cat* Get the Monte Carlo Simulation category. :returns: Category (DIST, DATA). :rtype: str .. py:property:: experiments :type: int *experiments* Get the number of experiments. :returns: Number of experiments to run. :rtype: int .. py:property:: simulations :type: Dict[str, pydasa.analysis.simulation.MonteCarlo] *simulations* Get the dictionary of Monte Carlo simulations. :returns: Dictionary of Monte Carlo simulations. :rtype: Dict[str, MonteCarlo] .. py:property:: is_configured :type: bool *is_configured* Check if simulations are configured and ready to run. :returns: True if both distributions and simulations are configured. :rtype: bool .. py:property:: has_results :type: bool *has_results* Check if simulation results are available. :returns: True if simulations have been run and results exist. :rtype: bool .. py:method:: reset() *reset()* Reset simulation state while preserving input configuration. Clears results, solved state, and simulation-specific attributes (simulations, distributions, cache) while keeping variables, schema, and coefficients. .. py:method:: clear() *clear()* Clear all attributes to default values. Resets all simulation properties to their initial state, including variables, coefficients, and results from WorkflowBase. .. py:method:: to_dict() *to_dict()* Convert the handler's state to a dictionary. :returns: Dictionary representation of the handler's state. :rtype: Dict[str, Any] .. py:method:: from_dict(data) :classmethod: *from_dict()* Create a MonteCarloSimulation instance from a dictionary. :param data: Dictionary containing the handler's state. :type data: Dict[str, Any] :returns: New instance of MonteCarloSimulation. :rtype: MonteCarloSimulation