# 15.1 API Conventions¶

## 15.1.1 Function arguments¶

Naming Convention

In the definition of the **MOSEK** Optimizer API for Java a consistent naming convention has been used. This implies that whenever for example `numcon`

is an argument in a function definition it indicates the number of constraints. In Table 15.1 the variable names used to specify the problem parameters are listed.

API name | API type | Dimension | Related problem parameter |
---|---|---|---|

`numcon` |
`int` |
\(m\) | |

`numvar` |
`int` |
\(n\) | |

`numcone` |
`int` |
\(t\) | |

`aptrb` |
`int[]` |
`numvar` |
\(a_{ij}\) |

`aptre` |
`int[]` |
`numvar` |
\(a_{ij}\) |

`asub` |
`int[]` |
`aptre[numvar-1]` |
\(a_{ij}\) |

`aval` |
`double[]` |
`aptre[numvar-1]` |
\(a_{ij}\) |

`c` |
`double[]` |
`numvar` |
\(c_j\) |

`cfix` |
`double` |
\(c^f\) | |

`blc` |
`double[]` |
`numcon` |
\(l_k^c\) |

`buc` |
`double[]` |
`numcon` |
\(u_k^c\) |

`blx` |
`double[]` |
`numvar` |
\(l_k^x\) |

`bux` |
`double[]` |
`numvar` |
\(u_k^x\) |

`numqonz` |
`int` |
\(q_{ij}^o\) | |

`qosubi` |
`int[]` |
`numqonz` |
\(q_{ij}^o\) |

`qosubj` |
`int[]` |
`numqonz` |
\(q_{ij}^o\) |

`qoval` |
`double[]` |
`numqonz` |
\(q_{ij}^o\) |

`numqcnz` |
`int` |
\(q_{ij}^k\) | |

`qcsubk` |
`int[]` |
`numqcnz` |
\(q_{ij}^k\) |

`qcsubi` |
`int[]` |
`numqcnz` |
\(q_{ij}^k\) |

`qcsubj` |
`int[]` |
`numqcnz` |
\(q_{ij}^k\) |

`qcval` |
`double[]` |
`numqcnz` |
\(q_{ij}^k\) |

`bkc` |
`int[]` |
`numcon` |
\(l_k^c\) and \(u_k^c\) |

`bkx` |
`int[]` |
`numvar` |
\(l_k^x\) and \(u_k^x\) |

The relation between the variable names and the problem parameters is as follows:

- The quadratic terms in the objective: \(q_{ \mathtt{qosubi[t]}, \mathtt{qosubj[t]} }^o = \mathtt{qoval[t]},\quad t=0,\ldots ,\mathtt{numqonz}-1.\)
- The linear terms in the objective : \(c_j = \mathtt{c[j]},\quad j=0,\ldots ,\mathtt{numvar}-1\)
- The fixed term in the objective : \(c^f = \mathtt{cfix}.\)
- The quadratic terms in the constraints: \(q_{\mathtt{qcsubi[t]},\mathtt{qcsubj[t]}}^{\mathtt{qcsubk[t]}} = \mathtt{qcval[t]},\quad t=0,\ldots ,\mathtt{numqcnz}-1\)
- The linear terms in the constraints: \(a_{\mathtt{asub[t],j}} = \mathtt{aval[t]}, \quad t=\mathtt{ptrb[j]},\ldots ,\mathtt{ptre[j]}-1,\ j=0,\ldots ,\mathtt{numvar}-1\)

Passing arguments by reference

An argument described as **T** by reference indicates that the function interprets its given argument as a reference to a variable of type **T**. This usually means that the argument is used to output or update a value of type **T**. For example, suppose we have a function documented as

```
void foo (..., int[] nzc, ...)
```

`nzc`

(**int**by reference) – The number of nonzero elements in the matrix. (output)

Then it could be called as follows.

```
int nzc = new int[1];
foo (..., nzc, ...)
System.out.println("The number of nonzero elements: ", nzc[0])
```

Information about input/output arguments

The following are purely informational tags which indicate how **MOSEK** treats a specific function argument.

- (input) An input argument. It is used to input data to
**MOSEK**. - (output) An output argument. It can be a user-preallocated data structure, a reference, a string buffer etc. where
**MOSEK**will output some data. - (input/output) An input/output argument.
**MOSEK**will read the data and overwrite it with new/updated information.

## 15.1.2 Bounds¶

The bounds on the constraints and variables are specified using the variables `bkc`

, `blc`

, and `buc`

. The components of the integer array `bkc`

specify the bound type according to Table 15.2

Symbolic constant | Lower bound | Upper bound |
---|---|---|

`boundkey.fx` |
finite | identical to the lower bound |

`boundkey.fr` |
minus infinity | plus infinity |

