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 conopt::coidef_readmatrix() defined above before CONOPT is started. CONOPT will call ReadMatrix as the first routine (except for calls of Message). During this call, the modeller must provide the matrix that corresponds to the problem instance. It is recommended that the modeller follows the these steps:

1. Define the variables. This involves specifying the lower and upper bounds (LOWER and UPPER respectively), an initial solution value (CURR), and an initial variable status (VSTA). The modeller must take note of the array indices that correspond to the model variables. These indices are used when specifying the structure of the matrix and Hessian.
2. Define the constraints. The constraints are defined by specifying the type (TYPE)—either equality, greater than or equal, or less than or equal—the right hand side of the constraint (RHS), and the initial status of the constraint slack variables (ESTA). It is important to note that CONOPT only accepts one-sided constraints. As such, range constraints must be added by providing both sides of the constraint separately.
3. Define the matrix. This is the most important part of the ReadMatrix callback, since it defines the instance that will be solved. The matrix is provided to CONOPT in a column-oriented format with the arrays COLSTA, ROWNO, NLFLAG and VALUE.
   • COLSTA has a length of the number of variables. Each element i corresponds to the index j in ROWNO, VALUE and NLFLAG (the same index for all) that is the start of the non-zeros for variable i.
   • ROWNO has a length of the number of non-zeros. These are the row numbers for the non-zeros of the columns.
   • VALUE has a length of the number of non-zeros. These are the non-zero coefficients for the columns in the matrix.
   • NLFLAG has a length of the number of non-zeros. This is a flag that is set to 1 to indicate whether the column is in a nonlinear expression in the corresponding row. This is 0 by default. If the NLFLAG is set to 1, then the corresponding entry in VALUE is ignored.

As an example of specifying the matrix, consider column 2 that has 4 non-zeros. These are in rows 2, 4, 7, 8. The non-zeros in rows 2 and 7 are 0.5 and 1.6 respectively. Column 2 is in a nonlinear expression in rows 4 and 8. In this example, let column 1 have 5 non-zeros in the matrix. Then,

• COLSTA[2] = 6,
• ROWNO[6] = 2, ROWNO[7] = 4, ROWNO[8] = 7, and ROWNO[9] = 8,
• VALUE[6] = 0.5 and VALUE[8] = 1.6 (we don't need to specify VALUE[7] an VALUE[9] because these correspond to nonlinear expressions),
• NLFLAG[7] = 1 and NLFLAG[9] = 1 (we don't need to specify NLFLAG[6] and NLFLAG[8] because these correspond to linear expressions),

If there is a third variable, then COLSTA[3] = 10.

Regarding the specification of nonlinear expressions in the matrix, consider the row

\[a_1 x_1 + a_2 x_2 + a_3 x_3 + a_4 x_3^2 + a_5 x_4 x_5. \]

The NLFLAG for variables \(x_1\) and \(x_2\) are set to 0, and the NLFLAG for \(x_3\), \(x_4\) and \(x_5\) are set to 1. Even though \(x_3\) is also in a linear term, the linear term is considered part of the nonlinear expression containing \(x_3\). This definition of the nonlinear expressions is important when performing the evaluation in the FDEval callback.

The Tutorial and Examples using CONOPT provided with the Library show several methods for specifying a model instance using the ReadMatrix callback.

ReadMatrix – Read Matrix

Attention

Mandatory callback routine.

Integer Function ReadMatrix( LOWER, CURR, UPPER, VSTA, &
                        TYPE, RHS, ESTA, COLSTA        &
                        ROWNO, VALUE, NLFLAG,          &
                        N, M, NZ, USRMEM )
INTEGER, Intent (IN)                   :: N, M, NZ
INTEGER, Dimension(N),  Intent(IN OUT) :: VSTA
INTEGER, Dimension(M),  Intent(IN OUT) :: TYPE, ESTA
INTEGER, Dimension(N+1),Intent(IN OUT) :: COLSTA
INTEGER, Dimension(NZ), Intent(IN OUT) :: ROWNO, NLFLAG
REAL*8,  Dimension(N),  Intent(IN OUT) :: LOWER, CURR, UPPER
REAL*8,  Dimension(M),  Intent(IN OUT) :: RHS
REAL*8,  Dimension(NZ), Intent(IN OUT) :: VALUE
REAL*8,  Intent(IN OUT)                :: 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 conopt::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 conopt::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 conopt::coidef_numvar().
• M: Number of constraints as defined in conopt::coidef_numcon().
• NZ: Number of Jacobian elements as defined in conopt::coidef_numnz().
• USRMEM: User memory as defined in conopt::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.