simopt.solver

Base classes for simulation optimization solvers.

Module Contents

exception simopt.solver.BudgetExhaustedError

Bases: Exception

Raised when a solver exceeds its allotted simulation budget.

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

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

class simopt.solver.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 request() before taking replications. If the request would exceed total, a BudgetExhaustedException is raised. This provides a consistent way for solvers to terminate exactly at the specified budget.

Parameters:: total (int) – Total number of replications available for the run.

Initialize object with the total number of replications available.

total

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.

Parameters:: amount (int) – Number of replications to consume.
Raises:: BudgetExhaustedException – If amount would cause usage to exceed total.

property used: int: Number of replications consumed so far.

property remaining: int: Number of replications still available (total - used).

class simopt.solver.SolverConfig

Bases: pydantic.BaseModel

Base class for solver configuration.

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

class simopt.solver.Solver(name: str = '', fixed_factors: dict | None = None)

Bases: 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.

Parameters:

name (str) – Name of the solver.
fixed_factors (dict) – Dictionary of user-specified solver factors.

Initialize a solver object.

Parameters:

name (str, optional) – Name of the solver. Defaults to an empty string.
fixed_factors (dict | None, optional) – Dictionary of user-specified solver factors. Defaults to None.

class_name_abbr: ClassVar[str]: Short name of the solver class.

class_name: ClassVar[str]: Long name of the solver class.

config_class: ClassVar[type[SolverConfig]]: Configuration class for the solver.

objective_type: ClassVar[simopt.problem_types.ObjectiveType]: Description of objective types.

constraint_type: ClassVar[simopt.problem_types.ConstraintType]: Description of constraint types.

variable_type: ClassVar[simopt.problem_types.VariableType]: Description of variable types.

gradient_needed: ClassVar[bool]: True if gradient of objective function is needed, otherwise False.

name

config

rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a] = []

solution_progenitor_rngs: list[mrg32k3a.mrg32k3a.MRG32k3a] = []

recommended_solns = []

intermediate_budgets = []

compatibility() → str: Compatibility of the solver.

specifications() → dict[str, dict]: Details of each factor (for GUI, data validation, and defaults).

property factors: dict: Changeable factors (i.e., parameters) of the solver.

attach_rngs(rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a]) → None

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

Parameters:: rng_list (list[mrg32k3a.mrg32k3a.MRG32k3a]) – List of random-number generators used for the solver’s internal purposes.

abstractmethod solve(problem: simopt.problem.Problem) → None

Run a single macroreplication of a solver on a problem.

Parameters:

problem (Problem) – Simulation-optimization problem to solve.

Returns:

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

Return type:

tuple

run(problem: simopt.problem.Problem) → tuple[list[simopt.problem.Solution], list[int]]

Run the solver on a problem.

Parameters:: problem (Problem) – The problem to solve.
Returns:: A tuple containing a list of solutions and a list of intermediate budgets.
Return type:: tuple[list[Solution], list[int]]

create_new_solution(x: tuple, problem: simopt.problem.Problem) → simopt.problem.Solution

Create a new solution object with attached RNGs.

Parameters:

x (tuple) – A vector of decision variables.
problem (Problem) – The problem instance associated with the solution.

Returns:

New solution object for the given decision variables and problem.

Return type:

Solution