CONOPT
Loading...
Searching...
No Matches
Functions
Registration of options
The public API of CONOPT » C API » Initialisation Methods

Functions

int COI_CALLCONV COIDEF_License (coiHandle_t cntvect, int licint1, int licint2, int licint3, const char *licstring)
 define the License Information.
 
int COI_CALLCONV COIDEF_Base (coiHandle_t cntvect, int base)
 define the Base index for vectors.
 
int COI_CALLCONV COIDEF_Fortran (coiHandle_t cntvect)
 define Fortran Conventions for Argument Passing.
 
int COI_CALLCONV COIDEF_C (coiHandle_t cntvect)
 define C Conventions for Argument Passing.
 
int COI_CALLCONV COIDEF_ItLim (coiHandle_t cntvect, int itlim)
 define the Iteration Limit.
 
int COI_CALLCONV COIDEF_ErrLim (coiHandle_t cntvect, int errlim)
 define the Error Limit.
 
int COI_CALLCONV COIDEF_ResLim (coiHandle_t cntvect, double reslim)
 define resource limit.
 
int COI_CALLCONV COIDEF_MaxHeap (coiHandle_t cntvect, double maxheap)
 define Limit on Heap Memory. ""
 
int COI_CALLCONV COIDEF_IniStat (coiHandle_t cntvect, int inistat)
 handling of the initial status values.
 
int COI_CALLCONV COIDEF_FVincLin (coiHandle_t cntvect, int fvinclin)
 include the linear terms in function evaluations.
 
int COI_CALLCONV COIDEF_FVforAll (coiHandle_t cntvect, int fvforall)
 call the FDEval for all constraints, including linear constraints.
 
int COI_CALLCONV COIDEF_MaxSup (coiHandle_t cntvect, int maxsup)
 limit on superbasics.
 
int COI_CALLCONV COIDEF_Square (coiHandle_t cntvect, int square)
 square models.
 
int COI_CALLCONV COIDEF_EmptyRow (coiHandle_t cntvect, int emptyrow)
 allow empty rows.
 
int COI_CALLCONV COIDEF_EmptyCol (coiHandle_t cntvect, int emptycol)
 allow empty columns.
 
int COI_CALLCONV COIDEF_DisCont (coiHandle_t cntvect, int discont)
 allow discontinuous functions and derivatives.
 
int COI_CALLCONV COIDEF_HessFac (coiHandle_t cntvect, double hessfac)
 factor for Hessian density relative to Jacobian density HessFac.
 
int COI_CALLCONV COIDEF_DebugFV (coiHandle_t cntvect, int debugfv)
 turn Debugging of FDEval on and off.
 
int COI_CALLCONV COIDEF_Debug2D (coiHandle_t cntvect, int debug2d)
 turn debugging of 2nd derivatives on and off.
 
int COI_CALLCONV COIDEF_ClearM (coiHandle_t cntvect, int clearm)
 ClearM.
 
int COI_CALLCONV COIDEF_ThreadS (coiHandle_t cntvect, int threads)
 number of threads allowed internally in CONOPT.
 
int COI_CALLCONV COIDEF_ThreadF (coiHandle_t cntvect, int threadf)
 number of threads allowed for simultaneous FDEval calls.
 
int COI_CALLCONV COIDEF_Thread2D (coiHandle_t cntvect, int thread2d)
 number of threads allowed for simultaneous 2DDir calls.
 
int COI_CALLCONV COIDEF_ThreadC (coiHandle_t cntvect, int threadc)
 check for thread compatibility.
 
int COI_CALLCONV COIDEF_StdOut (coiHandle_t cntvect, int tostdout)
 allow output to StdOut.
 

Detailed Description

Options that modify the macro behaviour of CONOPT.

These cover conventions for indexes COIDEF_Base() and argument passing COIDEF_Fortran() and COIDEF_C(). They also cover limits on the algorithms, such as iteration limits COIDEF_ItLim() and error limits COIDEF_ErrLim(). These options must be specified before the CONOPT solving is started, i.e before a call to COI_Solve().

Function Documentation

◆ COIDEF_License()

int COI_CALLCONV COIDEF_License ( coiHandle_t cntvect,
int licint1,
int licint2,
int licint3,
const char * licstring )

define the License Information.

The license consists of three integer codes and a string that defines the user. If the license is not defined or if it is incorrect then CONOPT will run in small-scale demo mode and it will only be able to solve small models.

Parameters
licint1the first license integer code
licint2the second license integer code
licint3the third license integer code
licstringthe license string
cntvectthe control vector

◆ COIDEF_Base()

int COI_CALLCONV COIDEF_Base ( coiHandle_t cntvect,
int base )

define the Base index for vectors.

