Evaluating Non-linear Function Values and Derivatives

Methods for computing the values and derivatives for non-linear functions.

The first callback routine described in this section, FDEval, defines the nonlinearities of the model by returning numerical values. It must be defined by the modeler and registered with COIDEF_FDEval() if the model is nonlinear, i.e. if COIDEF_NumNlNz() has been called with a nonzero value of NumNlNZ. The routine is called repeatedly during the optimization so it should be implemented efficiently. Some arguments are provided by CONOPT. The remaining arguments must be defined by the modeler. Note that FDEval works on one row or equation at a time.

The second callback routine described in this section, FDEvalIni, is optional. If FDEvalIni is registered, it will be called each time the point of interest has changed, and it will define the coming point and tell which constraints CONOPT will need during the following calls to FDEval. FDEvalIni can for example be used to transfer the point used by CONOPT into a format recognized by the modeler, or to optimize the computation of common terms that appear in several constraints.

The third callback routine, FDEvalEnd, is optional. If FDEvalEnd is registered, it will be called at the end of the function evaluation stage. This can be used to clean up any user data generated, such as in FDEvalIni, that was used to improve the efficiency of the function and derivative evaluation.

The last callback routine described in this section, FDInterval, defines intervals for the nonlinearities of the model, again by returning numerical values. It can optionally be defined by the modeler and registered with COIDEF_FDInterval(). The routine is used to improve the quality of the preprocessing phase. It is not called very often so efficiency is not important.

FDEval – Function and Derivative Evaluator

Note

This is a mandatory callback if the model has nonlinear parts.

int COI_CALLCONV FDEval( double* X, double* G, double* JAC, 
        int* ROWNO, int* JCNM, int* MODE, int* IGNERR, 
        int* ERRCNT, int* N, int* NJ, void* USRMEM );

where:

• X: Vector with the point of evaluation. The point is provided by CONOPT.
• G: Scalar function value: The value of G must be returned by the modeler if MODE = 1 or 3, otherwise it will be ignored. If FVincLin defined in COIDEF_FVincLin() is 0, the default value, then G should return the sum of the nonlinear terms in row number ROWNO, and if FVincLin is 1 then G should return the sum of both linear and nonlinear terms. The nonlinear terms are defined as all terms that correspond to Jacobian elements with NLFLAG = 1 when loading the model. Constant terms in nonlinear constraints may be included in G provided RHS in ReadMatrix is adjusted correspondingly. Constant terms in linear constraints may also be defined here provided FVforAll is given the non default value 1 in COIDEF_FVforAll(). In summary, G should include the following, depending on FVincLin and FVforAll:

FVforAll \ FVincLin	0	1
0	G includes nonlinear terms only. FDEval is only called for nonlinear rows.	G includes linear and nonlinear terms. FDEval is only called for nonlinear rows.
1	G includes nonlinear and constant terms. FDEval is called for all rows.	G includes linear, nonlinear, and constant terms. FDEval is called for all rows.

• JAC: Vector of Jacobian values. All the nonlinear Jacobian values in row number ROWNO (and only these) should be evaluated. The indices in JAC are the indices of the variables, i.e. the derivative with respect to X(I) should be returned in JAC(I). JAC must be returned by the modeler if MODE = 2 or 3; otherwise it must be ignored.

• ROWNO: Scalar with the number of the row for which nonlinearities are to be evaluated. Is provided by CONOPT. Note that if FVforAll = 0, the default value, then FDEval will only be called for nonlinear rows, and constant terms in linear rows must therefore be included in RHS in ReadMatrix. If FVforAll = 1 then FDEval will be called for all rows, and the linear constraints must return any constant term that is not included in the right hand side. CONOPT will initialize G to zero so FDEval can just return for linear rows without constant terms. In summary, FDEval will be called for the following values of ROWNO, depending on FVforAll:

  • 0: Called for all nonlinear rows only.
  • 1: Called for all rows.

  The row numbers are consistent with the Base selected by the modeler.

