GALAHAD WCP package

purpose

The wcp package uses a primal-dual interior-point method to find a well-centered point within a polyhedral set. The aim is to find a point that lies interior to the boundary of the polyhedron definied by the general linear constraints and simple bounds

\[c_l \leq A x \leq c_u \;\;\mbox{and} \;\; x_l \leq x \leq x_u,\]

where \(A\) is a given \(m\) by \(n\) matrix, and any of the components of the vectors \(c_l\), \(c_u\), \(x_l\) or \(x_u\) may be infinite. The method offers the choice of direct and iterative solution of the key regularization subproblems, and is most suitable for problems involving a large number of unknowns \(x\), since full advantage is taken of “any zero coefficients in the matrix \(A\). The package identifies infeasible problems, and problems for which there is no strict interior.

See Section 4 of $GALAHAD/doc/wcp.pdf for a brief description of the method employed and other details.

terminolgy

More specifically, if possible, the package finds a solution to the system of primal optimality equations

\[A x = c,\;\;\mbox{(1)}\]

the dual optimality equations

\[g = A^{T} y + z,\;\; y = y^{l} + y^{u} \;\;\mbox{and}\;\; z = z^{l} + z^{u},\;\;\mbox{(2)}\]

and perturbed complementary slackness equations

\[( c_i^{} - c^l_i ) y^{l}_i = (\mu_c^{l})_i^{} \;\;\mbox{and}\;\; ( c_i^{} - c_i^u ) y^{u}_i = (\mu_c^{u})_i^{}, \;\;\; i = 1, \ldots , m,\;\;\mbox{(3)}\]

and

\[((x^{}_j - x^l_j ) z_j^{l} = (\mu_x^{l})_j^{} \;\;\mbox{and}\;\; ( x^{}_j - x^u_j ) z_j^{u} = (\mu_x^{u})_j^{}, \;\;\; j = 1, \ldots , n,\;\;\mbox{(4)}\]

for which

\[c^{l} \leq c \leq c^{u}, \;\; x^{l} \leq x \leq x^{u}, \;\; y^{l} \geq 0, \;\; y^{u} \leq 0, \;\; z^{l} \geq 0 \;\; \mbox{and} \;\; z^{u} \leq 0. \;\;\mbox{(5)}\]

Here \(\mu_c^{l}\), \(\mu_c^{u}\), \(\mu_x^{l}\) and \(\mu_x^{u}\) are vectors of strictly positive targets, \(g\) is another given target vector (which is often zero), \((y^{l}, y^{u})\) and \((z^{l}, z^{u})\) are Lagrange multipliers for the linear constraints and dual variables for the simple bounds respectively, and vector inequalities hold component-wise; \(c\) gives the constraint value \(A x\). Since the perturbed complementarity equations normally imply that

\[c^{l} < c < c^{u}, \;\; x^{l} < x < x^{u}, \;\; y^{l} > 0, \;\; y^{u} < 0, \;\; z^{l} > 0 \;\; \mbox{and} \;\; z^{u} < 0, \;\;\mbox{(6)}\]

such a primal-dual point \((x, c, y^{l}, y^{u}, z^{l}, z^{l})\) may be used, for example, as a feasible starting point for primal-dual interior-point methods for solving the linear programming problem of minimizing \(g^T x\) within the given polyhedral set. method

method

The algorithm is iterative, and at each major iteration attempts to find a solution to the perturbed system (1), (2),

\[( c_i^{} - c^l_i + (\theta_c^l)_i^{} ) ( y^{l}_i + (\theta_y^l)_i^{} ) = (\mu_c^{l})_i^{} \;\;\mbox{and}\;\; ( c_i^{} - c_i^u - (\theta_c^u)_i^{} ) y^{u}_i - (\theta_y^u)_i^{} ) = (\mu_c^{u})_i^{}, \;\;\; i = 1, \ldots , m,\;\;\mbox{(7)}\]

\[ ( x_j^{} - x^l_j + (\theta_x^l)_j^{} ) ( z^{l}_j + (\theta_z^l)_j^{} ) = (\mu_x^{l})_j^{} \;\;\mbox{and}\;\; ( x_j^{} - x_j^u - (\theta_x^u)_j^{} ) ( z^{u}_j - (\theta_z^u)_j^{} ) = (\mu_x^{u})_j^{}, \;\;\; j = 1, \ldots , n,\;\;\mbox{(8)}\]

and

\[c^{l} - \theta_c^l < c < c^{u} + \theta_c^u, \;\; x^{l} - \theta_x^l < x < x^{u} + \theta_x^u, \;\; y^{l} > - \theta_y^l , \;\; y^{u} < \theta_y^u , \;\; z^{l} > - \theta_z^l \;\; \mbox{and} \;\; z^{u} < \theta_z^u ,\;\;\mbox{(9)}\]

where the vectors of perturbations \(\theta^l_c\), \(\theta^u_c\), \(\theta^l_x\), \(\theta^u_x\), \(\theta^l_x\), \(\theta^u_x\), \(\theta^l_y\), \(\theta^u_y\), \(\theta^l_z\) and \(\theta^u_z\), are non-negative. Rather than solve (1), (2) and (7)–(9) exactly, we instead seek a feasible point for the easier relaxation (1), (2) and

