simopt.experiment.single

Base classes for problem-solver pairs and I/O/plotting helper functions.

Module Contents

simopt.experiment.single.model_directory
simopt.experiment.single.problem_directory
simopt.experiment.single.solver_directory
simopt.experiment.single.SIMOPT_TOPLEVEL
simopt.experiment.single.EXPERIMENT_DIR
class simopt.experiment.single.ProblemSolver(solver_name: str | None = None, problem_name: str | None = None, solver_rename: str | None = None, problem_rename: str | None = None, solver: simopt.base.Solver | None = None, problem: simopt.base.Problem | None = None, solver_fixed_factors: dict | None = None, problem_fixed_factors: dict | None = None, model_fixed_factors: dict | None = None, file_name_path: pathlib.Path | str | None = None, create_pickle: bool = True)

Base class for running one solver on one problem.

Initializes a ProblemSolver object.

You can either: 1. Provide solver and problem names to look them up via directory.py, or 2. Provide solver and problem objects directly.

Parameters:

  • solver_name (str, optional) – Name of the solver.

  • problem_name (str, optional) – Name of the problem.

  • solver_rename (str, optional) – User-defined name for the solver.

  • problem_rename (str, optional) – User-defined name for the problem.

  • solver (Solver, optional) – Simulation-optimization solver object.

  • problem (Problem, optional) – Simulation-optimization problem object.

  • solver_fixed_factors (dict, optional) – Fixed solver parameters.

  • problem_fixed_factors (dict, optional) – Fixed problem parameters.

  • model_fixed_factors (dict, optional) – Fixed model parameters.

  • file_name_path (Path | str, optional) – Path to save a pickled ProblemSolver object.

  • create_pickle (bool, optional) – Whether to save the object as a pickle file.

property solver: simopt.base.Solver

Simulation-optimization solver.

property problem: simopt.base.Problem

Simulation-optimization problem.

property n_macroreps: int

Number of macroreplications run.

property file_name_path: pathlib.Path

Path of .pickle file for saving ProblemSolver object.

Sequences of recommended solutions from each macroreplication.

property all_intermediate_budgets: list[list]

Sequences of intermediate budgets from each macroreplication.

property timings: list[float]

Runtimes (in seconds) for each macroreplication.

property n_postreps: int

Number of postreps to take at each recommended solution.

property crn_across_budget: bool

Whether CRN is used across solutions recommended at different times.

property crn_across_macroreps: bool

Whether CRN is used across solutions from different macroreplications.

property all_post_replicates: list[list[list]]

All post-replicates from all solutions from all macroreplications.

property all_est_objectives: list[list[float]]

Estimated objective values of all solutions from all macroreplications.

property n_postreps_init_opt: int

Number of postreplications at initial (x0) and optimal (x*) solutions.

property crn_across_init_opt: bool

Whether CRN is used for postreplications at x0 and x* solutions.

property x0: tuple

Initial solution (x0).

property x0_postreps: list

Post-replicates at x0.

property xstar: tuple

Proxy for optimal solution (x*).

property xstar_postreps: list

Post-replicates at x*.

property objective_curves: list[simopt.curve.Curve]

Estimated objective function curves, one per macroreplication.

property progress_curves: list[simopt.curve.Curve]

Progress curves, one for each macroreplication.

property has_run: bool

True if the solver has been run on the problem, otherwise False.

property has_postreplicated: bool

True if the solver has been postreplicated, otherwise False.

property has_postnormalized: bool

True if the solver has been postprocessed, otherwise False.

create_pickle = True
all_stoch_constraints = []
all_est_lhs = []
feasibility_curves = []
model_created(model: simopt.base.Model) → None

Hook called after the problem’s model is instantiated.

Parameters:

model – The initialized model associated with the experiment’s problem.

This is a helper function to customize the experiment’s input model.

before_replicate(model: simopt.base.Model, rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a]) → None

Hook executed immediately before each replication during an experiment.

Parameters:

  • model – The model about to be simulated.

  • rng_list – The list of RNGs used for the replication.

This is a helper function to customize behavior before each replication.

check_compatibility() → str

Check whether the experiment’s solver and problem are compatible.

Returns:

Error message in the event problem and solver are incompatible.

Return type:

str

run(n_macroreps: int, n_jobs: int = -1) → None

Runs the solver on the problem for a given number of macroreplications.

Note

RNGs for random problem instances are reserved but currently unused. This method is under development.

Parameters:

  • n_macroreps (int) – Number of macroreplications to run.

  • n_jobs (int, optional) – Number of jobs to run in parallel. Defaults to -1. -1: use all available cores 1: run sequentially

Raises:

