corneto.methods.sampler.sample_alternative_solutions#

corneto.methods.sampler.sample_alternative_solutions(problem, variable_name, *, percentage=0.1, scale=0.05, rel_opt_tol=0.1, max_samples=30, perturbation_name='perturbation', solver_kwargs=None, rng=None, collect_vars=None, exclude_objectives_pattern='regularization', verbose=1)#

Generate alternative feasible solutions by perturbing one decision variable.

This routine takes an optimization problem (with attributes .expr, .solve() and .objectives), identifies a target variable within it, and generates up to max_samples new feasible solutions by randomly perturbing a fraction of that variable’s entries. Only those perturbations that keep all original, non-excluded objectives within a relative tolerance of the baseline are accepted.

Parameters:

  • problem – An optimization problem instance exposing: - expr: mapping of variable names to variable objects - solve(…): method to solve the problem - objectives: list of objective objects (each with .name and .value)

  • variable_name (str) – Name of the variable in problem.expr to perturb.

  • percentage (float, optional) – Fraction of the variable’s entries to perturb in each trial. Defaults to 0.10.

  • scale (float, optional) – Standard deviation of the normal random noise. Defaults to 0.03.

  • rel_opt_tol (float, optional) – Maximum allowed relative deviation of any original, non-excluded objective from its baseline value. Defaults to 0.05.

  • max_samples (int, optional) – Maximum number of perturbation trials to attempt. Defaults to 30.

  • perturbation_name (str, optional) – Name to assign to the added perturbation objective. Defaults to “perturbation”.

  • solver_kwargs (dict | None, optional) – Extra keyword arguments passed to problem.solve(). Defaults to None.

  • rng (np.random.Generator | int | None, optional) – Random number generator or seed for reproducibility. Defaults to None.

  • collect_vars (Sequence[str] | None, optional) – Names of the variables whose values you want returned. If None, collect every variable in problem.expr. An empty list collects none; otherwise, collect only the named variables.

  • exclude_objectives_pattern (str | None, optional) – A regular-expression pattern. Objectives whose names match this pattern will be excluded from the relative-error tolerance check. If None, no objectives are excluded. Defaults to “regularization”.

  • verbose (int, optional) – Verbosity level: - 0: silent - 1: summary - 2: full detail Defaults to 1.

Returns:

A mapping from each collected variable name to a NumPy array of shape (n_samples, …), where the remaining axes match the variable shape: - n_samples ≥ 1 counts the incumbent plus every accepted perturbation - the remaining dimensions match the variable’s own shape

Example:

out = sample_alternative_solutions(problem, “x”, collect_vars=[“x”, “y”]) x_stack = out[“x”] # leading axis indexes samples incumbent_x = x_stack[0] # first slice is always the baseline

Return type:

dict[str, np.ndarray]

Raises:

KeyError – If variable_name is not in problem.expr, or if any name in collect_vars is missing from problem.expr.