• JCNM: Vector with a list of column numbers for the nonlinear nonzero Jacobian elements in the current row. It is only defined when MODE = 2 or 3. JCNM and NJ are provided for modelers that may find this information useful; it can be ignored by others. The numbers are consistent with the Base (Fortran or C conventions) selected by the modeler.
• MODE: Scalar indicator for mode of evaluation, provided by CONOPT:
  • 1: Only evaluate the sum of the nonlinear terms (and possibly linear terms) in row ROWNO and return the value in G.
  • 2: Only evaluate the nonlinear Jacobian elements in row ROWNO and return them in JAC.
  • 3: Perform both option 1 and 2.
• IGNERR: Scalar that indicates whether CONOPT assumes the point to be safe (0) or potentially unsafe (1). During certain parts of the optimization CONOPT will make very long steps and it is not unlikely that one of the constraints is not defined. If an error is encountered while IGNERR is 1, this error is not included in the ErrLim limit, and the modeler may skip any error messages that otherwise should be issued from FDEval.
• ERRCNT: Scalar Function Evaluation Error Indicator. FDEval must set this argument to 1 each time a function value cannot be computed. The counts are accumulated by CONOPT (except when IGNERR = 1). If their sum exceeds the ErrLim value defined in COIDEF_ErrLim(), CONOPT will stop the optimization, communicate the solution to the modeler with solver status SOLSTA = 5 (Evaluation Error Limit) in callback routine Status, and return control to the modeler. If ERRCNT has been set by FDEval then G and JAC will not be used and CONOPT will in general try to backtrack to a "safe" point. Note that CONOPT assumes that all functions are defined for all values of the variables between their bounds. CONOPT will never call FDEval with X outside the bounds specified in ReadMatrix. Also see the Progress callback routine for an alternative way of stopping CONOPT.

• NEWPT: Scalar new point indicator, provided by CONOPT:

  • 0: This is the same point as in last call, i.e. ROWNO has changed but the nonlinear variables in X have not changed. Some variables that are linear in all constraints may also have been changed.
  • 1: This is a new point.

  NEWPT is provided by CONOPT as a service to the modeler. It may be used to calculate and reuse terms that depend on X but are common among several equations, e.g. when some of the equations represent simultaneous sets of differential equations solved by an expensive integration routine.

• N: Number of variables as defined in COIDEF_NumVar().
• NJ: Number of nonlinear nonzero Jacobian elements in the current row and number of elements in the JCNM vector. JCNM is only defined when MODE = 2 or 3; when MODE = 1 then NJ has the value 1 and JCNM points to a random vector.
• THREAD: In some multi-threading environments multiple copies of FDEval can be called at the same time, (see Multi Threading). THREAD will hold the number of the thread for the current call of FDEval. THREAD is in the interval from 0 to the maximum number of threads allowed for FDEval.
• USRMEM: User memory as defined in COIDEF_UsrMem() (Only for Fortran and C API).

You should notice the difference between the ERRCNT and the return code of FDEval. A nonzero value returned in ERRCNT indicates that the current point defined in X is bad. The function value G or the derivatives JAC could not be computed and CONOPT should try to backtrack to a safe point. A nonzero value returned as the value of FDEval indicates that there is a serious or permanent error and there is no reason to continue the optimization. The return code on FDEval can for example be used if a data file is not found, or if FDEval is called with a value of ROWNO that was not expected.

FDEvalIni – Function and Derivative Evaluator Initialization

int COI_CALLCONV FDEvalIni( double* X, int* ROWLIST, int* MODE, 
        int* LISTSIZE, int* NUMTHREAD, int* IGNERR, 
        int* ERRCNT, int* N, void* USRMEM );

where:

• X: Vector with the point of evaluation for the future FDEval calls. The point is provided by CONOPT.
• ROWLIST: List of the constraints that will be evaluated in the future FDEval calls.
• MODE: Scalar indicator for mode of evaluation for future FDEval calls, provided by CONOPT. See MODE above.
• LISTSIZE: The number of elements in ROWLIST, defined by CONOPT.
• NUMTHREAD: The number of threads that will be used for the following FDEval calls.
• IGNERR: Scalar that indicates whether CONOPT assumes the point to be safe (0) or potentially unsafe (1), see above.
• ERRCNT: Scalar Function Evaluation Error Indicator. Either FDEvalIni or FDEval must set this argument to 1 if a function value cannot be computed. If ERRCNT has been set by FDEvalIni then CONOPT will not call FDEval in the same point. Otherwise, see FDEval for a discussion of ERRCNT.
• N: Number of variables as defined in COIDEF_NumVar().
• USRMEM: User memory as defined in COIDEF_UsrMem() (Only for Fortran and C API).

