NAG FL Interface
e04tcf (handle_​disable)

Settings help

FL Name Style:


FL Specification Language:


1 Purpose

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

2 Specification

Fortran Interface
Subroutine e04tcf ( handle, comp, lidx, idx, ifail)
Integer, Intent (In) :: lidx, idx(lidx)
Integer, Intent (Inout) :: ifail
Character (*), Intent (In) :: comp
Type (c_ptr), Intent (In) :: handle
C Header Interface
#include <nag.h>
void  e04tcf_ (void **handle, const char *comp, const Integer *lidx, const Integer idx[], Integer *ifail, const Charlen length_comp)
The routine may be called by the names e04tcf or nagf_opt_handle_disable.

3 Description

e04tcf and e04tbf form a pair of routines 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 routines of the NAG optimization modelling suite, e04tcf 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. e04tbf 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 e04tbf. By default, all newly created components of the model are enabled. Calling this routine 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 x07abf. 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, −2x+y−1 with disabled x and y is interpreted as −20−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 e04tdf 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 (u, uc, 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, objfun and 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 rj2(x) are skipped in the sum and their values are not referenced.
See Section 3.1 in the E04 Chapter Introduction for more details about the NAG optimization modelling suite.

4 References

None.

5 Arguments

1: handle Type (c_ptr) Input
On entry: the handle to the problem. It needs to be initialized (e.g., by e04raf) and must not be changed between calls to the NAG optimization modelling suite.
2: comp Character(*) Input
On entry: the type of the component of the model to be disabled. comp is case insensitive.
comp='X', 'VAR' or 'VARIABLE'
Decision variables x.
comp='LC' or 'LINEAR CONSTRAINT'
Linear constraints (see e04rjf).
comp='QC' or 'QUADRATIC CONSTRAINT'
Quadratic constraints (see e04rsf and e04rtf).
comp='NLC' or 'NONLINEAR CONSTRAINT'
Nonlinear constraints (see e04rkf).
comp='CN' or 'CONE'
Quadratic or rotated quadratic cones (see e04rbf).
comp='MI' or 'MATRIX INEQUALITY'
Matrix inequality constraints (see e04rnf).
comp='NLS' or 'RESIDUAL'
Nonlinear residuals ri(x) in the nonlinear least squares objective function (see e04rmf).
Constraint: comp='X', 'VAR', 'VARIABLE', 'LC', 'LINEAR CONSTRAINT', 'QC', 'QUADRATIC CONSTRAINT', 'NLC', 'NONLINEAR CONSTRAINT', 'CN', 'CONE', 'MI', 'MATRIX INEQUALITY', 'NLS' or 'RESIDUAL'.
3: lidx Integer Input
On entry: the number of elements in the index set.
Constraint: lidx1.
4: idx(lidx) Integer array Input
On entry: the index set of components comp to be disabled. The elements may be supplied in any order.
Constraint: 1idx(i)M, for i=1,2,,lidx , where M is the total number of the given components (e.g., decision variables) in the problem.
5: ifail Integer Input/Output
On entry: ifail must be set to 0, −1 or 1 to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of 0 causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of −1 means that an error message is printed while a value of 1 means that it is not.
If halting is not appropriate, the value −1 or 1 is recommended. If message printing is undesirable, then the value 1 is recommended. Otherwise, the value −1 is recommended. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry ifail=0 or −1, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
ifail=1
The supplied handle does not define a valid handle to the data structure for the NAG optimization modelling suite. It has not been properly initialized or it has been corrupted.
ifail=2
The problem cannot be modified right now, the solver is running.
ifail=5
On entry, lidx=value.
Constraint: lidx1.
ifail=6
On entry, comp=value.
Constraint: comp='X', 'LC', 'QC', 'NLC', 'CN', 'MI' or 'NLS'.
ifail=8
On entry, comp=value, i=value, idx(i)=value and M=value.
Constraint: 1idx(i)M.
ifail=9
On entry, comp=value and idx(i)=value.
This component has been deleted.
This error can only occur when trying to enable a cone constraint that has been deleted by setting its size to 0 with e04rbf.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
e04tcf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example shows how to use the NAG optimization modelling suite to edit a nonlinear least squares problem. In particular, outlier data is disabled in the NAG handle without having to redefine the full problem.
We use e04ggf to fit a nonlinear least squares problem of the form
minimize xp i=1 30 (f(ti,x)-yi)2  
where p=5, x=(a,b,c,d,ω) and f(t)=at2+bt+c+dsin(ωt) to some simulated data {(ti,yi)}.
Thirty data points were simulated using (a=0.3,b=1.0,c=0.01,d=0.2,ω=5.0) with ti uniformly spread in [-1.0,1.0] and yi=f(ti,x)+εi where εi is random noise. In addition two data points, y10 and y20, were modified to simulate the presence of outlier data.
We show how to solve three variants of the same problem:

10.1 Program Text

Program Text (e04tcfe.f90)

10.2 Program Data

Program Data (e04tcfe.d)

10.3 Program Results

Program Results (e04tcfe.r)