Defining the Model

Providing the matrix information and initial values to CONOPT.

The call back routine ReadMatrix described in this section defines the structure of the model. It is a mandatory routine that must be registered with COIDEF_ReadMatrix() defined above before CONOPT is started. CONOPT will call ReadMatrix as the first routine (except for calls of Message) and the modeler must define initial values, bounds, constraint types, right hand sides, and structure and nonlinearity pattern of the Jacobian. All arguments passed to ReadMatrix (except USRMEM) are allocated and owned by CONOPT. CONOPT assigns many arguments with default values before the routine is called to make the model building process as easy as possible. If these default values are appropriate, the modeler does not have to change them. The Tutorial and Examples using CONOPT provided with the Library show several uses of defaults.

ReadMatrix – Read Matrix

Attention

Mandatory callback routine.

int COI_CALLCONV ReadMatrix( double* LOWER, double* CURR, 
        double* UPPER, int* VSTA, int* TYPE, double* RHS,
        int* ESTA, int* COLSTA, int* ROWNO, double* VALUE,
        int* NLFLAG, int* N, int* M, int* NZ, 
        void* USRMEM );

where:

• LOWER: Vector of lower bounds on the variables. CONOPT will fill the vector with a special internal value that represent minus infinity or no lower bound before issuing the callback.
• CURR: Vector of initial values of the variables. CONOPT will fill the vector with the default initial value of zero before issuing the callback.
• UPPER: Vector of upper bounds on the variables. CONOPT will fill the vector with a special internal value that represent plus infinity or no upper bound before issuing the callback.

• VSTA: Vector of initial status values for the variable. VSTA is only used if COIDEF_IniStat() was called with IniStat = 1 or 2.

  If IniStat = 1 the value of VSTA must be defined as:

  • 0: The variable is initialized non-basic (if CURR = LOWER or CURR = UPPER) or super-basic, and
  • 1: The variable is initialized basic

  and if IniStat = 2 the value of VSTA must be defined as:

  • 0: The variable is initialized at lower bound
  • 1: The variable is initialized at upper bound
  • 2: The variable is initialized basic, and
  • 3: The variable is initialized superbasic.

  IniStat = 1 is simple to implement by hand, while IniStat = 2 is consistent with the output status defined in the Solution callback method. Note that if the numerical value in CURR are inconsistent with the status value, the numerical values will be used.

  If IniStat = 0 (the default value) CONOPT will not use VSTA and you do not have to define it.

• TYPE: Vector of equation types. The values of TYPE have the following meaning:

  • 0: An equality constraint.
  • 1: A greater than or equal constraint.
  • 2: A less than or equal constraint.
  • 3: A free row.

  There is no default value for TYPE so it must be defined for all constraints. Note that CONOPT does not accept ranges.

• RHS: Vector of right hand sides values. The default value is zero.

• ESTA: Vector of initial status values for the slacks in the constraints. ESTA is only used if COIDEF_IniStat() was called with IniStat = 1 or 2.

  If IniStat = 1 the value of ESTA must be defined as:

  • 0: The slack is initialized non-basic (if the constraint is binding in the initial point) or super-basic, and
  • 1: The slack is initialized basic

  and if IniStat = 2 the value of ESTA must be defined as:

  • 0: The slack is initialized at lower bound.
  • 1: The slack is initialized at upper bound.
  • 2: The slack is initialized basic, and
  • 3: The slack is initialized superbasic.

  Again, IniStat = 1 is simple to implement by hand, while IniStat = 2 is consistent with the output status defined in Solution callback method.

  If IniStat = 0 (the default value) then CONOPT will not use ESTA.

• COLSTA: Vector of start of column pointers. All non-zero Jacobian elements must be sorted by column, i.e. all elements in column i comes before all elements in column i+1. COLSTA points to the first element in each column. If you have selected Base = 1 (Fortran conventions) then COLSTA must therefore satisfy: COLSTA(1) = 1 and COLSTA(N+1) = NZ+1. If you have selected Base = 0 (C conventions) then COLSTA must therefore satisfy: COLSTA[0] = 0 and COLSTA[N] = NZ. COLSTA must in both cases be increasing.
• ROWNO: Vector of row or equation numbers of the non-zeros. The numbers must be in the range 1 through M inclusive if you have defined Base = 1 (Fortran conventions) and in the range 0 to M-1 inclusive if you have defined Base = 0 (C conventions). Although the columns are sorted, the rows do not have to be sorted within each column.
• VALUE: Vector of values of the Jacobian elements. VALUE must be defined for all constant Jacobian elements, i.e. elements for which the following NLFLAG = 0. VALUE does not have to be defined for varying Jacobian elements.

• NLFLAG: Vector of nonlinearity flags:

  • 0: The non-zero is constant, i.e. the variable appears linearly.
  • 1: The non-zero is varying, i.e. the variable appears nonlinearly

  NLFLAG is not read if the model is linear, i.e. if NLNZ = 0, otherwise it must be defined. Note that if you have an LP model, you should probably select a specialized LP algorithm instead of CONOPT.

• N: Number of variables as defined in COIDEF_NumVar().
• M: Number of constraints as defined in COIDEF_NumCon().
• NZ: Number of Jacobian elements as defined in COIDEF_NumNz().
• USRMEM: User memory as defined in COIDEF_UsrMem() (Only for Fortran and C API).

The lower bounds in LOWER must be less than or equal to the upper bounds in UPPER. Some of the bounds may be -INF or +INF, which are the bounds CONOPT assigns by default. If a bound is infinite, the user should normally not change the corresponding entry in LOWER or UPPER. If it is more convenient for the modeler to assign a value representing infinity it should be done using the values that are present in LOWER and UPPER when ReadMatrix is called, for example taken from the first element before any assignments are done. As an alternative, you may define the numerical value of Infinity to be used by the solution algorithm in option RTMAXV and store the same value in UPPER and -RTMAXV in LOWER.

The values in CURR, both those defined by the modeler and those defined by default, are without warning moved to the nearest bound if they are outside the bounds.

Note

CONOPT assumes that all functions are defined for all values of the variables between their bounds. CONOPT will never attempt to evaluate the functions in points outside the bounds specified by LOWER and UPPER.