`boundkey.lo` |
finite | plus infinity |

`boundkey.ra` |
finite | finite |

`boundkey.up` |
minus infinity | finite |

For instance `bkc[2]=`

`boundkey.lo`

means that \(-\infty < l_2^c\) and \(u_2^c = \infty\). Even if a variable or constraint is bounded only from below, e.g. \(x \geq 0\), both bounds are inputted or extracted; the irrelevant value is ignored.

Finally, the numerical values of the bounds are given by

The bounds on the variables are specified using the variables `bkx`

, `blx`

, and `bux`

in the same way. The numerical values for the lower bounds on the variables are given by

## 15.1.3 Vector Formats¶

Three different vector formats are used in the **MOSEK** API:

Full (dense) vector

This is simply an array where the first element corresponds to the first item, the second element to the second item etc. For example to get the linear coefficients of the objective in `task`

with `numvar`

variables, one would write

```
double[] c = new double[numvar];
task.getc(c);
```

Vector slice

A vector slice is a range of values from `first`

up to and **not including** `last`

entry in the vector, i.e. for the set of indices `i`

such that `first <= i < last`

. For example, to get the bounds associated with constrains 2 through 9 (both inclusive) one would write

```
double[] upper_bound = new double[8];
double[] lower_bound = new double[8];
mosek.boundkey bound_key[]
= new mosek.boundkey[8];
task.getconboundslice(2,10,
bound_key,lower_bound,upper_bound);
```

Sparse vector

A sparse vector is given as an array of indexes and an array of values. The indexes need not be ordered. For example, to input a set of bounds associated with constraints number 1, 6, 3, and 9, one might write

```
int[] bound_index = { 1, 6, 3, 9 };
mosek.boundkey[] bound_key
= { mosek.boundkey.fr,
mosek.boundkey.lo,
mosek.boundkey.up,
mosek.boundkey.fx };
double[] lower_bound = { 0.0, -10.0, 0.0, 5.0 };
double[] upper_bound = { 0.0, 0.0, 6.0, 5.0 };
task.putconboundlist(bound_index,
bound_key,lower_bound,upper_bound);
```

## 15.1.4 Matrix Formats¶

The coefficient matrices in a problem are inputted and extracted in a sparse format. That means only the nonzero entries are listed.

### 15.1.4.1 Unordered Triplets¶

In unordered triplet format each entry is defined as a row index, a column index and a coefficient. For example, to input the \(A\) matrix coefficients for \(a_{1,2}=1.1, a_{3,3}=4.3\) , and \(a_{5,4}=0.2\) , one would write as follows:

```
int[] subi = { 1, 3, 5 };
int[] subj = { 2, 3, 4 };
double[] cof = { 1.1, 4.3, 0.2 };
task.putaijlist(subi,subj,cof);
```

Please note that in some cases (like `Task.putaijlist`

) *only* the specified indexes are modified — all other are unchanged. In other cases (such as `Task.putqconk`

) the triplet format is used to modify *all* entries — entries that are not specified are set to \(0\).

### 15.1.4.2 Column or Row Ordered Sparse Matrix¶

In a sparse matrix format only the non-zero entries of the matrix are stored. **MOSEK** uses a sparse packed matrix format ordered either by columns or rows. Here we describe the column-wise format. The row-wise format is based on the same principle.

Column ordered sparse format

A sparse matrix in column ordered format is essentially a list of all non-zero entries read column by column from left to right and from top to bottom within each column. The exact representation uses four arrays:

`asub`

: Array of size equal to the number of nonzeros. List of row indexes.`aval`

: Array of size equal to the number of nonzeros. List of non-zero entries of \(A\) ordered by columns.`ptrb`

: Array of size`numcol`

, where`ptrb[j]`

is the position of the first value/index in`aval`

/`asub`

for the \(j\)-th column.`ptre`

: Array of size`numcol`

, where`ptre[j]`

is the position of the last value/index plus one in`aval`

/`asub`

for the \(j\)-th column.

With this representation the values of a matrix \(A\) with `numcol`

columns are assigned using:

As an example consider the matrix

which can be represented in the column ordered sparse matrix format as

Fig. 15.1 illustrates how the matrix \(A\) in (15.1) is represented in column ordered sparse matrix format.

Column ordered sparse format with nonzeros

Note that `nzc[j] := ptre[j]-ptrb[j]`

is exactly the number of nonzero elements in the \(j\)-th column of \(A\). In some functions a sparse matrix will be represented using the equivalent dataset `asub`

, `aval`

, `ptrb`

, `nzc`

. The matrix \(A\) (15.1) would now be represented as:

Row ordered sparse matrix

The matrix \(A\) (15.1) can also be represented in the row ordered sparse matrix format as: