base module¶

Summary¶

Provide base classes for solvers, problems, and models.

class base.Model(fixed_factors)¶

Bases: object

Base class to implement simulation models (models) featured in simulation-optimization problems.

name¶

Name of model.

Type: str

n_rngs¶

Number of random-number generators used to run a simulation replication.

Type: int

n_responses¶

Number of responses (performance measures).

Type: int

factors¶

Changeable factors of the simulation model.

Type: dict

specifications¶

Details of each factor (for GUI, data validation, and defaults).

Type: dict

check_factor_list¶

Switch case for checking factor simulatability.

Type: dict

Parameters: fixed_factors (dict) – Dictionary of user-specified model factors.

check_factor_datatype(factor_name)¶

Determine if a factor’s data type matches its specification.

Returns: is_right_type – True if factor is of specified data type, otherwise False.
Return type: bool

check_simulatable_factor(factor_name)¶

Determine if a simulation replication can be run with the given factor.

Parameters: factor_name (str) – Name of factor for dictionary lookup (i.e., key).
Returns: is_simulatable – True if model specified by factors is simulatable, otherwise False.
Return type: bool

check_simulatable_factors()¶

Determine if a simulation replication can be run with the given factors.

Notes

Each subclass of base.Model has its own custom check_simulatable_factors method.

Returns: is_simulatable – True if model specified by factors is simulatable, otherwise False.
Return type: bool

replicate(rng_list)¶

Simulate a single replication for the current model factors.

Parameters

rng_list (list [mrg32k3a.mrg32k3a.MRG32k3a]) – RNGs for model to use when simulating a replication.

Returns

responses (dict) – Performance measures of interest.
gradients (dict [dict]) – Gradient estimate for each response.

class base.Problem(fixed_factors, model_fixed_factors)¶

Bases: object

Base class to implement simulation-optimization problems.

name¶

Name of problem.

Type: str

dim¶

Number of decision variables.

Type: int

n_objectives¶

Number of objectives.

Type: int

n_stochastic_constraints¶

Number of stochastic constraints.

Type: int

minmax¶

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

Type: tuple [int]

constraint_type¶

Description of constraints types: “unconstrained”, “box”, “deterministic”, “stochastic”.

Type: str

variable_type¶

Description of variable types: “discrete”, “continuous”, “mixed”.

Type: str

lower_bounds¶

Lower bound for each decision variable.

Type: tuple

upper_bounds¶

Upper bound for each decision variable.

Type: tuple

gradient_available¶

True if direct gradient of objective function is available, otherwise False.

Type: bool

optimal_value¶

Optimal objective function value.

Type: float

optimal_solution¶

Optimal solution.

Type: tuple

model¶

Associated simulation model that generates replications.

Type: base.Model

model_default_factors¶

Default values for overriding model-level default factors.

Type: dict

model_fixed_factors¶

Combination of overriden model-level factors and defaults.

Type: dict

model_decision_factors¶

Set of keys for factors that are decision variables.

Type: set [str]

rng_list¶

List of RNGs used to generate a random initial solution or a random problem instance.

Type: list [mrg32k3a.mrg32k3a.MRG32k3a]

factors¶

Changeable factors of the problem:

initial_solutiontuple: Default initial solution from which solvers start.
budgetint: Max number of replications (fn evals) for a solver to take.

Type: dict

specifications¶

Details of each factor (for GUI, data validation, and defaults).

Type: dict

Parameters

fixed_factors (dict) – Dictionary of user-specified problem factors.
model_fixed_factors (dict) – Subset of user-specified non-decision factors to pass through to the model.

attach_rngs(rng_list)¶

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.

check_budget()¶

Check if budget is strictly positive.

Returns: True if budget is strictly positive, otherwise False.
Return type: bool

check_deterministic_constraints(x)¶

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

Parameters: x (tuple) – Vector of decision variables.
Returns: satisfies – True if solution x satisfies the deterministic constraints, otherwise False.
Return type: bool

check_factor_datatype(factor_name)¶

Determine if a factor’s data type matches its specification.

Parameters: factor_name (str) – String corresponding to name of factor to check.
Returns: is_right_type – True if factor is of specified data type, otherwise False.
Return type: bool

check_initial_solution()¶

Check if initial solution is feasible and of correct dimension.

Returns: True if initial solution is feasible and of correct dimension, otherwise False.
Return type: bool

check_problem_factor(factor_name)¶

Determine if the setting of a problem factor is permissible.

