optiprofiler.Feature

Contents

optiprofiler.Feature#

class optiprofiler.Feature(name, **feature_options)[source]#

Mapping from an optimization problem to a new one with specified features.

We are interested in testing solvers on problems with different features. For example, we may want to test the performance of solvers when the objective function is noisy. For this purpose, we define the Feature class.

Suppose we have an optimization problem

\[\begin{split}\min \quad & \mathrm{fun}(x) \\ \text{s.t.} \quad & x_l \le x \le x_u, \\ & A_{\mathrm{ub}} x \le b_{\mathrm{ub}}, \\ & A_{\mathrm{eq}} x = b_{\mathrm{eq}}, \\ & c_{\mathrm{ub}}(x) \le 0, \\ & c_{\mathrm{eq}}(x) = 0, \\ & \text{with initial point } x_0.\end{split}\]

Then Feature maps the above problem to the following one:

\[\begin{split}\min \quad & \mathrm{fun\_mod}(Ax + b) \\ \text{s.t.} \quad & x_{l,\mathrm{mod}} \le Ax + b \le x_{u,\mathrm{mod}}, \\ & A_{\mathrm{ub,mod}} (Ax + b) \le b_{\mathrm{ub,mod}}, \\ & A_{\mathrm{eq,mod}} (Ax + b) = b_{\mathrm{eq,mod}}, \\ & c_{\mathrm{ub,mod}}(Ax + b) \le 0, \\ & c_{\mathrm{eq,mod}}(Ax + b) = 0, \\ & \text{with initial guess } x_{0,\mathrm{mod}},\end{split}\]

where the modified quantities are determined by the chosen feature name and options.

Parameters:
namestr

Name of the feature. Must be one of the following:

  1. 'plain' : do nothing to the optimization problem.

  2. 'perturbed_x0' : perturb the initial guess x0.

  3. 'noisy' : add noise to the objective function and nonlinear constraints.

  4. 'truncated' : truncate values of the objective function and nonlinear constraints to a given number of significant digits.

  5. 'permuted' : randomly permute the variables. The bounds and linear constraints are modified accordingly so that the new problem is mathematically equivalent to the original one.

  6. 'linearly_transformed' : apply an invertible linear transformation D @ Q' (with D diagonal and Q orthogonal) to the variables. Bounds and linear constraints are modified accordingly.

  7. 'random_nan' : randomly replace values of the objective function and nonlinear constraints with NaN.

  8. 'unrelaxable_constraints' : set the objective function to Inf outside the feasible region.

  9. 'nonquantifiable_constraints' : replace values of nonlinear constraints with either 0 (satisfied) or 1 (violated).

  10. 'quantized' : quantize the objective function and nonlinear constraints.

  11. 'custom' : user-defined feature.

**feature_optionsdict