\[\begin{split}\begin{array}{cccccl} \gamma (\mu_c^{l})_i^{} & \leq & ( c_i^{} - c^l_i + (\theta_c^l)_i^{} ) ( y^{l}_i + (\theta_y^l)_i^{} ) & \leq & (\mu_c^{l})_i^{} / \gamma & \;\;\mbox{and}\;\; \\ \gamma (\mu_c^{u})_i^{} & \leq & ( c_i^{} - c_i^u - (\theta_c^u)_i^{} ) ( y^{u}_i - (\theta_y^u)_i^{} ) & \leq & (\mu_c^{u})_i^{}, /\gamma & \;\;\; i = 1, \ldots , m, \;\;\mbox{and}\;\; \\ \gamma (\mu_x^{l})_j^{} & \leq & ( x_j^{} - x^l_j + (\theta_x^l)_j^{} ) ( z^{l}_j + (\theta_z^l)_j^{} ) & \leq & (\mu_x^{l})_j^{} /\gamma & \;\;\mbox{and}\;\; \\ \gamma (\mu_x^{u})_j^{} & \leq & ( x_j^{} - x_j^u - (\theta_x^u)_j^{} ) ( z^{u}_j - (\theta_z^u)_j^{} ) & \leq & (\mu_x^{u})_j^{} /\gamma , & \;\;\; j = 1, \ldots , n, \end{array} \;\;\mbox{(10)}\end{split}\]

for some \(\gamma \in (0,1]\) which is allowed to be smaller than one if there is a nonzero perturbation.

Given any solution to (1)–(2) and (10) satisfying (9), the perturbations are reduced (sometimes to zero) so as to ensure that the current solution is feasible for the next perturbed problem. Specifically, the perturbation \((\theta^l_c)_i^{}\) for the constraint \(c_i^{} \geq c^l_i\) is set to zero if \(c_i\) is larger than some given parameter \(\epsilon > 0\). If not, but \(c_i\) is strictly positive, the perturbation will be reduced by a multiplier \(\rho \in (0,1)\). Otherwise, the new perturbation will be set to \(\xi (\theta^l_c)_i^{} + ( 1 - \xi ) ( c_i^l - c_i^{} )\) for some factor \(\xi \in (0,1)\). Identical rules are used to reduce the remaining primal and dual perturbations. The targets \(\mu_c^{l}\), \(\mu_c^{u}\), \(\mu_x^{l}\) and \(\mu_x^{u}\) will also be increased by the factor \(\beta \geq 1\) for those (primal and/or dual) variables with strictly positive perturbations so as to try to accelerate the convergence.

Ultimately the intention is to drive all the perturbations to zero. It can be shown that if the original problem (1)–(4) and (6) has a solution, the perturbations will be zero after a finite number of major iterations. Equally, if there is no interior solution (6), the sets of (primal and dual) variables that are necessarily at (one of) their bounds for all feasible points—we refer to these as implicit equalities—will be identified, as will the possibility that there is no point (interior or otherwise) in the primal and/or dual feasible regions.

Each major iteration requires the solution \(v = (x,c,z^l,z^u,y^l,y^u)\) of the nonlinear system (1), (2) and (7)–(9) for fixed perturbations, using a minor iteration. The minor iteration uses a stabilized (predictor-corrector) Newton method, in which the arc \(v(\alpha) = v + \alpha \dot{v} + \alpha^2 \ddot{v}\), \(\alpha \in [0,1]\), involving the standard Newton step \(\dot{v}\) for the equations (1), (2), (7) and (8), optionally augmented by a corrector \(\ddot{v}\) to account for the nonlinearity in (7) and (8), is truncated so as to ensure that

\[( c_i^{}(\alpha) - c^l_i + (\theta_c^l)_i^{} ) ( y^{l}_i(\alpha) + (\theta_y^l)_i^{} ) \geq \tau (\mu_c^{l})_i^{}, \;\;\; i = 1, \ldots , m,\]

\[( c_i^{}(\alpha) - c_i^u - (\theta_c^u)_i^{} ) ( y^{u}_i(\alpha) - (\theta_y^u)_i^{} ) \geq \tau (\mu_c^{u})_i^{}, \;\;\; i = 1, \ldots , m,\]

\[( x_j^{}(\alpha) - x^l_j + (\theta_x^l)_j^{} ) ( z^{l}_j(\alpha) + (\theta_z^l)_j^{} ) \geq \tau (\mu_x^{l})_j^{}, \;\;\; j = 1, \ldots , n,\]

and

\[( x_j^{}(\alpha) - x_j^u - (\theta_x^u)_j^{} ) ( z^{u}_j(\alpha) - (\theta_z^u)_j^{} ) \geq \tau (\mu_x^{u})_j^{}, \;\;\; j = 1, \ldots , n,\]

for some \(\tau \in (0,1)\), always holds, and also so that the norm of the residuals to (1), (2), (7) and (8) is reduced as much as possible. The Newton and corrector systems are solved using a factorization of the Jacobian of its defining functions (the so-called “augmented system” approach) or of a reduced system in which some of the trivial equations are eliminated (the “Schur-complement” approach). The factors are obtained using the package SBLS.

In order to make the solution as efficient as possible, the variables and constraints are reordered internally by the package QPP prior to solution. In particular, fixed variables, and free (unbounded on both sides) constraints are temporarily removed. In addition, an attempt to identify and remove linearly dependent equality constraints may be made by factorizing

\[\begin{split}\left(\begin{array}{cc}\alpha I & A^T_{\cal E} \\ A^{}_{\cal E} & 0 \end{array}\right),\end{split}\]

where \(A_{\cal E}\) denotes the gradients of the equality constraints and \(\alpha > 0\) is a given scaling factor, using SBLS, and examining small pivot blocks.

reference

The basic algorithm, its convergence analysis and results of numerical experiments are given in

C. Cartis and N. I. M. Gould, Finding a point n the relative interior of a polyhedron. Technical Report TR-2006-016, Rutherford Appleton Laboratory (2006).

matrix storage

The unsymmetric \(m\) by \(n\) matrix \(A\) may be presented and stored in a variety of convenient input formats.

Dense storage format: The matrix \(A\) is stored as a compact dense matrix by rows, that is, the values of the entries of each row in turn are stored in order within an appropriate real one-dimensional array. In this case, component \(n \ast i + j\) of the storage array A_val will hold the value \(A_{ij}\) for \(0 \leq i \leq m-1\), \(0 \leq j \leq n-1\). The string A_type = ‘dense’ should be specified.

