simopt.problem

Base classes for simulation optimization problems and models.

Module Contents

class simopt.problem.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.

Parameters:

• stochastic – The stochastic component of the objective value.

• stochastic_gradients – Gradients of the stochastic component.

• deterministic – The deterministic component of the objective value.

• deterministic_gradients – Gradients of the deterministic component.

stochastic

stochastic_gradients = None

deterministic = 0.0

deterministic_gradients = None

value() → float

Return the total objective value (stochastic + deterministic).

grad() → numpy.ndarray | None

Return the combined gradients of both components, or None if unavailable.

class simopt.problem.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.

Parameters:

• stochastic – The stochastic component of the constraint.

• stochastic_gradients – Gradients of the stochastic component.

• deterministic – The deterministic component of the constraint.

• deterministic_gradients – Gradients of the deterministic component.

stochastic

stochastic_gradients = None

deterministic = 0.0

deterministic_gradients = None

value() → float

Return the total constraint value (stochastic + deterministic if present).

grad() → numpy.ndarray | None

Return the combined gradients of both components, or None if unavailable.

class simopt.problem.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.

Parameters:

• objectives – List of objective function results from the replication.

• stochastic_constraints – Optional list of stochastic constraint results.

objectives

stochastic_constraints = None

class simopt.problem.Problem(name: str = '', fixed_factors: dict | None = None, model_fixed_factors: dict | None = None)

Bases: abc.ABC

Base class for simulation-optimization problems.

Parameters:

• name (str) – Problem name.

• fixed_factors (dict) – User-defined factors that affect the problem setup.

• model_fixed_factors (dict) – Subset of non-decision factors passed to the model.

Initialize a problem object.

Parameters:

• name (str) – Name of the problem.

• fixed_factors (dict | None) – Dictionary of user-specified problem factors.

• model_fixed_factors (dict | None) – Subset of user-specified non-decision factors passed to the model.

class_name_abbr: ClassVar[str]

Short name of the problem class.

class_name: ClassVar[str]

Long name of the problem class.

config_class: ClassVar[type[pydantic.BaseModel]]

Configuration class for problem.

model_class: ClassVar[type[simopt.model.Model]]

Simulation model class for problem.

constraint_type: ClassVar[simopt.problem_types.ConstraintType]

Description of constraints types.

variable_type: ClassVar[simopt.problem_types.VariableType]

Description of variable types.

gradient_available: ClassVar[bool]

Indicates whether the solver provides direct gradient information.

n_objectives: ClassVar[int]

Number of objectives.

minmax: ClassVar[tuple[int, Ellipsis]]

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

n_stochastic_constraints: ClassVar[int]

Number of stochastic constraints.

model_default_factors: ClassVar[dict]

Default values for overriding model-level default factors.

model_decision_factors: ClassVar[set[str]]

Set of keys for factors that are decision variables.

name

config

model

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

before_replicate_override = None

property optimal_value: float | None

Optimal objective function value (if known).

property optimal_solution: tuple | None

Optimal solution if known; defaults to None.

property dim: int

Abstractmethod:

Number of decision variables.

property lower_bounds: tuple[float, Ellipsis]

Abstractmethod:

Lower bound for each decision variable.

property upper_bounds: tuple[float, Ellipsis]

Abstractmethod:

Upper bound for each decision variable.

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 of the problem.

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

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

Parameters:

rng_list (list[mrg32k3a.mrg32k3a.MRG32k3a]) – List of random-number generators used to generate a random initial solution or a random problem instance.

abstractmethod vector_to_factor_dict(vector: tuple) → dict

Convert a vector of variables to a dictionary with factor keys.

Parameters:

vector (tuple) – A vector of values associated with decision variables.

Returns:

Dictionary with factor keys and associated values.

Return type:

dict

abstractmethod factor_dict_to_vector(factor_dict: dict) → tuple

Convert a dictionary with factor keys to a vector of variables.

Parameters:

factor_dict (dict) – Dictionary with factor keys and associated values.

Returns:

Vector of values associated with decision variables.

Return type:

tuple

check_deterministic_constraints(x: tuple, /) → bool

Check if a solution x satisfies the problem’s deterministic constraints.

Parameters:

x (tuple) – A vector of decision variables.

Returns:

True if the solution satisfies all deterministic constraints;

False otherwise.

Return type:

bool

abstractmethod get_random_solution(rand_sol_rng: mrg32k3a.mrg32k3a.MRG32k3a) → tuple

Generate a random solution for starting or restarting solvers.

Parameters:

rand_sol_rng (MRG32k3a) – Random number generator used to sample the solution.

Returns:

A tuple representing a randomly generated vector of decision

variables.

Return type:

tuple

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.

Parameters:

rng_list (list[MRG32k3a]) – RNGs used for this replication.

abstractmethod replicate(x: tuple, /) → RepResult

Replicate the problem for a given solution.

Parameters:

x (tuple) – The solution to evaluate.

simulate(solution: Solution, num_macroreps: int = 1) → None

Simulate m i.i.d. replications at solution x.

Parameters:

• solution (Solution) – Solution to evaluate.

• num_macroreps (int, optional) – Number of macroreplications to simulate at x. Defaults to 1.

simulate_up_to(solutions: list[Solution], n_reps: int) → None

Simulate a list of solutions up to a given number of replications.

Parameters:

• solutions (list[Solution]) – List of Solution objects to simulate.

• n_reps (int) – Common number of replications to simulate each solution up to.

Raises:

• TypeError – If solutions is not a list of Solution objects or if n_reps is not an integer.

• ValueError – If n_reps is less than or equal to 0.

class simopt.problem.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.

Parameters:

• x (tuple) – Vector of decision variables.

• problem (Problem) – Problem to which x is a solution.

property x: tuple

Vector of decision variables.

property dim: int

Number of decision variables describing x.

property objectives_mean: numpy.ndarray

Mean of objectives.

property objectives_var: numpy.ndarray

Variance of objectives.

property objectives_stderr: numpy.ndarray

Standard error of objectives.

property objectives_cov: numpy.ndarray

Covariance of objectives.

property objectives_gradients_mean: numpy.ndarray

Mean of gradients of objectives.

property objectives_gradients_var: numpy.ndarray

Variance of gradients of objectives.

property objectives_gradients_stderr: numpy.ndarray

Standard error of gradients of objectives.

property objectives_gradients_cov: numpy.ndarray

Covariance of gradients of objectives.

property stoch_constraints_mean: numpy.ndarray

Mean of stochastic constraints.

property stoch_constraints_var: numpy.ndarray

Variance of stochastic constraints.

property stoch_constraints_stderr: numpy.ndarray

Standard error of stochastic constraints.

property stoch_constraints_cov: numpy.ndarray

Covariance of stochastic constraints.

property stoch_constraints_gradients: numpy.ndarray

Gradients of stochastic constraints.

property stoch_constraints_gradients_mean: numpy.ndarray

Mean of gradients of stochastic constraints.

decision_factors

property n_reps: int

Number of replications.

property objectives: numpy.ndarray

Objectives.

property objectives_gradients: numpy.ndarray

Objectives gradients.

property stoch_constraints: numpy.ndarray

Stochastic constraints.

attach_rngs(rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a], copy: bool = True) → None

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

Parameters:

• rng_list (list[MRG32k3a]) – List of RNGs used to run simulation replications.

• copy (bool, optional) – If True (default), copies the RNGs before attaching them. If False, attaches the original RNG objects directly.

add_replicate_result(result: RepResult) → None

Add a replicate result to the solution.

Parameters:

result (RepResult) – The replicate result to add.