Functions
integer function	coidef_license (cntvect, licint1, licint2, licint3, licstring)
	define the License Information.

integer function	coidef_base (cntvect, base)
	define the Base index for vectors.

integer function	coidef_fortran (cntvect)
	define Fortran Conventions for Argument Passing.

integer function	coidef_c (cntvect)
	define C Conventions for Argument Passing.

integer function	coidef_itlim (cntvect, itlim)
	define the Iteration Limit.

integer function	coidef_errlim (cntvect, errlim)
	define the Error Limit.

integer function	coidef_reslim (cntvect, reslim)
	define resource limit.

integer function	coidef_maxheap (cntvect, maxheap)
	define Limit on Heap Memory. ""

integer function	coidef_inistat (cntvect, inistat)
	handling of the initial status values.

integer function	coidef_fvinclin (cntvect, fvinclin)
	include the linear terms in function evaluations.

integer function	coidef_fvforall (cntvect, fvforall)
	call the FDEval for all constraints, including linear constraints.

integer function	coidef_maxsup (cntvect, maxsup)
	limit on superbasics.

integer function	coidef_square (cntvect, square)
	square models.

integer function	coidef_emptyrow (cntvect, emptyrow)
	allow empty rows.

integer function	coidef_emptycol (cntvect, emptycol)
	allow empty columns.

integer function	coidef_discont (cntvect, discont)
	allow discontinuous functions and derivatives.

integer function	coidef_hessfac (cntvect, hessfac)
	factor for Hessian density relative to Jacobian density HessFac.

integer function	coidef_debugfv (cntvect, debugfv)
	turn Debugging of FDEval on and off.

integer function	coidef_debug2d (cntvect, debug2d)
	turn debugging of 2nd derivatives on and off.

integer function	coidef_zeronoise (cntvect, zeronoise)
	define zero noise level.

integer function	coidef_threads (cntvect, threads)
	number of threads allowed internally in CONOPT.

integer function	coidef_threadf (cntvect, threadf)
	number of threads allowed for simultaneous `FDEval` calls.

integer function	coidef_thread2d (cntvect, thread2d)
	number of threads allowed for simultaneous `2DDir` calls.

integer function	coidef_threadc (cntvect, threadc)
	check for thread compatibility.

integer function	coidef_stdout (cntvect, tostdout)
	allow output to StdOut.

integer function	coidef_optorder (cntvect, optorder)
	define Optfile / Option order.

integer function	coidef_clearm (cntvect, clearm)
	ClearM.

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()