Parameters: factor_name (str) – Name of factor for dictionary lookup (i.e., key).
Returns: is_permissible – True if problem factor is permissible, otherwise False.
Return type: bool

check_problem_factors()¶

Determine if the joint settings of problem factors are permissible.

Notes

Each subclass of base.Problem has its own custom check_problem_factors method.

Returns: is_simulatable – True if problem factors are permissible, otherwise False.
Return type: bool

deterministic_objectives_and_gradients(x)¶

Compute deterministic components of objectives for a solution x.

Parameters

x (tuple) – Vector of decision variables.

Returns

det_objectives (tuple) – Vector of deterministic components of objectives.
det_objectives_gradients (tuple) – Vector of gradients of deterministic components of objectives.

deterministic_stochastic_constraints_and_gradients(x)¶

Compute deterministic components of stochastic constraints for a solution x.

Parameters

x (tuple) – Vector of decision variables.

Returns

det_stoch_constraints (tuple) – Vector of deterministic components of stochastic constraints.
det_stoch_constraints_gradients (tuple) – Vector of gradients of deterministic components of stochastic constraints.

factor_dict_to_vector(factor_dict)¶

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

Notes

Each subclass of base.Problem has its own custom factor_dict_to_vector method.

Parameters: factor_dict (dict) – Dictionary with factor keys and associated values.
Returns: vector – Vector of values associated with decision variables.
Return type: tuple

factor_dict_to_vector_gradients(factor_dict)¶

Convert a dictionary with factor keys to a gradient vector.

Notes

A subclass of base.Problem can have its own custom factor_dict_to_vector_gradients method if the objective is deterministic.

Parameters: factor_dict (dict) – Dictionary with factor keys and associated values.
Returns: vector – Vector of partial derivatives associated with decision variables.
Return type: tuple

get_random_solution(rand_sol_rng)¶

Generate a random solution for starting or restarting solvers.

Parameters: rand_sol_rng (mrg32k3a.mrg32k3a.MRG32k3a) – Random-number generator used to sample a new random solution.
Returns: x – vector of decision variables
Return type: tuple

response_dict_to_objectives(response_dict)¶

Convert a dictionary with response keys to a vector of objectives.

Notes

Each subclass of base.Problem has its own custom response_dict_to_objectives method.

Parameters: response_dict (dict) – Dictionary with response keys and associated values.
Returns: objectives – Vector of objectives.
Return type: tuple

response_dict_to_objectives_gradients(response_dict)¶

Convert a dictionary with response keys to a vector of gradients.

Notes

A subclass of base.Problem can have its own custom response_dict_to_objectives_gradients method if the objective is deterministic.

Parameters: response_dict (dict) – Dictionary with response keys and associated values.
Returns: vector – Vector of gradients.
Return type: tuple

response_dict_to_stoch_constraints(response_dict)¶

Convert a dictionary with response keys to a vector of left-hand sides of stochastic constraints: E[Y] <= 0.

Notes

Each subclass of base.Problem has its own custom response_dict_to_stoch_constraints method.

Parameters: response_dict (dict) – Dictionary with response keys and associated values.
Returns: stoch_constraints – Vector of LHSs of stochastic constraints.
Return type: tuple

simulate(solution, m=1)¶

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

Notes

Gradients of objective function and stochastic constraint LHSs are temporarily commented out. Under development.

Parameters

solution (base.Solution) – Solution to evalaute.
m (int) – Number of replications to simulate at x.

simulate_up_to(solutions, n_reps)¶

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

Parameters

solutions (set [base.Solution]) – A set of base.Solution objects.
n_reps (int) – Common number of replications to simulate each solution up to.

vector_to_factor_dict(vector)¶

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

Notes

Each subclass of base.Problem has its own custom vector_to_factor_dict method.

Parameters: vector (tuple) – Vector of values associated with decision variables.
Returns: factor_dict – Dictionary with factor keys and associated values.
Return type: dict

class base.Solution(x, problem)¶

Bases: object

Base class for solutions represented as vectors of decision variables and dictionaries of decision factors.

x¶

Vector of decision variables.

Type: tuple

dim¶

Number of decision variables describing x.

Type: int

decision_factors¶

Decision factor names and values.

Type: dict

rng_list¶

RNGs for model to use when running replications at the solution.

Type: list [mrg32k3a.mrg32k3a.MRG32k3a]

n_reps¶

Number of replications run at the solution.

Type: int

det_objectives¶