FDEvalEnd – Function and Derivative Evaluator Termination

int COI_CALLCONV FDEvalEnd( int* IGNERR, int* ERRCNT, 
        void* USRMEM );

where:

• IGNERR: Scalar that indicates whether CONOPT assumes the point to be safe (0) or potentially unsafe (1), see FDEval above.
• ERRCNT: Scalar Function Evaluation Error Indicator. Either FDEvalIni or FDEval must set this argument to 1 if a function value cannot be computed. If ERRCNT has been set by FDEvalIni then CONOPT will not call FDEval in the same point. Otherwise, see FDEval for a discussion of ERRCNT.
• USRMEM: User memory as defined in COIDEF_UsrMem() (Only for Fortran and C API).

FDInterval – Function and Derivative Interval Evaluator

CONOPT can take advantage of interval information during its preprocesing phase. If the user can provide intervals for function values and/or derivatives values as a function of intervals for the variables, then CONOPT may perform more efficiently. The intervals must be defined in a callback routine that must be registered with the COIDEF_FDInterval() routine.

int COI_CALLCONV FDInterval( double* XMIN, double* XMAX, 
        double* GMIN, double* GMAX, double* JMIN, 
        double* JAMX, int* ROWNO, int* JCNM, 
        int* MODE, double* PINF, int* N, int* NJ, 
        void* USRMEM );

where:

• XMIN: Vector of lower bound on the variables. Provided by CONOPT.
• XMAX: Vector of upper bound on the variables. Provided by CONOPT
• GMIN: Scalar. If MODE = 1 or 3 then a lower bound on the function value in constraint ROWNO may be returned in GMIN.
• GMAX: Scalar. If MODE = 1 or 3 then a upper bound on the function value in constraint ROWNO may be returned in GMAX.
• JMIN: If MODE = 2 or 3 then a lower bound on the derivatives of the function value in constraint ROWNO with respect to the variable I may be returned in JMIN(I).
• JMAX: If MODE = 2 or 3 then an upper bounds on the derivatives of the function value in constraint ROWNO with respect to the variable I may be returned in JMAX(I).
• ROWNO: The number of the current constraint. FDInterval will only be called for nonlinear constraints.
• JCNM: List of column numbers for the nonlinear nonzero Jacobian elements in the current row. It is only defined when MODE = 2 or 3. When MODE = 1 NJ has the value 1 and JCNM points to a random vector. JCNM and NJ are provided for modelers that may find this information useful; it can be ignored by others.
• MODE: Indicator for mode of evaluation, provided by CONOPT:
  • 1: Only evaluate the bounds on the sum of the nonlinear terms in row ROWNO and return the interval in [GMIN, GMAX].
  • 2: Only evaluate the bounds on the nonlinear Jacobian elements in row ROWNO and return the intervals in [JMIN, JMAX].
  • 3: Perform both option 1 and 2. (Currently, MODE = 3 is not used).
• PINF: Plus Infinity. XMAX uses the special PINF to represent no upper bound and XMIN uses -PINF to represent no lower bound. Provided by CONOPT.
• N: Number of variables in the model.
• NJ: Number of nonlinear nonzero Jacobian elements in the current row and number of elements in the JCNM vector. JCNM is only defined when MODE = 2 or 3; when MODE = 1 then NJ has the value 1 and JCNM points to a random vector.
• USRMEM: User memory as defined in COIDEF_UsrMem() (Only for Fortran and C API).

There are a few points to note:

1. FDInterval works on one constraint at a time.
2. CONOPT will initialize GMIN to –PINF, GMAX to +PINF and similarly for the relevant elements in JMIN and JMAX. Therefore, if you do not have a bound on a function or a derivative value or if the value is infinite, then ignore the return value (or use –PINF and +PINF).
3. Currently FDInterval does not use FVincLin and FVforAll which means that GMIN and GMAX only should include information about nonlinear terms.
4. There is no error counter similar to ERRCNT in FDEval. If there are potential function evaluation errors in an interval this will usually translate into the lower and/or upper bounds being infinite.