Dense by columns storage format: The matrix \(A\) is stored as a compact dense matrix by columns, that is, the values of the entries of each column in turn are stored in order within an appropriate real one-dimensional array. In this case, component \(m \ast j + i\) of the storage array A_val will hold the value \(A_{ij}\) for \(0 \leq i \leq m-1\), \(0 \leq j \leq n-1\). The string A_type = ‘dense_by_columns’ should be specified.

Sparse co-ordinate storage format: Only the nonzero entries of the matrices are stored. For the \(l\)-th entry, \(0 \leq l \leq ne-1\), of \(A\), its row index i, column index j and value \(A_{ij}\), \(0 \leq i \leq m-1\), \(0 \leq j \leq n-1\), are stored as the \(l\)-th components of the integer arrays A_row and A_col and real array A_val, respectively, while the number of nonzeros is recorded as A_ne = \(ne\). The string A_type = ‘coordinate’should be specified.

Sparse row-wise storage format: Again only the nonzero entries are stored, but this time they are ordered so that those in row i appear directly before those in row i+1. For the i-th row of \(A\) the i-th component of the integer array A_ptr holds the position of the first entry in this row, while A_ptr(m) holds the total number of entries. The column indices j, \(0 \leq j \leq n-1\), and values \(A_{ij}\) of the nonzero entries in the i-th row are stored in components l = A_ptr(i), \(\ldots\), A_ptr(i+1)-1, \(0 \leq i \leq m-1\), of the integer array A_col, and real array A_val, respectively. For sparse matrices, this scheme almost always requires less storage than its predecessor. The string A_type = ‘sparse_by_rows’ should be specified.

Sparse column-wise storage format: Once again only the nonzero entries are stored, but this time they are ordered so that those in column j appear directly before those in column j+1. For the j-th column of \(A\) the j-th component of the integer array A_ptr holds the position of the first entry in this column, while A_ptr(n) holds the total number of entries. The row indices i, \(0 \leq i \leq m-1\), and values \(A_{ij}\) of the nonzero entries in the j-th columnsare stored in components l = A_ptr(j), \(\ldots\), A_ptr(j+1)-1, \(0 \leq j \leq n-1\), of the integer array A_row, and real array A_val, respectively. As before, for sparse matrices, this scheme almost always requires less storage than the co-ordinate format. The string A_type = ‘sparse_by_columns’ should be specified.

introduction to function calls

To solve a given problem, functions from the wcp package must be called in the following order:

• wcp_initialize - provide default control parameters and set up initial data structures

• wcp_read_specfile (optional) - override control values by reading replacement values from a file

• wcp_import - set up problem data structures and fixed values

• wcp_reset_control (optional) - possibly change control parameters if a sequence of problems are being solved

• wcp_find_wcp - find a well-centered point

• wcp_information (optional) - recover information about the solution and solution process

• wcp_terminate - deallocate data structures

See the examples section for illustrations of use.

callable functions

o.. _global:

overview of functions provided

// typedefs

typedef float spc_;
typedef double rpc_;
typedef int ipc_;

// structs

struct wcp_control_type;
struct wcp_inform_type;
struct wcp_time_type;

// function calls

void wcp_initialize(void **data, struct wcp_control_type *control, ipc_ *status);
void wcp_read_specfile(struct wcp_control_type *control, const char specfile[]);

void wcp_import(
    struct wcp_control_type *control,
    void **data,
    ipc_ *status,
    ipc_ n,
    ipc_ m,
    const char A_type[],
    ipc_ A_ne,
    const ipc_ A_row[],
    const ipc_ A_col[],
    const ipc_ A_ptr[]
);

void wcp_reset_control(
    struct wcp_control_type *control,
    void **data,
    ipc_ *status
);

void wcp_find_wcp(
    void **data,
    ipc_ *status,
    ipc_ n,
    ipc_ m,
    const rpc_ g[],
    ipc_ a_ne,
    const rpc_ A_val[],
    const rpc_ c_l[],
    const rpc_ c_u[],
    const rpc_ x_l[],
    const rpc_ x_u[],
    rpc_ x[],
    rpc_ c[],
    rpc_ y_l[],
    rpc_ y_u[],
    rpc_ z_l[],
    rpc_ z_u[],
    ipc_x_stat[],
    ipc_c_stat[]
);

void wcp_information(void **data, struct wcp_inform_type *inform, ipc_*status);

void wcp_terminate(
    void **data,
    struct wcp_control_type *control,
    struct wcp_inform_type *inform
);

typedefs

typedef float spc_

spc_ is real single precision

typedef double rpc_

rpc_ is the real working precision used, but may be changed to float by defining the preprocessor variable SINGLE.

typedef int ipc_

ipc_ is the default integer word length used, but may be changed to int64_t by defining the preprocessor variable INTEGER_64.

function calls

void wcp_initialize(void **data, struct wcp_control_type *control, ipc_ *status)

Set default control values and initialize private data

Parameters:

data	holds private internal data
control	is a struct containing control information (see wcp_control_type)
status	is a scalar variable of type ipc_, that gives the exit status from the package. Possible values are (currently): 0 The initialization was successful.

void wcp_read_specfile(struct wcp_control_type *control, const char specfile[])

Read the content of a specification file, and assign values associated with given keywords to the corresponding control parameters. An in-depth discussion of specification files is available, and a detailed list of keywords with associated default values is provided in $GALAHAD/src/wcp/WCP.template. See also Table 2.1 in the Fortran documentation provided in $GALAHAD/doc/wcp.pdf for a list of how these keywords relate to the components of the control structure.

Parameters:

control	is a struct containing control information (see wcp_control_type)
specfile	is a character string containing the name of the specification file

void wcp_import(
    struct wcp_control_type *control,
    void **data,
    ipc_ *status,
    ipc_ n,
    ipc_ m,
    const char A_type[],
    ipc_ A_ne,
    const ipc_ A_row[],
    const ipc_ A_col[],
    const ipc_ A_ptr[]
)

Import problem data into internal storage prior to solution.

Parameters:

