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.