simopt.solver
=============

.. py:module:: simopt.solver

.. autoapi-nested-parse::

   Base classes for simulation optimization solvers.







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

.. py:exception:: BudgetExhaustedError

   Bases: :py:obj:`Exception`


   Raised when a solver exceeds its allotted simulation budget.

   This exception is thrown by :class:`Budget` when a call to
   :meth:`Budget.request` asks for more replications than remain in the
   available budget. It is caught in :meth:`Solver.run` to stop the
   macroreplication cleanly once the budget is exhausted.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:class:: Budget(total: int)

   Tracks and enforces a solver's replication budget.

   A ``Budget`` instance is attached to each solver run and measures the number of
   simulation replications consumed. Solvers should call :meth:`request` before
   taking replications. If the request would exceed ``total``, a
   :class:`BudgetExhaustedException` is raised. This provides a consistent way for
   solvers to terminate exactly at the specified budget.

   :param total: Total number of replications available for the run.
   :type total: int

   Initialize object with the total number of replications available.


   .. py:attribute:: total


   .. py:method:: request(amount: int) -> None

      Consume ``amount`` replications from the budget.

      Typical usage is to call ``request(r)`` immediately before taking ``r``
      replications at the current solution.

      :param amount: Number of replications to consume.
      :type amount: int

      :raises BudgetExhaustedException: If ``amount`` would cause usage to exceed
          :attr:`total`.



   .. py:property:: used
      :type: int


      Number of replications consumed so far.


   .. py:property:: remaining
      :type: int


      Number of replications still available (``total - used``).


.. py:class:: SolverConfig

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


   Base class for solver configuration.


   .. py:attribute:: crn_across_solns
      :type:  Annotated[bool, Field(default=True, description='use CRN across solutions?')]


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

   Bases: :py:obj:`abc.ABC`


   Base class to implement simulation-optimization solvers.

   This class defines the core structure for simulation-optimization
   solvers in SimOpt. Subclasses must implement the required methods
   for running simulations and updating solutions.

   :param name: Name of the solver.
   :type name: str
   :param fixed_factors: Dictionary of user-specified solver factors.
   :type fixed_factors: dict

   Initialize a solver object.

   :param name: Name of the solver. Defaults to an empty string.
   :type name: str, optional
   :param fixed_factors: Dictionary of user-specified solver
                         factors. Defaults to None.
   :type fixed_factors: dict | None, optional


   .. py:attribute:: class_name_abbr
      :type:  ClassVar[str]

      Short name of the solver class.


   .. py:attribute:: class_name
      :type:  ClassVar[str]

      Long name of the solver class.


   .. py:attribute:: config_class
      :type:  ClassVar[type[SolverConfig]]

      Configuration class for the solver.


   .. py:attribute:: objective_type
      :type:  ClassVar[simopt.problem_types.ObjectiveType]

      Description of objective types.


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

      Description of constraint types.


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

      Description of variable types.


   .. py:attribute:: gradient_needed
      :type:  ClassVar[bool]

      True if gradient of objective function is needed, otherwise False.


   .. py:attribute:: name


   .. py:attribute:: config


   .. py:attribute:: rng_list
      :type:  list[mrg32k3a.mrg32k3a.MRG32k3a]
      :value: []



   .. py:attribute:: solution_progenitor_rngs
      :type:  list[mrg32k3a.mrg32k3a.MRG32k3a]
      :value: []



   .. py:attribute:: recommended_solns
      :value: []



   .. py:attribute:: intermediate_budgets
      :value: []



   .. 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 (i.e., parameters) of the solver.


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

      Attach a list of random-number generators to the solver.

      :param rng_list: List of random-number
                       generators used for the solver's internal purposes.
      :type rng_list: list[``mrg32k3a.mrg32k3a.MRG32k3a``]



   .. py:method:: solve(problem: simopt.problem.Problem) -> None
      :abstractmethod:


      Run a single macroreplication of a solver on a problem.

      :param problem: Simulation-optimization problem to solve.
      :type problem: Problem

      :returns:     - list [Solution]: List of solutions recommended throughout the budget.
                    - list [int]: List of intermediate budgets when recommended solutions
                        change.
      :rtype: tuple



   .. py:method:: run(problem: simopt.problem.Problem) -> tuple[list[simopt.problem.Solution], list[int]]

      Run the solver on a problem.

      :param problem: The problem to solve.
      :type problem: Problem

      :returns: A tuple containing a list of solutions
                and a list of intermediate budgets.
      :rtype: tuple[list[Solution], list[int]]



   .. py:method:: create_new_solution(x: tuple, problem: simopt.problem.Problem) -> simopt.problem.Solution

      Create a new solution object with attached RNGs.

      :param x: A vector of decision variables.
      :type x: tuple
      :param problem: The problem instance associated with the solution.
      :type problem: Problem

      :returns: New solution object for the given decision variables and problem.
      :rtype: Solution