control	is a struct whose members provide control paramters for the remaining prcedures (see wcp_control_type)
data	holds private internal data
status	is a scalar variable of type ipc_, that gives the exit status from the package. Possible values are: 0 The import was successful -1 An allocation error occurred. A message indicating the offending array is written on unit control.error, and the returned allocation status and a string containing the name of the offending array are held in inform.alloc_status and inform.bad_alloc respectively. -2 A deallocation error occurred. A message indicating the offending array is written on unit control.error and the returned allocation status and a string containing the name of the offending array are held in inform.alloc_status and inform.bad_alloc respectively. -3 The restrictions n > 0 or m > 0 or requirement that a type contains its relevant string ‘dense’, ‘coordinate’, ‘sparse_by_rows’, ‘diagonal’, ‘scaled_identity’, ‘identity’, ‘zero’ or ‘none’ has been violated.
n	is a scalar variable of type ipc_, that holds the number of variables.
m	is a scalar variable of type ipc_, that holds the number of general linear constraints.
A_type	is a one-dimensional array of type char that specifies the unsymmetric storage scheme used for the constraint Jacobian, \(A\). It should be one of ‘coordinate’, ‘sparse_by_rows’ or ‘dense; lower or upper case variants are allowed.
A_ne	is a scalar variable of type ipc_, that holds the number of entries in \(A\) in the sparse co-ordinate storage scheme. It need not be set for any of the other schemes.
A_row	is a one-dimensional array of size A_ne and type ipc_, that holds the row indices of \(A\) in the sparse co-ordinate storage scheme. It need not be set for any of the other schemes, and in this case can be NULL.
A_col	is a one-dimensional array of size A_ne and type ipc_, that holds the column indices of \(A\) in either the sparse co-ordinate, or the sparse row-wise storage scheme. It need not be set when the dense or diagonal storage schemes are used, and in this case can be NULL.
A_ptr	is a one-dimensional array of size n+1 and type ipc_, that holds the starting position of each row of \(A\), as well as the total number of entries, in the sparse row-wise storage scheme. It need not be set when the other schemes are used, and in this case can be NULL.

void wcp_reset_control(
    struct wcp_control_type *control,
    void **data,
    ipc_ *status
)

Reset control parameters after import if required.

Parameters:

control	is a struct whose members provide control paramters for the remaining prcedures (see wcp_control_type)
data	holds private internal data
status	is a scalar variable of type ipc_, that gives the exit status from the package. Possible values are: 0 The import was successful.

void wcp_find_wcp(
    void **data,
    ipc_ *status,
    ipc_ n,
    ipc_ m,
    const rpc_ g[],
    ipc_ a_ne,
    const rpc_ A_val[],
    const rpc_ c_l[],
    const rpc_ c_u[],
    const rpc_ x_l[],
    const rpc_ x_u[],
    rpc_ x[],
    rpc_ c[],
    rpc_ y_l[],
    rpc_ y_u[],
    rpc_ z_l[],
    rpc_ z_u[],
    ipc_ x_stat[],
    ipc_ c_stat[]
)

Find a well-centered point in the feasible region

Parameters:

data	holds private internal data
status	is a scalar variable of type ipc_, that gives the entry and exit status from the package. Possible exit values are: 0 The run was successful -1 An allocation error occurred. A message indicating the offending array is written on unit control.error, and the returned allocation status and a string containing the name of the offending array are held in inform.alloc_status and inform.bad_alloc respectively. -2 A deallocation error occurred. A message indicating the offending array is written on unit control.error and the returned allocation status and a string containing the name of the offending array are held in inform.alloc_status and inform.bad_alloc respectively. -3 The restrictions n > 0 and m > 0 or requirement that a type contains its relevant string ‘dense’, ‘coordinate’, ‘sparse_by_rows’, ‘diagonal’, ‘scaled_identity’, ‘identity’, ‘zero’ or ‘none’ has been violated. -4 The constraint bounds are inconsistent. -5 The constraints appear to have no feasible point. -9 The analysis phase of the factorization failed; the return status from the factorization package is given in the component inform.factor_status -10 The factorization failed; the return status from the factorization package is given in the component inform.factor_status. -11 The solution of a set of linear equations using factors from the factorization package failed; the return status from the factorization package is given in the component inform.factor_status. -16 The problem is so ill-conditioned that further progress is impossible. -17 The step is too small to make further impact. -18 Too many iterations have been performed. This may happen if control.maxit is too small, but may also be symptomatic of a badly scaled problem. -19 The CPU time limit has been reached. This may happen if control.cpu_time_limit is too small, but may also be symptomatic of a badly scaled problem.
n	is a scalar variable of type ipc_, that holds the number of variables
m	is a scalar variable of type ipc_, that holds the number of general linear constraints.
g	is a one-dimensional array of size n and type rpc_, that holds the target vector \(g\). The j-th component of g, j = 0, … , n-1, contains \(g_j\).
a_ne	is a scalar variable of type ipc_, that holds the number of entries in the constraint Jacobian matrix \(A\).
A_val	is a one-dimensional array of size a_ne and type rpc_, that holds the values of the entries of the constraint Jacobian matrix \(A\) in any of the available storage schemes.
c_l	is a one-dimensional array of size m and type rpc_, that holds the lower bounds \(c^l\) on the constraints \(A x\). The i-th component of c_l, i = 0, … , m-1, contains \(c^l_i\).
c_u	is a one-dimensional array of size m and type rpc_, that holds the upper bounds \(c^l\) on the constraints \(A x\). The i-th component of c_u, i = 0, … , m-1, contains \(c^u_i\).
x_l	is a one-dimensional array of size n and type rpc_, that holds the lower bounds \(x^l\) on the variables \(x\). The j-th component of x_l, j = 0, … , n-1, contains \(x^l_j\).
x_u	is a one-dimensional array of size n and type rpc_, that holds the upper bounds \(x^l\) on the variables \(x\). The j-th component of x_u, j = 0, … , n-1, contains \(x^l_j\).
x	is a one-dimensional array of size n and type rpc_, that holds the values \(x\) of the optimization variables. The j-th component of x, j = 0, … , n-1, contains \(x_j\).
c	is a one-dimensional array of size m and type rpc_, that holds the residual \(c(x)\). The i-th component of c, i = 0, … , m-1, contains \(c_i(x)\).
y_l	is a one-dimensional array of size n and type rpc_, that holds the values \(y^l\) of the Lagrange multipliers for the lower bounds on the general linear constraints. The j-th component of y_l, i = 0, … , m-1, contains \(y^l_i\).
y_u	is a one-dimensional array of size n and type rpc_, that holds the values \(y^u\) of the Lagrange multipliers for the upper bounds on the general linear constraints. The j-th component of y_u, i = 0, … , m-1, contains \(y^u_i\).
z_l	is a one-dimensional array of size n and type rpc_, that holds the values \(z^l\) of the dual variables for the lower bounds on the variables. The j-th component of z_l, j = 0, … , n-1, contains \(z^l_j\).
z_u	is a one-dimensional array of size n and type rpc_, that holds the values \(z^u\) of the dual variables for the upper bounds on the variables. The j-th component of z_u, j = 0, … , n-1, contains \(z^u_j\).
x_stat	is a one-dimensional array of size n and type ipc_, that gives the optimal status of the problem variables. If x_stat(j) is negative, the variable \(x_j\) most likely lies on its lower bound, if it is positive, it lies on its upper bound, and if it is zero, it lies between its bounds.
c_stat	is a one-dimensional array of size m and type ipc_, that gives the optimal status of the general linear constraints. If c_stat(i) is negative, the constraint value \(a_i^T x\) most likely lies on its lower bound, if it is positive, it lies on its upper bound, and if it is zero, it lies between its bounds.

