simopt.models.contam
====================

.. py:module:: simopt.models.contam

.. autoapi-nested-parse::

   Simulate contamination rates.







Module Contents
---------------

.. py:data:: NUM_STAGES
   :type:  Final[int]
   :value: 5


.. py:class:: ContaminationConfig

   Bases: :py:obj:`pydantic.BaseModel`


   Configuration model for Contamination simulation.

   A model that simulates a contamination problem with a beta distribution.
   Returns the probability of violating contamination upper limit in each level of
   supply chain.


   .. py:attribute:: contam_rate_alpha
      :type:  Annotated[float, Field(default=1.0, description='alpha parameter of beta distribution for growth rate of contamination at each stage', gt=0)]


   .. py:attribute:: contam_rate_beta
      :type:  Annotated[float, Field(default=round(17 / 3, 2), description='beta parameter of beta distribution for growth rate of contamination at each stage', gt=0)]


   .. py:attribute:: restore_rate_alpha
      :type:  Annotated[float, Field(default=1.0, description='alpha parameter of beta distribution for rate that contamination decreases by after prevention effort', gt=0)]


   .. py:attribute:: restore_rate_beta
      :type:  Annotated[float, Field(default=round(3 / 7, 3), description='beta parameter of beta distribution for rate that contamination decreases by after prevention effort', gt=0)]


   .. py:attribute:: initial_rate_alpha
      :type:  Annotated[float, Field(default=1.0, description='alpha parameter of beta distribution for initial contamination fraction', gt=0)]


   .. py:attribute:: initial_rate_beta
      :type:  Annotated[float, Field(default=30.0, description='beta parameter of beta distribution for initial contamination fraction', gt=0)]


   .. py:attribute:: stages
      :type:  Annotated[int, Field(default=NUM_STAGES, description='stage of food supply chain', gt=0)]


   .. py:attribute:: prev_decision
      :type:  Annotated[tuple[float, Ellipsis], Field(default=(0, ) * NUM_STAGES, description='prevention decision')]


.. py:class:: ContaminationTotalCostContConfig

   Bases: :py:obj:`pydantic.BaseModel`


   Configuration model for Contamination Total Cost Continuous Problem.

   A problem configuration that minimizes total cost for continuous contamination
   control decisions.


   .. py:attribute:: initial_solution
      :type:  Annotated[tuple[float, Ellipsis], Field(default_factory=lambda: (1, ) * NUM_STAGES, description='initial solution')]


   .. py:attribute:: budget
      :type:  Annotated[int, Field(default=10000, description='max # of replications for a solver to take', gt=0, json_schema_extra={'isDatafarmable': False})]


   .. py:attribute:: prev_cost
      :type:  Annotated[list[float], Field(default_factory=lambda: [1] * NUM_STAGES, description='cost of prevention')]


   .. py:attribute:: error_prob
      :type:  Annotated[list[float], Field(default_factory=lambda: [0.2] * NUM_STAGES, description='error probability')]


   .. py:attribute:: upper_thres
      :type:  Annotated[list[float], Field(default_factory=lambda: [0.1] * NUM_STAGES, description='upper limit of amount of contamination')]


.. py:class:: ContaminationTotalCostDiscConfig

   Bases: :py:obj:`pydantic.BaseModel`


   Configuration model for Contamination Total Cost Discrete Problem.

   A problem configuration that minimizes total cost for discrete contamination
   control decisions.


   .. py:attribute:: initial_solution
      :type:  Annotated[tuple[int, Ellipsis], Field(default_factory=lambda: (1, ) * NUM_STAGES, description='initial solution')]


   .. py:attribute:: budget
      :type:  Annotated[int, Field(default=10000, description='max # of replications for a solver to take', gt=0)]


   .. py:attribute:: prev_cost
      :type:  Annotated[list[float], Field(default_factory=lambda: [1] * NUM_STAGES, description='cost of prevention')]


   .. py:attribute:: error_prob
      :type:  Annotated[list[float], Field(default_factory=lambda: [0.2] * NUM_STAGES, description='error probability')]


   .. py:attribute:: upper_thres
      :type:  Annotated[list[float], Field(default_factory=lambda: [0.1] * NUM_STAGES, description='upper limit of amount of contamination')]


