simopt.plots.utils

Plotting utilities.

Module Contents

simopt.plots.utils.setup_plot(plot_type: simopt.plot_type.PlotType, solver_name: str = 'SOLVER SET', problem_name: str = 'PROBLEM SET', normalize: bool = True, budget: int | None = None, beta: float | None = None, feasibility_score_method: Literal['inf_norm', 'norm'] = 'inf_norm', feasibility_norm_degree: int = 1, solve_tol: float | None = None, plot_title: str | None = None) → None

Create a new figure, add labels to the plot, and reformat axes.

Parameters:

  • plot_type (PlotType) – Type of plot to produce. Valid options include: - ALL: All estimated progress curves. - MEAN: Estimated mean progress curve. - QUANTILE: Estimated beta quantile progress curve. - SOLVE_TIME_CDF: CDF of solve time. - CDF_SOLVABILITY: CDF solvability profile. - QUANTILE_SOLVABILITY: Quantile solvability profile. - DIFFERENCE_OF_CDF_SOLVABILITY: Difference of CDF solvability profiles. - DIFFERENCE_OF_QUANTILE_SOLVABILITY: Difference of quantile solvability profiles. - AREA: Area scatterplot. - BOX: Box plot of terminal progress. - VIOLIN: Violin plot of terminal progress. - TERMINAL_SCATTER: Scatterplot of mean and std dev of terminal progress.

  • solver_name (str, optional) – Name of the solver. Defaults to “SOLVER SET”.

  • problem_name (str, optional) – Name of the problem. Defaults to “PROBLEM SET”.

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

  • budget (int, optional) – Function evaluation budget.

  • beta (float, optional) – Quantile to compute (must be in (0, 1)).

  • feasibility_score_method (Literal["inf_norm", "norm"], optional) – Method to compute the feasibility score. Defaults to “inf_norm”.

  • feasibility_norm_degree (int, optional) – Degree of the norm to use for the feasibility score. Defaults to 1.

  • solve_tol (float, optional) – Relative optimality gap for declaring a solve (must be in (0, 1]).

  • plot_title (str, optional) – Title to override the automatically generated one.

Raises:

ValueError – If any inputs are invalid.

simopt.plots.utils.save_plot(solver_name: str, problem_name: str, plot_type: simopt.plot_type.PlotType, normalize: bool, extra: float | list[float] | None = None, plot_title: str | None = None, ext: str = '.png', save_as_pickle: bool = False) → pathlib.Path

Create and save a plot with appropriate labels and formatting.

Parameters:

  • solver_name (str) – Name of the solver.

  • problem_name (str) – Name of the problem.

  • plot_type (PlotType) – Type of plot to produce. Valid options include: - ALL: All estimated progress curves. - MEAN: Estimated mean progress curve. - QUANTILE: Estimated beta quantile progress curve. - SOLVE_TIME_CDF: CDF of solve time. - CDF_SOLVABILITY: CDF solvability profile. - QUANTILE_SOLVABILITY: Quantile solvability profile. - DIFFERENCE_OF_CDF_SOLVABILITY: Difference of CDF solvability profiles. - DIFFERENCE_OF_QUANTILE_SOLVABILITY: Difference of quantile solvability profiles. - AREA: Area scatterplot. - TERMINAL_SCATTER: Scatterplot of mean and std dev of terminal progress. - FEASIBILITY_SCATTER: Scatterplot of terminal objective vs feasibility. - FEASIBILITY_VIOLIN: Violin plot of terminal feasibility. - ALL_FEASIBILITY_PROGRESS: Feasibility progress curves for all macroreps. - MEAN_FEASIBILITY_PROGRESS: Mean feasibility progress curve. - QUANTILE_FEASIBILITY_PROGRESS: Quantile feasibility progress curve.

  • normalize (bool) – Whether to normalize with respect to optimality gaps.

  • extra (float | list[float], optional) – Extra number(s) specifying quantile (e.g., beta) and/or solve tolerance.

  • plot_title (str | None, optional) – If provided, overrides the default title and filename.

  • ext (str, optional) – File extension for the saved plot. Defaults to “.png”.

  • save_as_pickle (bool, optional) – Whether to save the plot as a pickle file. Defaults to False.

Returns:

Path pointing to the location where the plot will be saved.

Return type:

Path

simopt.plots.utils.check_common_problem_and_reference(experiments: list[simopt.experiment.ProblemSolver]) → None

Check if a collection of experiments share the same problem, x0, and x*.

Parameters:

experiments (list[ProblemSolver]) – Problem-solver pairs of different solvers on a common problem.

Raises:

ValueError – If any experiments have different problem instances, starting solutions (x0), or optimal solutions (x*).

simopt.plots.utils.plot_bootstrap_conf_ints(bs_conf_int_lower_bounds: simopt.curve.Curve, bs_conf_int_upper_bounds: simopt.curve.Curve, color_str: str = 'C0') → None

Plot bootstrap confidence intervals.

Parameters:

  • bs_conf_int_lower_bounds (Curve) – Lower bounds of bootstrap confidence intervals, as curves.

  • bs_conf_int_upper_bounds (Curve) – Upper bounds of bootstrap confidence intervals, as curves.

  • color_str (str, optional) – String indicating line color, e.g., “C0”, “C1”, etc. Defaults to “C0”.

simopt.plots.utils.report_max_halfwidth(curve_pairs: list[list[simopt.curve.Curve]], normalize: bool, conf_level: float, difference: bool = False) → None

Print caption for the max halfwidth of bootstrap confidence interval curves.

Parameters:

  • curve_pairs (list[list[Curve]]) – A list of paired bootstrap CI curves.

  • normalize (bool) – Whether to normalize progress curves with respect to optimality gaps.

  • conf_level (float) – Confidence level for confidence intervals (must be in (0, 1)).

  • difference (bool, optional) – Whether the plot is for difference profiles. Defaults to False.

Raises:

ValueError – If conf_level is not in (0, 1) or if curve_pairs is empty.