integer function coidef_license	(	integer, dimension(numcallback)	cntvect,
		integer	licint1,
		integer	licint2,
		integer	licint3,
		character(len=*)	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

licint1	the first license integer code
licint2	the second license integer code
licint3	the third license integer code
licstring	the license string
cntvect	the control vector

Definition at line 679 of file coistart.f90.

◆ coidef_base()

integer function coidef_base	(	integer, dimension(numcallback)	cntvect,
		integer	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

cntvect	the control vector
base	the base index for vectors

Definition at line 742 of file coistart.f90.

◆ coidef_fortran()

integer function coidef_fortran ( integer, dimension(numcallback) cntvect )

define Fortran Conventions for Argument Passing.

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

Parameters

cntvect the control vector

Definition at line 778 of file coistart.f90.

◆ coidef_c()

integer function coidef_c ( integer, dimension(numcallback) cntvect )

define C Conventions for Argument Passing.

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

Parameters

cntvect the control vector

Definition at line 808 of file coistart.f90.

◆ coidef_itlim()

integer function coidef_itlim	(	integer, dimension(numcallback)	cntvect,
		integer	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

itlim	the iteration limit
cntvect	the control vector

Definition at line 844 of file coistart.f90.

◆ coidef_errlim()

integer function coidef_errlim	(	integer, dimension(numcallback)	cntvect,
		integer	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

errlim	the error limit
cntvect	the control vector

Definition at line 889 of file coistart.f90.

◆ coidef_reslim()

integer function coidef_reslim	(	integer, dimension(numcallback)	cntvect,
		real(co_r)	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

reslim	the solve time limit in seconds
cntvect	the control vector

Definition at line 931 of file coistart.f90.

◆ coidef_maxheap()

integer function coidef_maxheap	(	integer, dimension(numcallback)	cntvect,
		real(co_r)	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

maxheap	the limit on heap memory ""
cntvect	the control vector

Definition at line 987 of file coistart.f90.

◆ coidef_inistat()

integer function coidef_inistat	(	integer, dimension(numcallback)	cntvect,
		integer	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

cntvect	the control vector
inistat	the initial status

Definition at line 1031 of file coistart.f90.

◆ coidef_fvinclin()

integer function coidef_fvinclin	(	integer, dimension(numcallback)	cntvect,
		integer	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

fvinclin	the linear terms in functions
cntvect	the control vector

Definition at line 1077 of file coistart.f90.

◆ coidef_fvforall()

integer function coidef_fvforall	(	integer, dimension(numcallback)	cntvect,
		integer	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

fvforall	the linear constraints in functions
cntvect	the control vector

Definition at line 1123 of file coistart.f90.

◆ coidef_maxsup()

integer function coidef_maxsup	(	integer, dimension(numcallback)	cntvect,
		integer	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

maxsup	the limit on superbasics
cntvect	the control vector

Definition at line 1175 of file coistart.f90.

◆ coidef_square()

integer function coidef_square	(	integer, dimension(numcallback)	cntvect,
		integer	square )

square models.

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

Parameters

square	`Square = 1` informs CONOPT that the model is Square. `Square = 0` is the default used for an ordinary optimization model.
cntvect	the control vector

Definition at line 1215 of file coistart.f90.

◆ coidef_emptyrow()

integer function coidef_emptyrow	(	integer, dimension(numcallback)	cntvect,
		integer	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

emptyrow	1 allows empty rows, 0 is the default behavior.
cntvect	the control vector

Definition at line 1256 of file coistart.f90.

◆ coidef_emptycol()

integer function coidef_emptycol	(	integer, dimension(numcallback)	cntvect,
		integer	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

emptycol	1 allows empty columns, 0 is the default behaviour.
cntvect	the control vector

Definition at line 1299 of file coistart.f90.

◆ coidef_discont()

integer function coidef_discont	(	integer, dimension(numcallback)	cntvect,
		integer	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

discont	1 allows discontinuous functions and derivatives, 0 is the default behaviour.
cntvect	the control vector

Definition at line 1344 of file coistart.f90.

◆ coidef_hessfac()

integer function coidef_hessfac	(	integer, dimension(numcallback)	cntvect,
		real(co_r)	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

cntvect	the control vector
hessfac	the threshold factor for Hessian density relative to Jacobian density

Definition at line 1386 of file coistart.f90.

◆ coidef_debugfv()

integer function coidef_debugfv	(	integer, dimension(numcallback)	cntvect,
		integer	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

debugfv	the flag to enable debugging of function evaluations
cntvect	the control vector

Definition at line 1437 of file coistart.f90.

◆ coidef_debug2d()

integer function coidef_debug2d	(	integer, dimension(numcallback)	cntvect,
		integer	debug2d )

turn debugging of 2nd derivatives on and off.

CONOPT has a rudimentary routine for checking if the 2^nd 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

debug2d	the flag to enable the debugging of the second derivative evaulations
cntvect	the control vector

Definition at line 1488 of file coistart.f90.

◆ coidef_zeronoise()

integer function coidef_zeronoise	(	integer, dimension(numcallback)	cntvect,
		real(co_r)	zeronoise )

define zero noise level.

CONOPT has a Function and Derivative Debugger that also tests whether variables that should not appear in an equation actually have an influence on the function value: the variables that should not appear are all perturbed by random amounts and the function is called again. If the function changes by the slightest amount, this must have been caused by one of the variables that should not influence the equation, and an error has been identified.

However, some implementations may give very small function changes as shown by the following example: Equation \(i\) depends on \(\sum_{j \neq i}X(j)\). Initially, compute \(XS = \sum_{i}X(i)\) and the compute \(XS-X(i)\) for use in Equation \(i\). Because of the round-off errors involved in computing \(XS-X(i)\), \(X(i)\) may seem to appear in Equation \(i\). For these rare cases you may need to define a small "zero noise level" and all derivatives less that this value will not be considered errors. The default value is zero.

Parameters

cntvect	the control vector
zeronoise	the threshold for zero noise level in function derivatives

Definition at line 1538 of file coistart.f90.

◆ coidef_threads()

integer function coidef_threads	(	integer, dimension(numcallback)	cntvect,
		integer	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 2^nd 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

threads	the number of threads allowed internally
cntvect	the control vector

Definition at line 1589 of file coistart.f90.

◆ coidef_threadf()

integer function coidef_threadf	(	integer, dimension(numcallback)	cntvect,
		integer	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

threadf	the number of threads for simultaneous `FDEval` calls
cntvect	the control vector

Definition at line 1636 of file coistart.f90.

◆ coidef_thread2d()

integer function coidef_thread2d	(	integer, dimension(numcallback)	cntvect,
		integer	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

thread2d	the number of threads for simultaneous `2DDir` calls
cntvect	the control vector

Definition at line 1684 of file coistart.f90.

◆ coidef_threadc()

integer function coidef_threadc	(	integer, dimension(numcallback)	cntvect,
		integer	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

threadc	the number of threads CONOPT should simulate
cntvect	the control vector

Definition at line 1737 of file coistart.f90.

◆ coidef_stdout()

integer function coidef_stdout	(	integer, dimension(numcallback)	cntvect,
		integer	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

cntvect	the control vector
tostdout	1 to output to Standard Output, 0 to silence the output.

Definition at line 1777 of file coistart.f90.

◆ coidef_optorder()

integer function coidef_optorder	(	integer, dimension(numcallback)	cntvect,
		integer	optorder )

define Optfile / Option order.

By default CONOPT will first process the options defined in a file, see coidef_optfile(), and the process the options defined via a call-back routine. This method is called to change this order.

The interpretation of OptOrder is:

0: Process option defined via the option file before options defined via the options callback. (default value)
1: Process option defined via the options callback before options defined via options file.

Parameters

cntvect	the control vector
optorder	Option processing order

Definition at line 1822 of file coistart.f90.

◆ coidef_clearm()

integer function coidef_clearm	(	integer, dimension(numcallback)	cntvect,
		integer	clearm )

ClearM.

Parameters

clearm
cntvect	the control vector

Definition at line 1859 of file coistart.f90.

Functions

Detailed Description

Function Documentation

◆ coidef_license()

◆ coidef_base()

◆ coidef_fortran()

◆ coidef_c()

◆ coidef_itlim()

◆ coidef_errlim()

◆ coidef_reslim()

◆ coidef_maxheap()

◆ coidef_inistat()

◆ coidef_fvinclin()

◆ coidef_fvforall()

◆ coidef_maxsup()

◆ coidef_square()

◆ coidef_emptyrow()

◆ coidef_emptycol()

◆ coidef_discont()

◆ coidef_hessfac()

◆ coidef_debugfv()

◆ coidef_debug2d()

◆ coidef_zeronoise()

◆ coidef_threads()

◆ coidef_threadf()

◆ coidef_thread2d()

◆ coidef_threadc()

◆ coidef_stdout()

◆ coidef_optorder()

◆ coidef_clearm()