.. py:class:: Contamination(fixed_factors: dict | None = None)

   Bases: :py:obj:`simopt.base.Model`


   Contamination model with contamination and restoration rates.

   A model that simulates a contamination problem with a beta distribution.
   Returns the probability of violating contamination upper limit in each level of
   supply chain.

   Initialize the Contamination model.

   :param fixed_factors: Fixed factors for the model.
                         Defaults to None.
   :type fixed_factors: dict, optional


   .. py:attribute:: class_name_abbr
      :type:  ClassVar[str]
      :value: 'CONTAM'


      Short name of the model class.


   .. py:attribute:: class_name
      :type:  ClassVar[str]
      :value: 'Contamination'


      Long name of the model class.


   .. py:attribute:: config_class
      :type:  ClassVar[type[pydantic.BaseModel]]

      Configuration class for the model.


   .. py:attribute:: n_rngs
      :type:  ClassVar[int]
      :value: 2


      Number of RNGs used to run a simulation replication.


   .. py:attribute:: n_responses
      :type:  ClassVar[int]
      :value: 1


      Number of responses (performance measures).


   .. py:attribute:: contam_model


   .. py:attribute:: restore_model


   .. py:method:: before_replicate(rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a]) -> None

      Prepare the model just before generating a replication.

      :param rng_list: RNGs used to drive the simulation.
      :type rng_list: list[MRG32k3a]

      :raises NotImplementedError: If the subclass does not implement this hook.



   .. py:method:: replicate() -> tuple[dict, dict]

      Simulate a single replication for the current model factors.

      :param rng_list: Random number generators used to simulate
                       the replication.
      :type rng_list: list[MRG32k3a]

      :returns:

                A tuple containing:
                    - responses (dict): Performance measures of interest, including:
                        - "level": A list of contamination levels over time.
                    - gradients (dict): A dictionary of gradient estimates for each
                        response.
      :rtype: tuple[dict, dict]



.. py:class:: ContaminationTotalCostDisc(name: str = '', fixed_factors: dict | None = None, model_fixed_factors: dict | None = None)

   Bases: :py:obj:`simopt.base.Problem`


   Base class to implement simulation-optimization problems.

   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]
      :value: 'CONTAM-1'


      Short name of the problem class.


   .. py:attribute:: class_name
      :type:  ClassVar[str]
      :value: 'Min Total Cost for Discrete Contamination'


      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.base.Model]]

      Simulation model class for problem.


   .. py:attribute:: n_objectives
      :type:  ClassVar[int]
      :value: 1


      Number of objectives.


   .. py:attribute:: n_stochastic_constraints
      :type:  ClassVar[int]
      :value: 5


      Number of stochastic constraints.


   .. py:attribute:: minmax
      :type:  ClassVar[tuple[int, Ellipsis]]

      Indicators of maximization (+1) or minimization (-1) for each objective.


   .. py:attribute:: constraint_type
      :type:  ClassVar[simopt.base.ConstraintType]

      Description of constraints types.


   .. py:attribute:: variable_type
      :type:  ClassVar[simopt.base.VariableType]

      Description of variable types.


   .. py:attribute:: gradient_available
      :type:  ClassVar[bool]
      :value: True


      Indicates whether the solver provides direct gradient information.


   .. py:attribute:: optimal_value
      :type:  float | None
      :value: None


      Optimal objective function value (if known).


   .. py:attribute:: optimal_solution
      :type:  tuple | None
      :value: None


      Optimal solution if known; defaults to None.


   .. 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:property:: dim
      :type: int


      Number of decision variables.


   .. py:property:: lower_bounds
      :type: tuple


      Lower bound for each decision variable.


   .. py:property:: upper_bounds
      :type: tuple


      Upper bound for each decision variable.


   .. py:method:: vector_to_factor_dict(vector: tuple) -> dict

      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

      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:: replicate(x: tuple) -> simopt.base.RepResult

      Replicate the problem for a given solution.

      :param x: The solution to evaluate.
      :type x: 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

      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:class:: ContaminationTotalCostCont(name: str = '', fixed_factors: dict | None = None, model_fixed_factors: dict | None = None)

   Bases: :py:obj:`simopt.base.Problem`


   Base class to implement simulation-optimization problems.

   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]
      :value: 'CONTAM-2'


      Short name of the problem class.


   .. py:attribute:: class_name
      :type:  ClassVar[str]
      :value: 'Min Total Cost for Continuous Contamination'


      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.base.Model]]

      Simulation model class for problem.


   .. py:attribute:: n_objectives
      :type:  ClassVar[int]
      :value: 1


      Number of objectives.


   .. py:attribute:: n_stochastic_constraints
      :type:  ClassVar[int]
      :value: 5


      Number of stochastic constraints.


   .. py:attribute:: minmax
      :type:  ClassVar[tuple[int, Ellipsis]]

      Indicators of maximization (+1) or minimization (-1) for each objective.


   .. py:attribute:: constraint_type
      :type:  ClassVar[simopt.base.ConstraintType]

      Description of constraints types.


   .. py:attribute:: variable_type
      :type:  ClassVar[simopt.base.VariableType]

      Description of variable types.


   .. py:attribute:: gradient_available
      :type:  ClassVar[bool]
      :value: True


      Indicates whether the solver provides direct gradient information.


   .. py:attribute:: optimal_value
      :type:  ClassVar[float | None]
      :value: None


      Optimal objective function value (if known).


   .. py:attribute:: optimal_solution
      :type:  tuple | None
      :value: None


      Optimal solution if known; defaults to None.


   .. 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:property:: dim
      :type: int


      Number of decision variables.


   .. py:property:: lower_bounds
      :type: tuple


      Lower bound for each decision variable.


   .. py:property:: upper_bounds
      :type: tuple


      Upper bound for each decision variable.


   .. py:method:: vector_to_factor_dict(vector: tuple) -> dict

      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

      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:: replicate(x: tuple) -> simopt.base.RepResult

      Replicate the problem for a given solution.

      :param x: The solution to evaluate.
      :type x: 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

      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