simopt.experiment.single ======================== .. py:module:: simopt.experiment.single .. autoapi-nested-parse:: Base classes for problem-solver pairs and I/O/plotting helper functions. Module Contents --------------- .. py:data:: model_directory .. py:data:: problem_directory .. py:data:: solver_directory .. py:data:: EXPERIMENT_DIR .. py:class:: 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. :param solver_name: Name of the solver. :type solver_name: str, optional :param problem_name: Name of the problem. :type problem_name: str, optional :param solver_rename: User-defined name for the solver. :type solver_rename: str, optional :param problem_rename: User-defined name for the problem. :type problem_rename: str, optional :param solver: Simulation-optimization solver object. :type solver: Solver, optional :param problem: Simulation-optimization problem object. :type problem: Problem, optional :param solver_fixed_factors: Fixed solver parameters. :type solver_fixed_factors: dict, optional :param problem_fixed_factors: Fixed problem parameters. :type problem_fixed_factors: dict, optional :param model_fixed_factors: Fixed model parameters. :type model_fixed_factors: dict, optional :param file_name_path: Path to save a pickled ProblemSolver object. :type file_name_path: Path | str, optional :param create_pickle: Whether to save the object as a pickle file. :type create_pickle: bool, optional .. py:property:: solver :type: simopt.base.Solver Simulation-optimization solver. .. py:property:: problem :type: simopt.base.Problem Simulation-optimization problem. .. py:property:: n_macroreps :type: int Number of macroreplications run. .. py:property:: file_name_path :type: pathlib.Path Path of .pickle file for saving ProblemSolver object. .. py:property:: all_recommended_xs :type: list[list[tuple]] Sequences of recommended solutions from each macroreplication. .. py:property:: all_intermediate_budgets :type: list[list] Sequences of intermediate budgets from each macroreplication. .. py:property:: timings :type: list[float] Runtimes (in seconds) for each macroreplication. .. py:property:: n_postreps :type: int Number of postreps to take at each recommended solution. .. py:property:: crn_across_budget :type: bool Whether CRN is used across solutions recommended at different times. .. py:property:: crn_across_macroreps :type: bool Whether CRN is used across solutions from different macroreplications. .. py:property:: all_post_replicates :type: list[list[list]] All post-replicates from all solutions from all macroreplications. .. py:property:: all_est_objectives :type: list[list[float]] Estimated objective values of all solutions from all macroreplications. .. py:property:: n_postreps_init_opt :type: int Number of postreplications at initial (x0) and optimal (x*) solutions. .. py:property:: crn_across_init_opt :type: bool Whether CRN is used for postreplications at x0 and x* solutions. .. py:property:: x0 :type: tuple Initial solution (x0). .. py:property:: x0_postreps :type: list Post-replicates at x0. .. py:property:: xstar :type: tuple Proxy for optimal solution (x*). .. py:property:: xstar_postreps :type: list Post-replicates at x*. .. py:property:: objective_curves :type: list[simopt.curve.Curve] Estimated objective function curves, one per macroreplication. .. py:property:: progress_curves :type: list[simopt.curve.Curve] Progress curves, one for each macroreplication. .. py:property:: has_run :type: bool True if the solver has been run on the problem, otherwise False. .. py:property:: has_postreplicated :type: bool True if the solver has been postreplicated, otherwise False. .. py:property:: has_postnormalized :type: bool True if the solver has been postprocessed, otherwise False. .. py:attribute:: create_pickle :value: True .. py:attribute:: all_stoch_constraints :value: [] .. py:attribute:: all_est_lhs :value: [] .. py:attribute:: feasibility_curves :value: [] .. py:method:: model_created(model: simopt.base.Model) -> None Hook called after the problem's model is instantiated. :param model: The initialized model associated with the experiment's problem. This is a helper function to customize the experiment's input model. .. py:method:: before_replicate(model: simopt.base.Model, rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a]) -> None Hook executed immediately before each replication during an experiment. :param model: The model about to be simulated. :param rng_list: The list of RNGs used for the replication. This is a helper function to customize behavior before each replication. .. py:method:: check_compatibility() -> str Check whether the experiment's solver and problem are compatible. :returns: Error message in the event problem and solver are incompatible. :rtype: str .. py:method:: 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. :param n_macroreps: Number of macroreplications to run. :type n_macroreps: int :param n_jobs: Number of jobs to run in parallel. Defaults to -1. -1: use all available cores 1: run sequentially :type n_jobs: int, optional :raises ValueError: If `n_macroreps` is not positive. .. py:method:: run_multithread(mrep: int, solver: simopt.base.Solver, problem: simopt.base.Problem) -> tuple Runs one macroreplication of the solver on the problem. :param mrep: Index of the macroreplication. :type mrep: int :param solver: The simulation-optimization solver to run. :type solver: Solver :param problem: The problem to solve. :type problem: Problem :returns: A tuple containing: - int: Macroreplication index. - list: Recommended solutions. - list: Intermediate budgets. - float: Runtime for the macroreplication. :rtype: tuple :raises ValueError: If `mrep` is negative. .. py:method:: post_replicate(n_postreps: int, crn_across_budget: bool = True, crn_across_macroreps: bool = False) -> None Runs postreplications at the solver's recommended solutions. :param n_postreps: Number of postreplications at each recommended solution. :type n_postreps: int :param crn_across_budget: If True, use CRN across solutions from different time budgets. Defaults to True. :type crn_across_budget: bool, optional :param crn_across_macroreps: If True, use CRN across solutions from different macroreplications. Defaults to False. :type crn_across_macroreps: bool, optional :raises ValueError: If `n_postreps` is not positive. .. py:method:: post_replicate_multithread(mrep: int) -> tuple Runs postreplications for a given macroreplication's recommended solutions. :param mrep: Index of the macroreplication. :type mrep: int :returns: A tuple containing: - int: Macroreplication index. - list: Postreplicates for each recommended solution. - float: Runtime for the macroreplication. :rtype: tuple :raises ValueError: If `mrep` is negative. .. py:method:: 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. :param bootstrap_rng: Random number generator used for bootstrapping. :type bootstrap_rng: MRG32k3a :param normalize: If True, normalize progress curves with respect to optimality gaps. Defaults to True. :type normalize: bool, optional :param feasibility_score_method: Feasibility scoring method. Defaults to "inf_norm". :type feasibility_score_method: Literal["inf_norm", "norm"], optional :param feasibility_norm_degree: Degree of the norm when :type feasibility_norm_degree: int, optional :param ``feasibility_score_method == "norm"``. Defaults to 1.: :param feasibility_two_sided: Whether to award a non-zero score to feasible solutions based on the best violation. :type feasibility_two_sided: bool, optional :param disable_macrorep_bootstrap: Whether to disable bootstrap across macroreplications. Defaults to False. :type disable_macrorep_bootstrap: bool, optional :returns: Bootstrapped progress curves and feasibility curves for all macroreplications. :rtype: tuple[list[Curve], list[Curve]] .. py:method:: 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. .. py:method:: 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. .. py:method:: record_experiment_results(file_name: str) -> None Saves the ProblemSolver object to a .pickle file. :param file_name: Name of the pickle file. It is saved under the EXPERIMENT_DIR path. :type file_name: str .. py:method:: log_experiment_results(print_solutions: bool = True) -> None Creates a readable .txt log file from a problem-solver pair's .pickle file. :param print_solutions: If True, include recommended solutions in the .txt file. Defaults to True. :type print_solutions: bool, optional .. py:function:: 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. :param problem: The problem the solver was run on. :type problem: Problem :param recommended_solutions: Solutions recommended by the solver. :type recommended_solutions: list[Solution] :param intermediate_budgets: Budgets at which solutions were recommended. :type intermediate_budgets: list[int] :returns: A tuple containing: - list[Solution]: Trimmed list of recommended solutions. - list[int]: Trimmed list of corresponding intermediate budgets. :rtype: tuple