naginterfaces.library.opt.handle_​disable

naginterfaces.library.opt.handle_disable(handle, comp, idx)

handle_disable is a part of the NAG optimization modelling suite and allows you to disable various components of an existing model.

For full information please refer to the NAG Library document for e04tc

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/e04/e04tcf.html

Parameters

handleHandle

The handle to the problem. It needs to be initialized (e.g., by handle_init()) and must not be changed between calls to the NAG optimization modelling suite.

compstr

The type of the component of the model to be disabled. $comp$ is case insensitive.

$comp=\text{'X'}$, $\text{'VAR'}$ or $\text{'VARIABLE'}$

Decision variables $x$.

$comp=\text{'LC'}$ or $\text{'LINEAR CONSTRAINT'}$

Linear constraints (see handle_set_linconstr()).

$comp=\text{'QC'}$ or $\text{'QUADRATIC CONSTRAINT'}$

Quadratic constraints (see handle_set_qconstr() and handle_set_qconstr_fac()).

$comp=\text{'NLC'}$ or $\text{'NONLINEAR CONSTRAINT'}$

Nonlinear constraints (see handle_set_nlnconstr()).

$comp=\text{'CN'}$ or $\text{'CONE'}$

Quadratic or rotated quadratic cones (see handle_set_group()).

$comp=\text{'MI'}$ or $\text{'MATRIX INEQUALITY'}$

Matrix inequality constraints (see handle_set_linmatineq()).

$comp=\text{'NLS'}$ or $\text{'RESIDUAL'}$

Nonlinear residuals $r_i\left(x\right)$ in the nonlinear least squares objective function (see handle_set_nlnls()).

idxint, array-like, shape $\left(\text{lidx}\right)$

The index set of components $comp$ to be disabled. The elements may be supplied in any order.

Raises

NagValueError

(errno $1$)

$handle$ has not been initialized.

(errno $1$)

$handle$ does not belong to the NAG optimization modelling suite, has not been initialized properly or is corrupted.

(errno $1$)

$handle$ has not been initialized properly or is corrupted.

(errno $2$)

The problem cannot be modified right now, the solver is running.

(errno $5$)

On entry, $\text{lidx}=⟨value⟩$.

Constraint: $\text{lidx}\ge 1$.

(errno $6$)

On entry, $comp=⟨value⟩$.

Constraint: $comp=\text{'X'}$, $\text{'LC'}$, $\text{'QC'}$, $\text{'NLC'}$, $\text{'CN'}$, $\text{'MI'}$ or $\text{'NLS'}$.

(errno $8$)

On entry, $comp=⟨value⟩$, $i=⟨value⟩$, $idx[i-1]=⟨value⟩$ and $M=⟨value⟩$.

Constraint: $1\le idx[i-1]\le M$.

(errno $9$)

On entry, $comp=⟨value⟩$ and $idx[i-1]=⟨value⟩$.

This component has been deleted.

Notes

handle_disable and handle_enable() form a pair of functions which allow you to quickly remove parts of the model and add them back. This is particularly useful when a sequence of similar problems needs to be solved, to identify how a particular constraint or variable affects the solution, or to switch between previously defined constraints which are somewhat related to each other.

After the model has been fully or partially built by calling functions of the NAG optimization modelling suite, handle_disable may be used to disable some components (variables or constraints) from the model. To identify the part of the model to be disabled, the component type needs to be specified in $comp$ together with the appropriate component indices, such as variable or linear constraint numbers, in an index set $idx$. handle_enable() may be used to bring them back (to enable them). Note that a disabled component may still be edited but would not be automatically re-enabled; a disabled component can only be enabled by calling handle_enable(). By default, all newly created components of the model are enabled. Calling this function on disabled components is not an error but has no effect.

In general, disabled components are still present in the model with respect to the numbering of the variables and constraints (e.g., disabling a variable will not renumber the remaining variables) but the solver will ignore them and work internally with a smaller model formulation. The solver will communicate with you (e.g., return results) in arrays matching the full size of the model and the elements corresponding to the disabled components will be set to NaN, which can be tested for via a call to ieee.is_nan. The effect of disabling components is described in detail as follows:

Decision variables

As a rule, a disabled variable behaves as if the existing parts of the model were defined without the variable in the first place. Matching elements in all other model components are ignored. In particular, the following applies:

• elements in the linear or quadratic objective function corresponding to the disabled variables are ignored, as if they were set to 0;

• the same applies to the linear and quadratic constraints as well as to the matrix inequalities, however, note that this can generate infeasible constraints (for instance, $-2\le x+y\le -1$ with disabled $x$ and $y$ is interpreted as $-2\le 0\le -1$ and thus would be infeasible);

• the box bounds of the disabled variables are ignored;

• if a disabled variable is present in a cone constraint and the cone constraint becomes invalid (e.g., the length of the cone is just one or the first cone variable is disabled), the whole constraint is disabled as well;

• any callbacks for nonlinear function evaluation will have on input the full $x$ vector, however, all disabled variables are set to NaN and the matching elements in the returned derivatives are not referenced.

An alternative approach is to fix the variable to a predefined value by changing its simple bounds using handle_set_bound() instead of disabling it.

Linear constraints, Quadratic constraints, Second-order cones, Matrix inequalities

Disabled constraints do not restrict the feasible set, they are eliminated before the model is presented to the solver. As the constraints are not renumbered, the position for Lagrangian multipliers ($\text{u}$, $\text{uc}$, $\text{ua}$) is unchanged and NaNs are returned in place of disabled constraints.

Nonlinear constraints

The disabled nonlinear constraints do not affect the feasible set and their Lagrangian multipliers are returned as NaNs in their expected location. The values of the nonlinear constraints and their partial derivatives are passed to the solver via callbacks, such as, $\text{objfun}$ and $\text{objgrd}$. The size of all array arguments in the callbacks remain the same, irrespective of the number of disabled constraints. On exit from the callback any elements in these arrays corresponding to the disabled constraints are not referenced.

Nonlinear residuals

The disabled residuals in the nonlinear least squares objective function $\sum r_j^2\left(x\right)$ are skipped in the sum and their values are not referenced.

See the E04 Introduction for more details about the NAG optimization modelling suite.

See also

naginterfaces.library.examples.opt.handle_disable_ex.main()