Some of the vectors that are passed between CONOPT and the callback routines point to other vectors. Examples are Row Indices and Start of Column pointers. You must define to CONOPT if you use Fortran conventions with 1 as the first element or C conventions with 0. The base will also determine how the index of the objective is interpreted.

Parameters
cntvectthe control vector
basethe base index for vectors

◆ COIDEF_Fortran()

int COI_CALLCONV COIDEF_Fortran ( coiHandle_t cntvect)

define Fortran Conventions for Argument Passing.

This is equivalent to calling coidef_base(1) in Fortran or COIDEF_Base(1) in C.

Parameters
cntvectthe control vector

◆ COIDEF_C()

int COI_CALLCONV COIDEF_C ( coiHandle_t cntvect)

define C Conventions for Argument Passing.

This is equivalent to calling coidef_base(0) in Fortran or COIDEF_Base(0) in C.

Parameters
cntvectthe control vector

◆ COIDEF_ItLim()

int COI_CALLCONV COIDEF_ItLim ( coiHandle_t cntvect,
int itlim )

define the Iteration Limit.

By default CONOPT uses an iteration limit of 1 million iterations. This method can be used to set a new iteration limit.

The call is optional.

Parameters
itlimthe iteration limit
cntvectthe control vector

◆ COIDEF_ErrLim()

int COI_CALLCONV COIDEF_ErrLim ( coiHandle_t cntvect,
int errlim )

define the Error Limit.

The nonlinear functions may not be defined in all points, and the user written callback routine FDEval has an argument for telling CONOPT if a point is “bad”. CONOPT may try other points to avoid “bad” points up to a defined error limit (as specified by a call to this method). The default error limit is zero, i.e. CONOPT will by default stop if a “bad” point is encountered.

The call is optional.

Parameters
errlimthe error limit
cntvectthe control vector

◆ COIDEF_ResLim()

int COI_CALLCONV COIDEF_ResLim ( coiHandle_t cntvect,
double reslim )

define resource limit.

CONOPT will by default allow the optimization to run for 1 million seconds. A new limit can be set by a call to this method.

Note
ResLim is a double precision number.
Parameters
reslimthe solve time limit in seconds
cntvectthe control vector

◆ COIDEF_MaxHeap()

int COI_CALLCONV COIDEF_MaxHeap ( coiHandle_t cntvect,
double maxheap )

define Limit on Heap Memory. ""

By default CONOPT will allocate the memory it needs from the computers heap memory using Allocate or malloc calls. For very large models CONOPT may try to allocate more than the available physical memory and the responsiveness of the computer may suffer. This may not be acceptable in certain server environments. This method is used to define a limit on the amount of heap memory that CONOPT will allocate. If CONOPT reaches a point where it needs more memory than allowed it will try to continue without extra memory (if this is possible) or it will stop with an out of memory message and the sovle will return the value 113 or 114.

MaxHeap is measured in MegaBytes. A positive MaxHeap value indicates a limit while Maxheap = 0.0 indicates that the limit is set by the physical memory or the virtual memory system on the machine. After you have solved a model you can query the amount of memory actually used with the coiget_maxheapused() or COIGET_MaxHeapUsed().

The call is optional.

Parameters
maxheapthe limit on heap memory ""
cntvectthe control vector

◆ COIDEF_IniStat()

int COI_CALLCONV COIDEF_IniStat ( coiHandle_t cntvect,
int inistat )

handling of the initial status values.

CONOPT can take advantage of initial ‘Status’ information about the variables and constraints. This is information of the type: Variable number \(i\) is basic, variable \(j\) is superbasic, variable \(k\) is at lower bound etc.

Note
If you are going to provide Status information when building the model then CONOPT must be informed a call to this method with the second argument equal to 1 or 2 (depending on the definition you choose). You can turn it off again with another call with the value 0 (the default initial value).
Parameters
cntvectthe control vector
inistatthe initial status

◆ COIDEF_FVincLin()

int COI_CALLCONV COIDEF_FVincLin ( coiHandle_t cntvect,
int fvinclin )

include the linear terms in function evaluations.

CONOPT assumes that the function values returned by the user defined callback routine FDEval only include nonlinear terms, i.e. terms that correspond to variables that appear nonlinearly in the particular constraint.

If you prefer your FDEval routine to return function values as the sum of both linear and nonlinear terms then you must inform CONOPT by calling this method with FVincLin = 1. FVincLin = 0 will return CONOPT to the default behavior.

Parameters
fvinclinthe linear terms in functions
cntvectthe control vector

◆ COIDEF_FVforAll()

int COI_CALLCONV COIDEF_FVforAll ( coiHandle_t cntvect,
int fvforall )

