naginterfaces.library.opt.handle_​set_​qconstr

naginterfaces.library.opt.handle_set_qconstr(handle, s, idqc, idxr=None, r=None, irowq=None, icolq=None, q=None)

handle_set_qconstr is a part of the NAG optimization modelling suite and defines a new, or edits an existing, quadratic objective function or constraint of the problem.

For full information please refer to the NAG Library document for e04rs

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/e04/e04rsf.html

Parameters

handleHandle

The handle to the problem. It needs to be initialized (e.g., by handle_init()) and must not be changed between calls to the NAG optimization modelling suite.

sfloat

The constant term in quadratic constraint.

If $idqc=-1$, $s$ will not be referenced.

idqcint

$idqc=0$

A new quadratic constraint is created.

$idqc>0$

Specifies the index of an existing constraint to be replaced. i.e., replaces the $idqc$th constraint.

$idqc=-1$

A new quadratic objective is created and will replace any previously defined objective function.

idxrNone or int, array-like, shape $\left(\text{nnzr}\right)$, optional

The nonzero elements of the sparse vector $r$. $idxr[i-1]$ must contain the index of $r[\text{i}-1]$ in the vector, for $\text{i}=1,2,\dots ,\text{nnzr}$. No particular order is expected, but elements should not repeat. Note that $n$ is the current number of variables in the problem.

rNone or float, array-like, shape $\left(\text{nnzr}\right)$, optional

The nonzero elements of the sparse vector $r$. $idxr[i-1]$ must contain the index of $r[\text{i}-1]$ in the vector, for $\text{i}=1,2,\dots ,\text{nnzr}$. No particular order is expected, but elements should not repeat. Note that $n$ is the current number of variables in the problem.

irowqNone or int, array-like, shape $\left(\text{nnzq}\right)$, optional

Arrays $irowq$, $icolq$ and $q$ store the nonzeros of the upper triangle of the matrix $Q$ in coordinate storage (CS) format (see the F11 Introduction). $irowq$ specifies one-based row indices, $icolq$ specifies one-based column indices and $q$ specifies the values of the nonzero elements in such a way that $Q_{ij}=q[l-1]$ where $i=irowq[l-1]$, $j=icolq[\text{l}-1]$, for $\text{l}=1,2,\dots ,\text{nnzq}$. No particular order is expected, but elements should not repeat.

icolqNone or int, array-like, shape $\left(\text{nnzq}\right)$, optional

Arrays $irowq$, $icolq$ and $q$ store the nonzeros of the upper triangle of the matrix $Q$ in coordinate storage (CS) format (see the F11 Introduction). $irowq$ specifies one-based row indices, $icolq$ specifies one-based column indices and $q$ specifies the values of the nonzero elements in such a way that $Q_{ij}=q[l-1]$ where $i=irowq[l-1]$, $j=icolq[\text{l}-1]$, for $\text{l}=1,2,\dots ,\text{nnzq}$. No particular order is expected, but elements should not repeat.

qNone or float, array-like, shape $\left(\text{nnzq}\right)$, optional

Arrays $irowq$, $icolq$ and $q$ store the nonzeros of the upper triangle of the matrix $Q$ in coordinate storage (CS) format (see the F11 Introduction). $irowq$ specifies one-based row indices, $icolq$ specifies one-based column indices and $q$ specifies the values of the nonzero elements in such a way that $Q_{ij}=q[l-1]$ where $i=irowq[l-1]$, $j=icolq[\text{l}-1]$, for $\text{l}=1,2,\dots ,\text{nnzq}$. No particular order is expected, but elements should not repeat.

Returns

idqcint

If $idqc=0$ on entry, then $idqc$ is overwritten with the index of the new quadratic constraint. By definition, this is the number of quadratic constraints already defined plus one. Otherwise, $idqc$ stays unchanged.

Raises

NagValueError

(errno $1$)

$handle$ has not been initialized.

(errno $1$)

$handle$ does not belong to the NAG optimization modelling suite, has not been initialized properly or is corrupted.

(errno $1$)

$handle$ has not been initialized properly or is corrupted.

(errno $2$)

The problem cannot be modified right now, the solver is running.

(errno $4$)

On entry, $idqc=⟨value⟩$.

The given $idqc$ does not match with any quadratic constraint already defined.

(errno $5$)

On entry, $idqc=⟨value⟩$.

Constraint: $idqc\ge -1$.

(errno $6$)

On entry, $\text{nnzq}=⟨value⟩$.

Constraint: $\text{nnzq}\ge 0$.

(errno $6$)

On entry, $\text{nnzr}=⟨value⟩$.

Constraint: $\text{nnzr}\ge 0$.

(errno $6$)

$\text{nnzr}$ and $\text{nnzq}$ cannot be zero at the same time.

(errno $7$)

On entry, $i=⟨value⟩$, $idxr[i-1]=⟨value⟩$ and $\text{n}=⟨value⟩$.

Constraint: $1\le idxr[i-1]\le \text{n}$.

(errno $7$)

On entry, more than one element of $idxr$ has index $⟨value⟩$.

Constraint: each element of $idxr$ must have a unique index.

(errno $8$)

On entry, $i=⟨value⟩$, $irowq[\text{i}-1]=⟨value⟩$ and $\text{n}=⟨value⟩$.

Constraint: $1\le irowq[\text{i}-1]\le \text{n}$.

(errno $8$)

On entry, $i=⟨value⟩$, $icolq[\text{i}-1]=⟨value⟩$ and $\text{n}=⟨value⟩$.

Constraint: $1\le icolq[\text{i}-1]\le \text{n}$.

(errno $8$)

On entry, $i=⟨value⟩$, $irowq[\text{i}-1]=⟨value⟩$ and $icolq[\text{i}-1]=⟨value⟩$.

Constraint: $irowq[\text{i}-1]\le icolq[\text{i}-1]$ (elements within the upper triangle).

(errno $8$)

On entry, more than one element of $q$ has row index $⟨value⟩$ and column index $⟨value⟩$.

Constraint: each element of $q$ must have a unique row and column index.

Notes

After the $handle$ has been initialized (e.g., handle_init() has been called), handle_set_qconstr may be used to edit a model by adding or replacing a quadratic objective function or constraint of the form

$$\frac{1}{2}{x}^{T}Qx+r^{T}x$$

and

$$\frac{1}{2}{x}^{T}Qx+r^{T}x+s\le 0\text{,}$$

respectively. If a factor $F$ of $Q$ such that $Q=F^{T}F$ is available, handle_set_qconstr_fac() should be called instead.

The matrix $Q$ is a sparse symmetric $n\times n$ matrix. Typically handle_set_qconstr would be used together with Second-order Cone Programming (SOCP) solver handle_solve_socp_ipm() if $Q$ is positive semidefinite which implies the problem is convex. Otherwise, if the problem is nonconvex, a general nonlinear optimization solver (such as handle_solve_ipopt()) may be used. It is also acceptable if $Q$ is a zero matrix, in which case the corresponding objective function or constraint becomes linear. Note that it is possible to temporarily disable and enable individual constraints in the model by handle_disable() and handle_enable(), respectively. See the E04 Introduction for more details about the NAG optimization modelling suite.