void wcp_information(void **data, struct wcp_inform_type *inform, ipc_ *status)

Provides output information.

Parameters:

data	holds private internal data
inform	is a struct containing output information (see wcp_inform_type)
status	is a scalar variable of type ipc_, that gives the exit status from the package. Possible values are (currently): 0 The values were recorded successfully

void wcp_terminate(
    void **data,
    struct wcp_control_type *control,
    struct wcp_inform_type *inform
)

Deallocate all internal private storage.

Parameters:

data	holds private internal data
control	is a struct containing control information (see wcp_control_type)
inform	is a struct containing output information (see wcp_inform_type)

available structures

wcp_control_type structure

#include <galahad_wcp.h>

struct wcp_control_type {
    // components

    bool f_indexing;
    ipc_ error;
    ipc_ out;
    ipc_ print_level;
    ipc_ start_print;
    ipc_ stop_print;
    ipc_ maxit;
    ipc_ initial_point;
    ipc_ factor;
    ipc_ max_col;
    ipc_ indmin;
    ipc_ valmin;
    ipc_ itref_max;
    ipc_ infeas_max;
    ipc_ perturbation_strategy;
    ipc_ restore_problem;
    rpc_ infinity;
    rpc_ stop_p;
    rpc_ stop_d;
    rpc_ stop_c;
    rpc_ prfeas;
    rpc_ dufeas;
    rpc_ mu_target;
    rpc_ mu_accept_fraction;
    rpc_ mu_increase_factor;
    rpc_ required_infeas_reduction;
    rpc_ implicit_tol;
    rpc_ pivot_tol;
    rpc_ pivot_tol_for_dependencies;
    rpc_ zero_pivot;
    rpc_ perturb_start;
    rpc_ alpha_scale;
    rpc_ identical_bounds_tol;
    rpc_ reduce_perturb_factor;
    rpc_ reduce_perturb_multiplier;
    rpc_ insufficiently_feasible;
    rpc_ perturbation_small;
    rpc_ cpu_time_limit;
    rpc_ clock_time_limit;
    bool remove_dependencies;
    bool treat_zero_bounds_as_general;
    bool just_feasible;
    bool balance_initial_complementarity;
    bool use_corrector;
    bool space_critical;
    bool deallocate_error_fatal;
    bool record_x_status;
    bool record_c_status;
    char prefix[31];
    struct fdc_control_type fdc_control;
    struct sbls_control_type sbls_control;
};

detailed documentation

control derived type as a C struct

components

bool f_indexing

use C or Fortran sparse matrix indexing

ipc_ error

error and warning diagnostics occur on stream error

ipc_ out

general output occurs on stream out

ipc_ print_level

the level of output required is specified by print_level

ipc_ start_print

any printing will start on this iteration

ipc_ stop_print

any printing will stop on this iteration

ipc_ maxit

at most maxit inner iterations are allowed

ipc_ initial_point

how to choose the initial point. Possible values are

• 0 the values input in X, shifted to be at least prfeas from their nearest bound, will be used

• 1 the nearest point to the “bound average” 0.5(X_l+X_u) that satisfies the linear constraints will be used

ipc_ factor

the factorization to be used. Possible values are

• 0 automatic

• 1 Schur-complement factorization

• 2 augmented-system factorization

ipc_ max_col

the maximum number of nonzeros in a column of A which is permitted with the Schur-complement factorization

ipc_ indmin

an initial guess as to the integer workspace required by SBLS

ipc_ valmin

an initial guess as to the real workspace required by SBLS

ipc_ itref_max

the maximum number of iterative refinements allowed

ipc_ infeas_max