call the FDEval for all constraints, including linear constraints.

CONOPT will usually only call the user provided FDEval routine for nonlinear constraints. However, some models may have constant terms included in FDEval instead of in the right hand side, also for linear constraints.

Note
If your FDEval routine is programmed this way you must tell CONOPT to call FDEval for all constraints, linear as well as nonlinear, by calling this method with FVforAll = 1. Calling again with FVforAll = 0 will return CONOPT to its default behavior.
Parameters
fvforallthe linear constraints in functions
cntvectthe control vector

◆ COIDEF_MaxSup()

int COI_CALLCONV COIDEF_MaxSup ( coiHandle_t cntvect,
int maxsup )

limit on superbasics.

CONOPT uses a reduced gradient algorithm and performs its optimization in a space of “Superbasic” variables. It needs a square matrix of size the number of superbasic variables for estimated second order information. Since this matrix can be fairly large, CONOPT places a limit that by default is at least 500 rows and columns. For larger models CONOPT reserves around 25% of the memory needed for other purposes to this matrix. If you have a model with many superbasic variables it may be advantageous to increase this limit.

Note
If you provide second order information, through one of the 2DLagr, 2DDir, or 2DDirLag routines, then it is usually not worth while to increase MaxSup.

The limit can also be defined in an options file or options routine by setting LFNSUP.

Parameters
maxsupthe limit on superbasics
cntvectthe control vector

◆ COIDEF_Square()

int COI_CALLCONV COIDEF_Square ( coiHandle_t cntvect,
int square )

square models.

CONOPT has a special routine for solve square sets of equations without an objective function.

Parameters
squareSquare = 1 informs CONOPT that the model is Square. Square = 0 is the default used for an ordinary optimization model.
cntvectthe control vector

◆ COIDEF_EmptyRow()

int COI_CALLCONV COIDEF_EmptyRow ( coiHandle_t cntvect,
int emptyrow )

allow empty rows.

CONOPT performs many tests on the input data and by default it does not allow empty rows, i.e. constraints that do not depend on any variables. In some modeling systems environments it can be useful to allow empty rows.

Parameters
emptyrow1 allows empty rows, 0 is the default behavior.
cntvectthe control vector

◆ COIDEF_EmptyCol()

int COI_CALLCONV COIDEF_EmptyCol ( coiHandle_t cntvect,
int emptycol )

allow empty columns.

CONOPT performs many tests on the input data and by default it does not allow empty columns, i.e. variables that do not appear in any constraints. In some modeling systems environments it can be useful to allow empty columns. To bypass the usual tests you must inform CONOPT that empty columns should be allowed.

Parameters
emptycol1 allows empty columns, 0 is the default behaviour.
cntvectthe control vector

◆ COIDEF_DisCont()

int COI_CALLCONV COIDEF_DisCont ( coiHandle_t cntvect,
int discont )

allow discontinuous functions and derivatives.

CONOPT assumes that all functions are smooth with smooth derivatives and that these functions and derivatives can be computed with a noise level close to the machine precision. CONOPT can also be used on models with non-smooth derivatives, e.g. models with ABS or MIN or MAX functions, but the algorithm will still work as if all functions and derivatives are smooth. A few internal tests may fail for a model with discontinuous derivatives. The call will only turn the tests off or on; it will not alter the optimization behavior.

Parameters
discont1 allows discontinuous functions and derivatives, 0 is the default behaviour.
cntvectthe control vector

◆ COIDEF_HessFac()

int COI_CALLCONV COIDEF_HessFac ( coiHandle_t cntvect,
double hessfac )

factor for Hessian density relative to Jacobian density HessFac.

CONOPT will not use the Hessian of the Lagrangian if it is too dense. The limit on the number of nonzero Hessian elements (on an below the diagonal) is set to HessFac times the number of nonlinear Jacobian elements,:vertical resize 120 and the default value of HessFac is 10. The assumption is that computations involving a dense Hessian will be too expensive.

The Hessian factor can also be defined by defining the option RVHESS.

Parameters
cntvectthe control vector
hessfacthe threshold factor for Hessian density relative to Jacobian density

◆ COIDEF_DebugFV()

int COI_CALLCONV COIDEF_DebugFV ( coiHandle_t cntvect,
int debugfv )

turn Debugging of FDEval on and off.

CONOPT has a Function and Derivative Debugger that can check if the function values and derivatives computed by FDEval seem to be consistent and the derivatives are consistent with the sparsity pattern of the Jacobian.

The interpretation of DebugFV is:

  • 0: No debugging (the default value)
  • -1: Perform debugging in the initial point only.
  • +n: Perform debugging every n’th iteration.