Keyword arguments for the feature. The available options depend on the chosen name:

  • n_runs (int) – Number of runs of the experiment under the given feature. Default is 5 for stochastic features and 1 for deterministic features. Valid for all features.

  • distribution (str or callable) – Distribution of perturbation ('perturbed_x0') or noise ('noisy'). For 'perturbed_x0', it should be 'spherical' (default) or 'gaussian'. For 'noisy', it should be 'gaussian' (default) or 'uniform'. It can also be a callable (rng, dimension) -> array.

  • perturbation_level (float) – Magnitude of the perturbation in 'perturbed_x0'. Default is 1e-3.

  • noise_level (float) – Magnitude of the noise in 'noisy'. Default is 1e-3.

  • noise_type (str) – Type of the noise in 'noisy'. Must be 'absolute', 'relative', or 'mixed' (default).

  • significant_digits (int) – Number of significant digits in 'truncated'. Default is 6.

  • perturbed_trailing_digits (bool) – Whether to randomize the trailing digits in 'truncated'. Default is False.

  • rotated (bool) – Whether to use a random rotation matrix in 'linearly_transformed'. Default is True.

  • condition_factor (float) – Scaling factor of the condition number of the linear transformation in 'linearly_transformed'. The condition number will be 2 ** (condition_factor * n / 2). Default is 0.

  • nan_rate (float) – Probability that an evaluation returns NaN in 'random_nan'. Default is 0.05.

  • unrelaxable_bounds (bool) – Whether bound constraints are unrelaxable in 'unrelaxable_constraints'. Default is True.

  • unrelaxable_linear_constraints (bool) – Whether linear constraints are unrelaxable. Default is False.

  • unrelaxable_nonlinear_constraints (bool) – Whether nonlinear constraints are unrelaxable. Default is False.

  • mesh_size (float) – Size of the mesh in 'quantized'. Default is 1e-3.

  • mesh_type (str) – Type of the mesh in 'quantized'. Must be 'absolute' (default) or 'relative'.

  • ground_truth (bool) – Whether the featured problem is the ground truth in 'quantized'. Default is True.

  • mod_x0 (callable) – Modifier for the initial guess in 'custom': (rng, problem) -> modified_x0.

  • mod_affine (callable) – Modifier for the affine transformation in 'custom': (rng, problem) -> (A, b, inv).

  • mod_bounds (callable) – Modifier for the bounds in 'custom': (rng, problem) -> (xl, xu).

  • mod_linear_ub (callable) – Modifier for the linear inequality constraints in 'custom': (rng, problem) -> (aub, bub).

  • mod_linear_eq (callable) – Modifier for the linear equality constraints in 'custom': (rng, problem) -> (aeq, beq).

  • mod_fun (callable) – Modifier for the objective function in 'custom': (x, rng, problem) -> modified_fun.

  • mod_cub (callable) – Modifier for the nonlinear inequality constraints in 'custom': (x, rng, problem) -> modified_cub.

  • mod_ceq (callable) – Modifier for the nonlinear equality constraints in 'custom': (x, rng, problem) -> modified_ceq.

See also

Problem

Optimization problem.

FeaturedProblem

Problem equipped with a specific feature.

benchmark

Main benchmarking function.

Notes

Different feature names accept different subsets of options. The valid options for each feature name are:

  1. 'plain' : n_runs.

  2. 'perturbed_x0' : n_runs, distribution, perturbation_level.

  3. 'noisy' : n_runs, distribution, noise_level, noise_type.

  4. 'truncated' : n_runs, significant_digits, perturbed_trailing_digits.

  5. 'permuted' : n_runs.

  6. 'linearly_transformed' : n_runs, rotated, condition_factor.

  7. 'random_nan' : n_runs, nan_rate.

  8. 'unrelaxable_constraints' : n_runs, unrelaxable_bounds, unrelaxable_linear_constraints, unrelaxable_nonlinear_constraints.

  9. 'nonquantifiable_constraints' : n_runs.

  10. 'quantized' : n_runs, mesh_size, mesh_type, ground_truth.

  11. 'custom' : n_runs, mod_x0, mod_affine, mod_bounds, mod_linear_ub, mod_linear_eq, mod_fun, mod_cub, mod_ceq.

Examples

Create a plain feature (no modification to problems):

from optiprofiler import Feature

feature = Feature('plain')
print(feature.name)           # 'plain'
print(feature.is_stochastic)  # False

Create a noisy feature with custom noise level:

feature = Feature('noisy', noise_level=1e-2, noise_type='relative')
print(feature.is_stochastic)  # True
print(feature.options)
Attributes:
namestr

Name of the feature.

optionsdict

Options of the feature.

is_stochasticbool

Whether the feature is stochastic.

Methods

modifier_x0(seed, problem)

Modify the initial guess.

modifier_affine(seed, problem)

Generate an invertible matrix A, a vector b, and the inverse of A for the affine transformation applied to the variables.

modifier_bounds(seed, problem)

Modify the lower and upper bounds.

modifier_linear_ub(seed, problem)

Modify the linear inequality constraints.

modifier_linear_eq(seed, problem)

Modify the linear equality constraints.

modifier_fun(x, seed, problem, n_eval)

Modify the objective function value.

modifier_cub(x, seed, problem, n_eval_cub)

Modify the values of the nonlinear inequality constraints.

modifier_ceq(x, seed, problem, n_eval_ceq)

Modify the values of the nonlinear equality constraints.
Contents