the number of iterations for which the overall infeasibility of the problem is not reduced by at least a factor .required_infeas_reduction before the problem is flagged as infeasible (see required_infeas_reducti

ipc_ perturbation_strategy

the strategy used to reduce relaxed constraint bounds. Possible values are

• 0 do not perturb the constraints

• 1 reduce all perturbations by the same amount with linear reduction

• 2 reduce each perturbation as much as possible with linear reduction

• 3 reduce all perturbations by the same amount with superlinear reduction

• 4 reduce each perturbation as much as possible with superlinear reduction

ipc_ restore_problem

indicate whether and how much of the input problem should be restored on output. Possible values are

• 0 nothing restored

• 1 scalar and vector parameters

• 2 all parameters

rpc_ infinity

any bound larger than infinity in modulus will be regarded as infinite

rpc_ stop_p

the required accuracy for the primal infeasibility

rpc_ stop_d

the required accuracy for the dual infeasibility

rpc_ stop_c

the required accuracy for the complementarity

rpc_ prfeas

initial primal variables will not be closer than prfeas from their bound

rpc_ dufeas

initial dual variables will not be closer than dufeas from their bounds

rpc_ mu_target

the target value of the barrier parameter. If mu_target is not positive, it will be reset to an appropriate value

rpc_ mu_accept_fraction

the complemtary slackness x_i.z_i will be judged to lie within an acceptable margin around its target value mu as soon as mu_accept_fraction * mu <= x_i.z_i <= ( 1 / mu_accept_fraction ) * mu; the perturbations will be reduced as soon as all of the complemtary slacknesses x_i.z_i lie within acceptable bounds. mu_accept_fraction will be reset to ensure that it lies in the interval (0,1]

rpc_ mu_increase_factor

the target value of the barrier parameter will be increased by mu_increase_factor for infeasible constraints every time the perturbations are adjusted

rpc_ required_infeas_reduction

if the overall infeasibility of the problem is not reduced by at least a factor required_infeas_reduction over .infeas_max iterations, the problem is flagged as infeasible (see infeas_max)

rpc_ implicit_tol

any primal or dual variable that is less feasible than implicit_tol will be regarded as defining an implicit constraint

rpc_ pivot_tol

the threshold pivot used by the matrix factorization. See the documentation for SBLS for details (obsolete)

rpc_ pivot_tol_for_dependencies

the threshold pivot used by the matrix factorization when attempting to detect linearly dependent constraints. See the documentation for SBLS for details (obsolete)

rpc_ zero_pivot

any pivots smaller than zero_pivot in absolute value will be regarded to zero when attempting to detect linearly dependent constraints (obsolete)

rpc_ perturb_start

the constraint bounds will initially be relaxed by perturb_start; this perturbation will subsequently be reduced to zero. If perturb_start < 0, the amount by which the bounds are relaxed will be computed automatically

rpc_ alpha_scale

the test for rank defficiency will be to factorize

\[\begin{split}\left(\begin{array}{cc}\alpha I & A^T_{\cal E} \\ A^{}_{\cal E} & 0 \end{array}\right)\end{split}\]

for \(\alpha =\) alpha_scale

rpc_ identical_bounds_tol

any pair of constraint bounds (c_l,c_u) or (x_l,x_u) that are closer tha identical_bounds_tol will be reset to the average of their values

rpc_ reduce_perturb_factor

the constraint perturbation will be reduced as follows:

• • if the variable lies outside a bound, the corresponding perturbation will be reduced to reduce_perturb_factor * current pertubation

  • • ( 1 - reduce_perturb_factor ) * violation

• • otherwise, if the variable lies within insufficiently_feasible of its bound the pertubation will be reduced to

  • • reduce_perturb_multiplier * current pertubation

• • otherwise if will be set to zero

rpc_ reduce_perturb_multiplier

see reduce_perturb_factor

rpc_ insufficiently_feasible

see reduce_perturb_factor

rpc_ perturbation_small

if the maximum constraint pertubation is smaller than perturbation_small and the violation is smaller than implicit_tol, the method will deduce that there is a feasible point but no interior

rpc_ cpu_time_limit

the maximum CPU time allowed (-ve means infinite)

rpc_ clock_time_limit

the maximum elapsed clock time allowed (-ve means infinite)

bool remove_dependencies

the equality constraints will be preprocessed to remove any linear dependencies if true

bool treat_zero_bounds_as_general

any problem bound with the value zero will be treated as if it were a general value if true

bool just_feasible

if .just_feasible is true, the algorithm will stop as soon as a feasible point is found. Otherwise, the optimal solution to the problem will be found

bool balance_initial_complementarity

if .balance_initial_complementarity is .true. the initial complemetarity will be balanced

bool use_corrector

if .use_corrector, a corrector step will be used

bool space_critical

if .space_critical true, every effort will be made to use as little space as possible. This may result in longer computation time

bool deallocate_error_fatal

if .deallocate_error_fatal is true, any array/pointer deallocation error will terminate execution. Otherwise, computation will continue

bool record_x_status

if .record_x_status is true, the array inform.X_status will be allocated and the status of the bound constraints will be reported on exit.

bool record_c_status

if .record_c_status is true, the array inform.C_status will be allocated and the status of the general constraints will be reported on exit.

char prefix[31]

all output lines will be prefixed by .prefix(2:LEN(TRIM(.prefix))-1) where .prefix contains the required string enclosed in quotes, e.g. “string” or ‘string’

struct fdc_control_type fdc_control

control parameters for FDC

struct sbls_control_type sbls_control

control parameters for SBLS

wcp_time_type structure

#include <galahad_wcp.h>

struct wcp_time_type {
    // components

    rpc_ total;
    rpc_ preprocess;
    rpc_ find_dependent;
    rpc_ analyse;
    rpc_ factorize;
    rpc_ solve;
    rpc_ clock_total;
    rpc_ clock_preprocess;
    rpc_ clock_find_dependent;
    rpc_ clock_analyse;
    rpc_ clock_factorize;
    rpc_ clock_solve;
};

detailed documentation

time derived type as a C struct

components

rpc_ total

the total CPU time spent in the package

rpc_ preprocess

the CPU time spent preprocessing the problem

rpc_ find_dependent

the CPU time spent detecting linear dependencies

rpc_ analyse

the CPU time spent analysing the required matrices prior to factorization

rpc_ factorize

the CPU time spent factorizing the required matrices

rpc_ solve

the CPU time spent computing the search direction

rpc_ clock_total

the total clock time spent in the package

rpc_ clock_preprocess

the clock time spent preprocessing the problem

rpc_ clock_find_dependent

the clock time spent detecting linear dependencies

rpc_ clock_analyse

the clock time spent analysing the required matrices prior to factorization

rpc_ clock_factorize

the clock time spent factorizing the required matrices

rpc_ clock_solve

the clock time spent computing the search direction

wcp_inform_type structure

#include <galahad_wcp.h>

struct wcp_inform_type {
    // components

    ipc_ status;
    ipc_ alloc_status;
    char bad_alloc[81];
    ipc_ iter;
    ipc_ factorization_status;
    int64_t factorization_integer;
    int64_t factorization_real;
    ipc_ nfacts;
    ipc_ c_implicit;
    ipc_ x_implicit;
    ipc_ y_implicit;
    ipc_ z_implicit;
    rpc_ obj;
    rpc_ mu_final_target_max;
    rpc_ non_negligible_pivot;
    bool feasible;
    struct wcp_time_type time;
    struct fdc_inform_type fdc_inform;
    struct sbls_inform_type sbls_inform;
};

detailed documentation

inform derived type as a C struct

components

ipc_ status

return status. See WCP_solve for details

ipc_ alloc_status

the status of the last attempted allocation/deallocation

char bad_alloc[81]

the name of the array for which an allocation/deallocation error occurred

ipc_ iter

the total number of iterations required

ipc_ factorization_status

the return status from the factorization

int64_t factorization_integer

the total integer workspace required for the factorization

int64_t factorization_real

the total real workspace required for the factorization

ipc_ nfacts

the total number of factorizations performed

ipc_ c_implicit

the number of general constraints that lie on (one) of their bounds for feasible solutions

ipc_ x_implicit

the number of variables that lie on (one) of their bounds for all feasible solutions

ipc_ y_implicit

the number of Lagrange multipliers for general constraints that lie on (one) of their bounds for all feasible solutions

ipc_ z_implicit

the number of dual variables that lie on (one) of their bounds for all feasible solutions

rpc_ obj

the value of the objective function at the best estimate of the solution determined by WCP_solve

rpc_ mu_final_target_max

the largest target value on termination

rpc_ non_negligible_pivot

the smallest pivot which was not judged to be zero when detecting linear dependent constraints

bool feasible

is the returned primal-dual “solution” strictly feasible?

struct wcp_time_type time

timings (see above)

struct fdc_inform_type fdc_inform

inform parameters for FDC

struct sbls_inform_type sbls_inform

inform parameters for SBLS

Index

example calls

This is an example of how to use the package to find a well-centred point; the code is available in $GALAHAD/src/wcp/C/wcpt.c . A variety of supported Hessian and constraint matrix storage formats are shown.

Notice that C-style indexing is used, and that this is flaggeed by setting control.f_indexing to false. The floating-point type rpc_ is set in galahad_precision.h to double by default, but to float if the preproccesor variable SINGLE is defined. Similarly, the integer type ipc_ from galahad_precision.h is set to int by default, but to int64_t if the preproccesor variable INTEGER_64 is defined.

/* wcpf.c */
/* Full test for the WCP C interface using C sparse matrix indexing */

#include <stdio.h>
#include <math.h>
#include "galahad_precision.h"
#include "galahad_cfunctions.h"
#include "galahad_wcp.h"

int main(void) {

    // Derived types
    void *data;
    struct wcp_control_type control;
    struct wcp_inform_type inform;

    // Set problem data
    ipc_ n = 3; // dimension
    ipc_ m = 2; // number of general constraints
    rpc_ g[] = {0.0, 2.0, 0.0};   // linear term in the objective
    ipc_ A_ne = 4; // Jacobian elements
    ipc_ A_row[] = {0, 0, 1, 1}; // row indices
    ipc_ A_col[] = {0, 1, 1, 2}; // column indices
    ipc_ A_ptr[] = {0, 2, 4}; // row pointers
    rpc_ A_val[] = {2.0, 1.0, 1.0, 1.0 }; // values
    rpc_ c_l[] = {1.0, 2.0};   // constraint lower bound
    rpc_ c_u[] = {2.0, 2.0};   // constraint upper bound
    rpc_ x_l[] = {-1.0, - INFINITY, - INFINITY}; // variable lower bound
    rpc_ x_u[] = {1.0, INFINITY, 2.0}; // variable upper bound

    // Set output storage
    rpc_ c[m]; // constraint values
    ipc_ x_stat[n]; // variable status
    ipc_ c_stat[m]; // constraint status
    char st = ' ';
    ipc_ status;

    printf(" C sparse matrix indexing\n\n");

    printf(" basic tests of wcp storage formats\n\n");

    for( ipc_ d=1; d <= 3; d++){

        // Initialize WCP
        wcp_initialize( &data, &control, &status );

        // Set user-defined control options
        control.f_indexing = false; // C sparse matrix indexing

        // Start from 0
        rpc_ x[] = {0.0,0.0,0.0};
        rpc_ y_l[] = {0.0,0.0};
        rpc_ y_u[] = {0.0,0.0};
        rpc_ z_l[] = {0.0,0.0,0.0};
        rpc_ z_u[] = {0.0,0.0,0.0};

        switch(d){
            case 1: // sparse co-ordinate storage
                st = 'C';
                wcp_import( &control, &data, &status, n, m,
                            "coordinate", A_ne, A_row, A_col, NULL );
                wcp_find_wcp( &data, &status, n, m, g, A_ne, A_val,
                              c_l, c_u, x_l, x_u, x, c, y_l, y_u, z_l, z_u,
                              x_stat, c_stat );
                break;
            printf(" case %1" i_ipc_ " break\n",d);
            case 2: // sparse by rows
                st = 'R';
                wcp_import( &control, &data, &status, n, m,
                             "sparse_by_rows", A_ne, NULL, A_col, A_ptr );
                wcp_find_wcp( &data, &status, n, m, g, A_ne, A_val,
                              c_l, c_u, x_l, x_u, x, c, y_l, y_u, z_l, z_u,
                              x_stat, c_stat );
                break;
            case 3: // dense
                st = 'D';
                ipc_ A_dense_ne = 6; // number of elements of A
                rpc_ A_dense[] = {2.0, 1.0, 0.0, 0.0, 1.0, 1.0};
                wcp_import( &control, &data, &status, n, m,
                             "dense", A_dense_ne, NULL, NULL, NULL );
                wcp_find_wcp( &data, &status, n, m, g, A_dense_ne, A_dense,
                              c_l, c_u, x_l, x_u, x, c, y_l, y_u, z_l, z_u,
                              x_stat, c_stat );
                break;
            }
        wcp_information( &data, &inform, &status );

        if(inform.status == 0){
            printf("%c:%6" i_ipc_ " iterations. Optimal objective value = %5.2f status = %1" i_ipc_ "\n",
                   st, inform.iter, inform.obj, inform.status);
        }else{
            printf("%c: WCP_solve exit status = %1" i_ipc_ "\n", st, inform.status);
        }
        //printf("x: ");
        //for( ipc_ i = 0; i < n; i++) printf("%f ", x[i]);
        //printf("\n");
        //printf("gradient: ");
        //for( ipc_ i = 0; i < n; i++) printf("%f ", g[i]);
        //printf("\n");

        // Delete internal workspace
        wcp_terminate( &data, &control, &inform );
    }
}

This is the same example, but now fortran-style indexing is used; the code is available in $GALAHAD/src/wcp/C/wcptf.c .

/* wcptf.c */
/* Full test for the WCP C interface using Fortran sparse matrix indexing */

#include <stdio.h>
#include <math.h>
#include "galahad_precision.h"
#include "galahad_cfunctions.h"
#include "galahad_wcp.h"

int main(void) {

    // Derived types
    void *data;
    struct wcp_control_type control;
    struct wcp_inform_type inform;

    // Set problem data
    ipc_ n = 3; // dimension
    ipc_ m = 2; // number of general constraints
    rpc_ g[] = {0.0, 2.0, 0.0};   // linear term in the objective
    ipc_ A_ne = 4; // Jacobian elements
    ipc_ A_row[] = {1, 1, 2, 2}; // row indices
    ipc_ A_col[] = {1, 2, 2, 3}; // column indices
    ipc_ A_ptr[] = {1, 3, 5}; // row pointers
    rpc_ A_val[] = {2.0, 1.0, 1.0, 1.0 }; // values
    rpc_ c_l[] = {1.0, 2.0};   // constraint lower bound
    rpc_ c_u[] = {2.0, 2.0};   // constraint upper bound
    rpc_ x_l[] = {-1.0, - INFINITY, - INFINITY}; // variable lower bound
    rpc_ x_u[] = {1.0, INFINITY, 2.0}; // variable upper bound

    // Set output storage
    rpc_ c[m]; // constraint values
    ipc_ x_stat[n]; // variable status
    ipc_ c_stat[m]; // constraint status
    char st = ' ';
    ipc_ status;

    printf(" Fortran sparse matrix indexing\n\n");

    printf(" basic tests of wcp storage formats\n\n");

    for( ipc_ d=1; d <= 3; d++){

        // Initialize WCP
        wcp_initialize( &data, &control, &status );

        // Set user-defined control options
        control.f_indexing = true; // Fortran sparse matrix indexing

        // Start from 0
        rpc_ x[] = {0.0,0.0,0.0};
        rpc_ y_l[] = {0.0,0.0};
        rpc_ y_u[] = {0.0,0.0};
        rpc_ z_l[] = {0.0,0.0,0.0};
        rpc_ z_u[] = {0.0,0.0,0.0};

        switch(d){
            case 1: // sparse co-ordinate storage
                st = 'C';
                wcp_import( &control, &data, &status, n, m,
                            "coordinate", A_ne, A_row, A_col, NULL );
                wcp_find_wcp( &data, &status, n, m, g, A_ne, A_val,
                              c_l, c_u, x_l, x_u, x, c, y_l, y_u, z_l, z_u,
                              x_stat, c_stat );
                break;
            printf(" case %1" i_ipc_ " break\n",d);
            case 2: // sparse by rows
                st = 'R';
                wcp_import( &control, &data, &status, n, m,
                             "sparse_by_rows", A_ne, NULL, A_col, A_ptr );
                wcp_find_wcp( &data, &status, n, m, g, A_ne, A_val,
                              c_l, c_u, x_l, x_u, x, c, y_l, y_u, z_l, z_u,
                              x_stat, c_stat );
                break;
            case 3: // dense
                st = 'D';
                ipc_ A_dense_ne = 6; // number of elements of A
                rpc_ A_dense[] = {2.0, 1.0, 0.0, 0.0, 1.0, 1.0};
                wcp_import( &control, &data, &status, n, m,
                             "dense", A_dense_ne, NULL, NULL, NULL );
                wcp_find_wcp( &data, &status, n, m, g, A_dense_ne, A_dense,
                              c_l, c_u, x_l, x_u, x, c, y_l, y_u, z_l, z_u,
                              x_stat, c_stat );
                break;
            }
        wcp_information( &data, &inform, &status );

        if(inform.status == 0){
            printf("%c:%6" i_ipc_ " iterations. Optimal objective value = %5.2f status = %1" i_ipc_ "\n",
                   st, inform.iter, inform.obj, inform.status);
        }else{
            printf("%c: WCP_solve exit status = %1" i_ipc_ "\n", st, inform.status);
        }
        //printf("x: ");
        //for( ipc_ i = 0; i < n; i++) printf("%f ", x[i]);
        //printf("\n");
        //printf("gradient: ");
        //for( ipc_ i = 0; i < n; i++) printf("%f ", g[i]);
        //printf("\n");

        // Delete internal workspace
        wcp_terminate( &data, &control, &inform );
    }
}