The value can also be defined in an options file or options routine be setting LKDEBG. Error messages and error return codes are described in Error Return Codes.

Parameters
debugfvthe flag to enable debugging of function evaluations
cntvectthe control vector

◆ COIDEF_Debug2D()

int COI_CALLCONV COIDEF_Debug2D ( coiHandle_t cntvect,
int debug2d )

turn debugging of 2nd derivatives on and off.

CONOPT has a rudimentary routine for checking if the 2nd derivatives computed by 2DLagr, 2DDir, or 2DDirLag seem to be consistent with the derivatives computed by FDEval.

The interpretation of Debug2D is:

  • 0: No debugging (the default value)
  • -1: Perform debugging in the initial point only.
  • +n: Perform debugging every n’th iteration.

The value can also be defined in an options file or options routine be setting LKDEB2. Error return codes and examples of messages can be found in Error Return Codes.

Parameters
debug2dthe flag to enable the debugging of the second derivative evaulations
cntvectthe control vector

◆ COIDEF_ClearM()

int COI_CALLCONV COIDEF_ClearM ( coiHandle_t cntvect,
int clearm )

ClearM.

Parameters
clearm
cntvectthe control vector

◆ COIDEF_ThreadS()

int COI_CALLCONV COIDEF_ThreadS ( coiHandle_t cntvect,
int threads )

number of threads allowed internally in CONOPT.

As discussed in Multi Threading CONOPT can use multiple threads using the OpenMP standard. The multi-threading capability is divided into three areas: (1) Internally in CONOPT, (2) during function and derivative calls using the FDEval callback routine, and (3) during directional 2nd derivative calls using the 2DDir callback routine.

This method is used to define how many threads can be used internally in CONOPT. The argument ThreadS is interpreted as follows:

  • ThreadS = 0: use MaxThread threads, as many as the OpenMP system will allocate,
  • ThreadS = 1: use one thread (this is the default),
  • ThreadS > 1: use min(ThreadS,MaxThread) threads.
Parameters
threadsthe number of threads allowed internally
cntvectthe control vector

◆ COIDEF_ThreadF()

int COI_CALLCONV COIDEF_ThreadF ( coiHandle_t cntvect,
int threadf )

number of threads allowed for simultaneous FDEval calls.

This method can be used to define how many threads can be used for simultaneous FDEval calls. The argument ThreadF is interpreted as follows:

  • ThreadF = 0: use the same number of threads as internally in CONOPT (this is the default),
  • ThreadF = 1: use one thread,
  • ThreadF > 1: use min(ThreadS,ThreadF) threads.
Parameters
threadfthe number of threads for simultaneous FDEval calls
cntvectthe control vector

◆ COIDEF_Thread2D()

int COI_CALLCONV COIDEF_Thread2D ( coiHandle_t cntvect,
int thread2d )

number of threads allowed for simultaneous 2DDir calls.

This method can be used to define how many threads can be used for simultaneous 2DDir calls. The argument Thread2D is interpreted as follows:

  • Thread2D = 0: use the same number of threads as internally in CONOPT (this is the default),
  • Thread2D = 1: use one thread,
  • Thread2D > 1: use min(Thread2D,ThreadF) threads.
Parameters
thread2dthe number of threads for simultaneous 2DDir calls
cntvectthe control vector

◆ COIDEF_ThreadC()

int COI_CALLCONV COIDEF_ThreadC ( coiHandle_t cntvect,
int threadc )

check for thread compatibility.

When using multiple threads, the result of the execution is in most cases independent of the number of threads. However, a few operations mostly related to summations can create slightly different results depending on the number of threads, and therefore the results may depend on the number of threads. ThreadC can be used to force reproducible results. The execution is done as if there were ThreadC threads independent of the actual number of ThreadS (ThreadS > ThreadC).

This method can be used to define how many threads CONOPT should simulate. The argument ThreadC is interpreted as follows:

  • ThreadC = 0: let the execution be controlled by ThreadS defined above,
  • ThreadC > 1: simulate the use of ThreadC > ThreadS threads.

The upper bound on ThreadC is currently 8.

Parameters
threadcthe number of threads CONOPT should simulate
cntvectthe control vector

◆ COIDEF_StdOut()

int COI_CALLCONV COIDEF_StdOut ( coiHandle_t cntvect,
int tostdout )

allow output to StdOut.

CONOPT will by default not write to Standard Output or Fortran Write(,) to avoid problems in certain Windowing environments. All communication goes via callback routines. If there are errors during the initial setup of communication it can sometimes be difficult to locate these errors. If you allow output to Standard Output then CONOPT may provide some extra debugging information.

Parameters
cntvectthe control vector
tostdout1 to output to Standard Output, 0 to silence the output.