Deterministic components added to objectives.

Type: tuple

det_objectives_gradients¶

Gradients of deterministic components added to objectives; # objectives x dimension.

Type: tuple [tuple]

det_stoch_constraints¶

Deterministic components added to LHS of stochastic constraints.

Type: tuple

det_stoch_constraints_gradients¶

Gradients of deterministics components added to LHS stochastic constraints; # stochastic constraints x dimension.

Type: tuple [tuple]

storage_size¶

Max number of replications that can be recorded in current storage.

Type: int

objectives¶

Objective(s) estimates from each replication; # replications x # objectives.

Type: numpy array

objectives_gradients¶

Gradient estimates of objective(s) from each replication; # replications x # objectives x dimension.

Type: numpy array

stochastic_constraints¶

Stochastic constraint estimates from each replication; # replications x # stochastic constraints.

Type: numpy array

stochastic_constraints_gradients¶

Gradient estimates of stochastic constraints from each replication; # replications x # stochastic constraints x dimension.

Type: numpy array

Parameters

x (tuple) – Vector of decision variables.
problem (base.Problem) – Problem to which x is a solution.

attach_rngs(rng_list, copy=True)¶

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

Parameters

rng_list (list [mrg32k3a.mrg32k3a.MRG32k3a]) – List of random-number generators used to run simulation replications.
copy (bool, default=True) – True if we want to copy the mrg32k3a.mrg32k3a.MRG32k3a objects, otherwise False.

pad_storage(m)¶

Append zeros to numpy arrays for summary statistics.

Parameters: m (int) – Number of replications to simulate.

recompute_summary_statistics()¶

Recompute summary statistics of the solution.

Notes

Statistics for gradients of objectives and stochastic constraint LHSs are temporarily commented out. Under development.

class base.Solver(fixed_factors)¶

Bases: object

Base class to implement simulation-optimization solvers.

name¶

Name of solver.

Type: str

objective_type¶

Description of objective types: “single” or “multi”.

Type: str

constraint_type¶

Description of constraints types: “unconstrained”, “box”, “deterministic”, “stochastic”.

Type: str

variable_type¶

Description of variable types: “discrete”, “continuous”, “mixed”.

Type: str

gradient_needed¶

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

Type: bool

factors¶

Changeable factors (i.e., parameters) of the solver.

Type: dict

specifications¶

Details of each factor (for GUI, data validation, and defaults).

Type: dict

rng_list¶

List of RNGs used for the solver’s internal purposes.

Type: list [mrg32k3a.mrg32k3a.MRG32k3a]

solution_progenitor_rngs¶

List of RNGs used as a baseline for simulating solutions.

Type: list [mrg32k3a.mrg32k3a.MRG32k3a]

Parameters: fixed_factors (dict) – Dictionary of user-specified solver factors.

attach_rngs(rng_list)¶

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.

check_crn_across_solns()¶

Check solver factor crn_across_solns.

Notes

Currently implemented to always return True. This factor must be a bool.

check_factor_datatype(factor_name)¶

Determine if a factor’s data type matches its specification.

Parameters: factor_name (str) – String corresponding to name of factor to check.
Returns: is_right_type – True if factor is of specified data type, otherwise False.
Return type: bool

check_solver_factor(factor_name)¶

Determine if the setting of a solver factor is permissible.

Parameters: factor_name (str) – Name of factor for dictionary lookup (i.e., key).
Returns: is_permissible – True if the solver factor is permissible, otherwise False.
Return type: bool

check_solver_factors()¶

Determine if the joint settings of solver factors are permissible.

Notes

Each subclass of base.Solver has its own custom check_solver_factors method.

Returns: is_simulatable – True if the solver factors are permissible, otherwise False.
Return type: bool

create_new_solution(x, problem)¶

Create a new solution object with attached RNGs primed to simulate replications.

Parameters

x (tuple) – Vector of decision variables.
problem (base.Problem) – Problem being solved by the solvers.

Returns

new_solution – New solution.

Return type

base.Solution

rebase(n_reps)¶

Rebase the progenitor rngs to start at a later subsubstream index.

Parameters: n_reps (int) – Substream index to skip to.

solve(problem)¶

Run a single macroreplication of a solver on a problem.

Notes

Each subclass of base.Solver has its own custom solve method.

Parameters

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

Returns

recommended_solns (list [Solution]) – List of solutions recommended throughout the budget.
intermediate_budgets (list [int]) – List of intermediate budgets when recommended solutions changes.