simopt.problem ============== .. py:module:: simopt.problem .. autoapi-nested-parse:: Base classes for simulation optimization problems and models. Module Contents --------------- .. py:class:: Objective(stochastic: float, stochastic_gradients: float | collections.abc.Iterable[float] | None = None, deterministic: float = 0.0, deterministic_gradients: float | collections.abc.Iterable[float] | None = None) Represents an objective function value with optional gradients. Combines stochastic and deterministic components of an objective function, along with their respective gradients if available. Initialize an Objective with stochastic and deterministic components. :param stochastic: The stochastic component of the objective value. :param stochastic_gradients: Gradients of the stochastic component. :param deterministic: The deterministic component of the objective value. :param deterministic_gradients: Gradients of the deterministic component. .. py:attribute:: stochastic .. py:attribute:: stochastic_gradients :value: None .. py:attribute:: deterministic :value: 0.0 .. py:attribute:: deterministic_gradients :value: None .. py:method:: value() -> float Return the total objective value (stochastic + deterministic). .. py:method:: grad() -> numpy.ndarray | None Return the combined gradients of both components, or None if unavailable. .. py:class:: StochasticConstraint(stochastic: float, stochastic_gradients: float | collections.abc.Iterable[float] | None = None, deterministic: float = 0.0, deterministic_gradients: float | collections.abc.Iterable[float] | None = None) Represents a stochastic constraint with optional deterministic component. Initialize a StochasticConstraint. :param stochastic: The stochastic component of the constraint. :param stochastic_gradients: Gradients of the stochastic component. :param deterministic: The deterministic component of the constraint. :param deterministic_gradients: Gradients of the deterministic component. .. py:attribute:: stochastic .. py:attribute:: stochastic_gradients :value: None .. py:attribute:: deterministic :value: 0.0 .. py:attribute:: deterministic_gradients :value: None .. py:method:: value() -> float Return the total constraint value (stochastic + deterministic if present). .. py:method:: grad() -> numpy.ndarray | None Return the combined gradients of both components, or None if unavailable. .. py:class:: RepResult(objectives: list[Objective], stochastic_constraints: list[StochasticConstraint] | None = None) Container for results from a single simulation replication. Initialize a RepResult with objectives and optional constraints. :param objectives: List of objective function results from the replication. :param stochastic_constraints: Optional list of stochastic constraint results. .. py:attribute:: objectives .. py:attribute:: stochastic_constraints :value: None .. py:class:: Problem(name: str = '', fixed_factors: dict | None = None, model_fixed_factors: dict | None = None) Bases: :py:obj:`abc.ABC` Base class for simulation-optimization problems. :param name: Problem name. :type name: str :param fixed_factors: User-defined factors that affect the problem setup. :type fixed_factors: dict :param model_fixed_factors: Subset of non-decision factors passed to the model. :type model_fixed_factors: dict Initialize a problem object. :param name: Name of the problem. :type name: str :param fixed_factors: Dictionary of user-specified problem factors. :type fixed_factors: dict | None :param model_fixed_factors: Subset of user-specified non-decision factors passed to the model. :type model_fixed_factors: dict | None .. py:attribute:: class_name_abbr :type: ClassVar[str] Short name of the problem class. .. py:attribute:: class_name :type: ClassVar[str] Long name of the problem class. .. py:attribute:: config_class :type: ClassVar[type[pydantic.BaseModel]] Configuration class for problem. .. py:attribute:: model_class :type: ClassVar[type[simopt.model.Model]] Simulation model class for problem. .. py:attribute:: constraint_type :type: ClassVar[simopt.problem_types.ConstraintType] Description of constraints types. .. py:attribute:: variable_type :type: ClassVar[simopt.problem_types.VariableType] Description of variable types. .. py:attribute:: gradient_available :type: ClassVar[bool] Indicates whether the solver provides direct gradient information. .. py:attribute:: n_objectives :type: ClassVar[int] Number of objectives. .. py:attribute:: minmax :type: ClassVar[tuple[int, Ellipsis]] Indicators of maximization (+1) or minimization (-1) for each objective. .. py:attribute:: n_stochastic_constraints :type: ClassVar[int] Number of stochastic constraints. .. py:attribute:: model_default_factors :type: ClassVar[dict] Default values for overriding model-level default factors. .. py:attribute:: model_decision_factors :type: ClassVar[set[str]] Set of keys for factors that are decision variables. .. py:attribute:: name .. py:attribute:: config .. py:attribute:: model .. py:attribute:: rng_list :type: list[mrg32k3a.mrg32k3a.MRG32k3a] :value: [] .. py:attribute:: before_replicate_override :value: None .. py:property:: optimal_value :type: float | None Optimal objective function value (if known). .. py:property:: optimal_solution :type: tuple | None Optimal solution if known; defaults to None. .. py:property:: dim :type: int :abstractmethod: Number of decision variables. .. py:property:: lower_bounds :type: tuple[float, Ellipsis] :abstractmethod: Lower bound for each decision variable. .. py:property:: upper_bounds :type: tuple[float, Ellipsis] :abstractmethod: Upper bound for each decision variable. .. py:method:: compatibility() -> str Compatibility of the solver. .. py:method:: specifications() -> dict[str, dict] Details of each factor (for GUI, data validation, and defaults). .. py:property:: factors :type: dict Changeable factors of the problem. .. py:method:: attach_rngs(rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a]) -> None Attach a list of random-number generators to the problem. :param rng_list: List of random-number generators used to generate a random initial solution or a random problem instance. :type rng_list: list[``mrg32k3a.mrg32k3a.MRG32k3a``] .. py:method:: vector_to_factor_dict(vector: tuple) -> dict :abstractmethod: Convert a vector of variables to a dictionary with factor keys. :param vector: A vector of values associated with decision variables. :type vector: tuple :returns: Dictionary with factor keys and associated values. :rtype: dict .. py:method:: factor_dict_to_vector(factor_dict: dict) -> tuple :abstractmethod: Convert a dictionary with factor keys to a vector of variables. :param factor_dict: Dictionary with factor keys and associated values. :type factor_dict: dict :returns: Vector of values associated with decision variables. :rtype: tuple .. py:method:: check_deterministic_constraints(x: tuple, /) -> bool Check if a solution `x` satisfies the problem's deterministic constraints. :param x: A vector of decision variables. :type x: tuple :returns: True if the solution satisfies all deterministic constraints; False otherwise. :rtype: bool .. py:method:: get_random_solution(rand_sol_rng: mrg32k3a.mrg32k3a.MRG32k3a) -> tuple :abstractmethod: Generate a random solution for starting or restarting solvers. :param rand_sol_rng: Random number generator used to sample the solution. :type rand_sol_rng: MRG32k3a :returns: A tuple representing a randomly generated vector of decision variables. :rtype: tuple .. py:method:: before_replicate(rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a]) -> None Hook executed before each simulation replication. Subclasses can override this to perform per-replication setup such as using the same RNG for different input models. :param rng_list: RNGs used for this replication. :type rng_list: list[MRG32k3a] .. py:method:: replicate(x: tuple, /) -> RepResult :abstractmethod: Replicate the problem for a given solution. :param x: The solution to evaluate. :type x: tuple .. py:method:: simulate(solution: Solution, num_macroreps: int = 1) -> None Simulate `m` i.i.d. replications at solution `x`. :param solution: Solution to evaluate. :type solution: Solution :param num_macroreps: Number of macroreplications to simulate at `x`. Defaults to 1. :type num_macroreps: int, optional .. py:method:: simulate_up_to(solutions: list[Solution], n_reps: int) -> None Simulate a list of solutions up to a given number of replications. :param solutions: List of Solution objects to simulate. :type solutions: list[Solution] :param n_reps: Common number of replications to simulate each solution up to. :type n_reps: int :raises TypeError: If `solutions` is not a list of Solution objects or if `n_reps` is not an integer. :raises ValueError: If `n_reps` is less than or equal to 0. .. py:class:: Solution(x: tuple, problem: Problem) Base class for solutions in simulation-optimization problems. Solutions are represented by a vector of decision variables and a dictionary of associated decision factors. Initialize a solution object. :param x: Vector of decision variables. :type x: tuple :param problem: Problem to which `x` is a solution. :type problem: Problem .. py:property:: x :type: tuple Vector of decision variables. .. py:property:: dim :type: int Number of decision variables describing `x`. .. py:property:: objectives_mean :type: numpy.ndarray Mean of objectives. .. py:property:: objectives_var :type: numpy.ndarray Variance of objectives. .. py:property:: objectives_stderr :type: numpy.ndarray Standard error of objectives. .. py:property:: objectives_cov :type: numpy.ndarray Covariance of objectives. .. py:property:: objectives_gradients_mean :type: numpy.ndarray Mean of gradients of objectives. .. py:property:: objectives_gradients_var :type: numpy.ndarray Variance of gradients of objectives. .. py:property:: objectives_gradients_stderr :type: numpy.ndarray Standard error of gradients of objectives. .. py:property:: objectives_gradients_cov :type: numpy.ndarray Covariance of gradients of objectives. .. py:property:: stoch_constraints_mean :type: numpy.ndarray Mean of stochastic constraints. .. py:property:: stoch_constraints_var :type: numpy.ndarray Variance of stochastic constraints. .. py:property:: stoch_constraints_stderr :type: numpy.ndarray Standard error of stochastic constraints. .. py:property:: stoch_constraints_cov :type: numpy.ndarray Covariance of stochastic constraints. .. py:property:: stoch_constraints_gradients :type: numpy.ndarray Gradients of stochastic constraints. .. py:property:: stoch_constraints_gradients_mean :type: numpy.ndarray Mean of gradients of stochastic constraints. .. py:attribute:: decision_factors .. py:property:: n_reps :type: int Number of replications. .. py:property:: objectives :type: numpy.ndarray Objectives. .. py:property:: objectives_gradients :type: numpy.ndarray Objectives gradients. .. py:property:: stoch_constraints :type: numpy.ndarray Stochastic constraints. .. py:method:: attach_rngs(rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a], copy: bool = True) -> None Attach a list of random-number generators to the solution. :param rng_list: List of RNGs used to run simulation replications. :type rng_list: list[MRG32k3a] :param copy: If True (default), copies the RNGs before attaching them. If False, attaches the original RNG objects directly. :type copy: bool, optional .. py:method:: add_replicate_result(result: RepResult) -> None Add a replicate result to the solution. :param result: The replicate result to add. :type result: RepResult