ValueError – If n_macroreps is not positive.

run_multithread(mrep: int, solver: simopt.base.Solver, problem: simopt.base.Problem) → tuple

Runs one macroreplication of the solver on the problem.

Parameters:

  • mrep (int) – Index of the macroreplication.

  • solver (Solver) – The simulation-optimization solver to run.

  • problem (Problem) – The problem to solve.

Returns:

A tuple containing:

  • int: Macroreplication index.

  • list: Recommended solutions.

  • list: Intermediate budgets.

  • float: Runtime for the macroreplication.

Return type:

tuple

Raises:

ValueError – If mrep is negative.

post_replicate(n_postreps: int, crn_across_budget: bool = True, crn_across_macroreps: bool = False) → None

Runs postreplications at the solver’s recommended solutions.

Parameters:

  • n_postreps (int) – Number of postreplications at each recommended solution.

  • crn_across_budget (bool, optional) – If True, use CRN across solutions from different time budgets. Defaults to True.

  • crn_across_macroreps (bool, optional) – If True, use CRN across solutions from different macroreplications. Defaults to False.

Raises:

ValueError – If n_postreps is not positive.

post_replicate_multithread(mrep: int) → tuple

Runs postreplications for a given macroreplication’s recommended solutions.

Parameters:

mrep (int) – Index of the macroreplication.

Returns:

A tuple containing:

  • int: Macroreplication index.

  • list: Postreplicates for each recommended solution.

  • float: Runtime for the macroreplication.

Return type:

tuple

Raises:

ValueError – If mrep is negative.

bootstrap_sample(bootstrap_rng: mrg32k3a.mrg32k3a.MRG32k3a, normalize: bool = True, feasibility_score_method: Literal['inf_norm', 'norm'] = 'inf_norm', feasibility_norm_degree: int = 1, feasibility_two_sided: bool = False, disable_macrorep_bootstrap: bool = False) → tuple[list[simopt.curve.Curve], list[simopt.curve.Curve]]

Generates bootstrap samples of objective/progress and feasibility curves.

Parameters:

  • bootstrap_rng (MRG32k3a) – Random number generator used for bootstrapping.

  • normalize (bool, optional) – If True, normalize progress curves with respect to optimality gaps. Defaults to True.

  • feasibility_score_method (Literal["inf_norm", "norm"], optional) – Feasibility scoring method. Defaults to “inf_norm”.

  • feasibility_norm_degree (int, optional) – Degree of the norm when

  • 1. (feasibility_score_method == "norm". Defaults to)

  • feasibility_two_sided (bool, optional) – Whether to award a non-zero score to feasible solutions based on the best violation.

  • disable_macrorep_bootstrap (bool, optional) – Whether to disable bootstrap across macroreplications. Defaults to False.

Returns:

Bootstrapped progress curves and feasibility curves for all macroreplications.

Return type:

tuple[list[Curve], list[Curve]]

bootstrap_terminal_objective_and_feasibility(bootstrap_rng: mrg32k3a.mrg32k3a.MRG32k3a, feasibility_score_method: Literal['inf_norm', 'norm'] = 'inf_norm', feasibility_norm_degree: int = 1, feasibility_two_sided: bool = True) → tuple[list[float], list[float]]

Bootstraps terminal objective and feasibility scores.

feasibility_score_history(feasibility_score_method: Literal['inf_norm', 'norm'] = 'inf_norm', feasibility_norm_degree: int = 1, feasibility_two_sided: bool = True) → None

Compute feasibility score history.

record_experiment_results(file_name: str) → None

Saves the ProblemSolver object to a .pickle file.

Parameters:

file_name (str) – Name of the pickle file. It is saved under the EXPERIMENT_DIR path.

log_experiment_results(print_solutions: bool = True) → None

Creates a readable .txt log file from a problem-solver pair’s .pickle file.

Parameters:

print_solutions (bool, optional) – If True, include recommended solutions in the .txt file. Defaults to True.

simopt.experiment.single.trim_solver_results(problem: simopt.base.Problem, recommended_solutions: list[simopt.base.Solution], intermediate_budgets: list[int]) → tuple[list[simopt.base.Solution], list[int]]

Trims solver-recommended solutions beyond the problem’s maximum budget.

Parameters:

  • problem (Problem) – The problem the solver was run on.

  • recommended_solutions (list[Solution]) – Solutions recommended by the solver.

  • intermediate_budgets (list[int]) – Budgets at which solutions were recommended.

Returns:

A tuple containing:

  • list[Solution]: Trimmed list of recommended solutions.

  • list[int]: Trimmed list of corresponding intermediate budgets.

Return type:

tuple