GALAHAD LSQP package#
purpose#
The lsqp package uses an interior-point trust-region method to solve a
given linear or separable convex quadratic program.
The aim is to minimize the separable quadratic objective function
In the special case where \(w = 0\), \(g = 0\) and \(f = 0\), the so-called analytic center of the feasible set will be found, while linear programming, or constrained least distance, problems may be solved by picking \(w = 0\), or \(g = 0\) and \(f = 0\), respectively.
See Section 4 of $GALAHAD/doc/lsqp.pdf for additiional details.
The more-modern package cqp offers similar functionality, and
is often to be preferred.
terminology#
Any required solution \(x\) necessarily satisfies the primal optimality conditions
method#
Primal-dual interior point methods iterate towards a point that satisfies these optimality conditions by ultimately aiming to satisfy (1a), (2a) and (3), while ensuring that (1b) and (2b) are satisfied as strict inequalities at each stage. Appropriate norms of the amounts by which (1a), (2a) and (3) fail to be satisfied are known as the primal and dual infeasibility, and the violation of complementary slackness, respectively. The fact that (1b) and (2b) are satisfied as strict inequalities gives such methods their other title, namely interior-point methods.
When \(w \neq 0\) or \(g \neq 0\), the method aims at each stage to reduce the overall violation of (1a), (2a) and (3), rather than reducing each of the terms individually. Given an estimate \(v = (x, \; c, \; y, \; y^{l}, \; y^{u}, \; z, \; z^{l}, \; z^{u})\) of the primal-dual variables, a correction \(\Delta v = \Delta (x, \; c, \; y, \; y^{l}, \; y^{u} ,\;z,\;z^{l} ,\;z^{u} )\) is obtained by solving a suitable linear system of Newton equations for the nonlinear systems (1a), (2a) and a parameterized perturbation of (3). An improved estimate \(v + \alpha \Delta v\) is then used, where the step-size \(\alpha\) is chosen as close to 1.0 as possible while ensuring both that (1b) and (2b) continue to hold and that the individual components which make up the complementary slackness (3) do not deviate too significantly from their average value. The parameter that controls the perturbation of (3) is ultimately driven to zero.
The Newton equations are solved by applying the matrix factorization
package SBLS, but there are options
to factorize the matrix as a whole (the so-called “augmented system”
approach), to perform a block elimination first (the “Schur-complement”
approach), or to let the method itself decide which of the two
previous options is more appropriate.
The “Schur-complement” approach is usually to be preferred when all the
weights are nonzero or when every variable is bounded (at least one side),
but may be inefficient if any of the columns of \(A\) is too dense.
When \(w = 0\) and \(g = 0\), the method aims instead firstly to find an interior primal feasible point, that is to ensure that (1a) is satisfied. One this has been achieved, attention is switched to mninizing the potential function
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.
references#
The basic algorithm is that of
Y. Zhang, ``On the convergence of a class of infeasible interior-point methods for the horizontal linear complementarity problem’’. SIAM J. Optimization 4(1) (1994) 208-227,
with a number of enhancements described by
A. R. Conn, N. I. M. Gould, D. Orban and Ph. L. Toint, ``A primal-dual trust-region algorithm for minimizing a non-convex function subject to general inequality and linear equality constraints’’. Mathematical Programming **87* (1999) 215-249.
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 columns are 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 lsqp package must be called in the following order:
lsqp_initialize - provide default control parameters and set up initial data structures
lsqp_read_specfile (optional) - override control values by reading replacement values from a file
lsqp_import - set up problem data structures and fixed values
lsqp_reset_control (optional) - possibly change control parameters if a sequence of problems are being solved
lsqp_solve_qp - solve the quadratic program
lsqp_information (optional) - recover information about the solution and solution process
lsqp_terminate - deallocate data structures
See the examples section for illustrations of use.
callable functions#
overview of functions provided#
// typedefs typedef float spc_; typedef double rpc_; typedef int ipc_; // structs struct lsqp_control_type; struct lsqp_inform_type; struct lsqp_time_type; // function calls void lsqp_initialize( void **data, struct lsqp_control_type* control, ipc_ *status ); void lsqp_read_specfile( struct lsqp_control_type* control, const char specfile[] ); void lsqp_import( struct lsqp_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 lsqp_reset_control( struct lsqp_control_type* control, void **data, ipc_ *status ); void lsqp_solve_qp( void **data, ipc_ *status, ipc_ n, ipc_ m, const rpc_ w[], const rpc_ x0[], const rpc_ g[], const rpc_ f, 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[], rpc_ z[], ipc_ x_stat[], ipc_ c_stat[] ); void lsqp_information(void **data, struct lsqp_inform_type* inform, ipc_ *status); void lsqp_terminate( void **data, struct lsqp_control_type* control, struct lsqp_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 REAL_32 or (if supported) to
__real128 using the variable REAL_128.
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 lsqp_initialize( void **data, struct lsqp_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 lsqp_control_type) |
status |
is a scalar variable of type ipc_, that gives the exit status from the package. Possible values are (currently):
|
void lsqp_read_specfile( struct lsqp_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/lsqp/LSQP.template. See also Table 2.1 in the Fortran documentation provided in $GALAHAD/doc/lsqp.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 lsqp_control_type) |
specfile |
is a character string containing the name of the specification file |
void lsqp_import( struct lsqp_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 lsqp_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:
|
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 lsqp_reset_control( struct lsqp_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 lsqp_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:
|
void lsqp_solve_qp( void **data, ipc_ *status, ipc_ n, ipc_ m, const rpc_ w[], const rpc_ x0[], const rpc_ g[], const rpc_ f, 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[], rpc_ z[], ipc_ x_stat[], ipc_ c_stat[] )
Solve the separable convex quadratic program.
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:
|
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. |
w |
is a one-dimensional array of size n and type rpc_, that holds the values of the weights \(w\). |
x0 |
is a one-dimensional array of size n and type rpc_, that holds the values of the shifts \(x^0\). |
g |
is a one-dimensional array of size n and type rpc_, that holds the linear term \(g\) of the objective function. The j-th component of g, j = 0, … , n-1, contains \(g_j\). |
f |
is a scalar of type rpc_, that holds the constant term \(f\) of the objective function. |
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 |
is a one-dimensional array of size n and type rpc_, that holds the values \(y\) of the Lagrange multipliers for the general linear constraints. The j-th component of y, i = 0, … , m-1, contains \(y_i\). |
z |
is a one-dimensional array of size n and type rpc_, that holds the values \(z\) of the dual variables. The j-th component of z, j = 0, … , n-1, contains \(z_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 lsqp_information(void **data, struct lsqp_inform_type* inform, ipc_ *status)
Provides output information.
Parameters:
data |
holds private internal data |
inform |
is a struct containing output information (see lsqp_inform_type) |
status |
is a scalar variable of type ipc_, that gives the exit status from the package. Possible values are (currently):
|
void lsqp_terminate( void **data, struct lsqp_control_type* control, struct lsqp_inform_type* inform )
Deallocate all internal private storage.
Parameters:
data |
holds private internal data |
control |
is a struct containing control information (see lsqp_control_type) |
inform |
is a struct containing output information (see lsqp_inform_type) |
available structures#
lsqp_control_type structure#
#include <galahad_lsqp.h> struct lsqp_control_type { // components bool f_indexing; ipc_ error; ipc_ out; ipc_ print_level; ipc_ start_print; ipc_ stop_print; ipc_ maxit; ipc_ factor; ipc_ max_col; ipc_ indmin; ipc_ valmin; ipc_ itref_max; ipc_ infeas_max; ipc_ muzero_fixed; ipc_ restore_problem; ipc_ indicator_type; ipc_ extrapolate; ipc_ path_history; ipc_ path_derivatives; ipc_ fit_order; ipc_ sif_file_device; rpc_ infinity; rpc_ stop_p; rpc_ stop_d; rpc_ stop_c; rpc_ prfeas; rpc_ dufeas; rpc_ muzero; rpc_ reduce_infeas; rpc_ potential_unbounded; rpc_ pivot_tol; rpc_ pivot_tol_for_dependencies; rpc_ zero_pivot; rpc_ identical_bounds_tol; rpc_ mu_min; rpc_ indicator_tol_p; rpc_ indicator_tol_pd; rpc_ indicator_tol_tapia; rpc_ cpu_time_limit; rpc_ clock_time_limit; bool remove_dependencies; bool treat_zero_bounds_as_general; bool just_feasible; bool getdua; bool puiseux; bool feasol; bool balance_initial_complentarity; bool use_corrector; bool array_syntax_worse_than_do_loop; bool space_critical; bool deallocate_error_fatal; bool generate_sif_file; char sif_file_name[31]; 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_ 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 .reduce_infeas before the problem is flagged as infeasible (see reduce_infeas)
ipc_ muzero_fixed
the initial value of the barrier parameter will not be changed for the first muzero_fixed iterations
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
ipc_ indicator_type
specifies the type of indicator function used. Possible values are
1 primal indicator: constraint active if and only if the distance to nearest bound \(\leq\).indicator_p_tol
2 primal-dual indicator: constraint active if and only if the distance to nearest bound \(\leq\).indicator_tol_pd \* size of corresponding multiplier
3 primal-dual indicator: constraint active if and only if the distance to the nearest bound \(\leq\).indicator_tol_tapia \* distance to same bound at previous iteration
ipc_ extrapolate
should extrapolation be used to track the central path? Possible values
0 never
1 after the final major iteration
2 at each major iteration (unused at present)
ipc_ path_history
the maximum number of previous path points to use when fitting the data (unused at present)
ipc_ path_derivatives
the maximum order of path derivative to use (unused at present)
ipc_ fit_order
the order of (Puiseux) series to fit to the path data: $
to fit all data (unused at present)
ipc_ sif_file_device
specifies the unit number to write generated SIF file describing the current problem
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 bounds
rpc_ dufeas
initial dual variables will not be closer than dufeas from their bounds
rpc_ muzero
the initial value of the barrier parameter. If muzero is not positive, it will be reset to an appropriate value
rpc_ reduce_infeas
if the overall infeasibility of the problem is not reduced by at least a factor reduce_infeas over .infeas_max iterations, the problem is flagged as infeasible (see infeas_max)
rpc_ potential_unbounded
if W=0 and the potential function value is smaller than potential_unbounded * number of one-sided bounds, the analytic center will be flagged as unbounded
rpc_ pivot_tol
the threshold pivot used by the matrix factorization. See the documentation for SBLS for details
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
rpc_ zero_pivot
any pivots smaller than zero_pivot in absolute value will be regarded to zero when attempting to detect linearly dependent constraints
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_ mu_min
start terminal extrapolation when mu reaches mu_min
rpc_ indicator_tol_p
if .indicator_type = 1, a constraint/bound will be deemed to be active if and only if the distance to nearest bound $ \(\leq\).indicator_p_tol
rpc_ indicator_tol_pd
if .indicator_type = 2, a constraint/bound will be deemed to be active if and only if the distance to nearest bound $ \(\leq\).indicator_tol_pd \* size of corresponding multiplier
rpc_ indicator_tol_tapia
if .indicator_type = 3, a constraint/bound will be deemed to be active if and only if the distance to nearest bound $ \(\leq\).indicator_tol_tapia \* distance to same bound at previous iteration
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 getdua
if .getdua, is true, advanced initial values are obtained for the dual variables
bool puiseux
If extrapolation is to be used, decide between Puiseux and Taylor series.
bool feasol
if .feasol is true, the final solution obtained will be perturbed so tha variables close to their bounds are moved onto these bounds
bool balance_initial_complentarity
if .balance_initial_complentarity is true, the initial complemetarity is required to be balanced
bool use_corrector
if .use_corrector, a corrector step will be used
bool array_syntax_worse_than_do_loop
if .array_syntax_worse_than_do_loop is true, f77-style do loops will be used rather than f90-style array syntax for vector operations
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 generate_sif_file
if .generate_sif_file is .true. if a SIF file describing the current problem is to be generated
char sif_file_name[31]
name of generated SIF file containing input problem
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
lsqp_time_type structure#
#include <galahad_lsqp.h> struct lsqp_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
lsqp_inform_type structure#
#include <galahad_lsqp.h> struct lsqp_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_ nbacts; rpc_ obj; rpc_ potential; rpc_ non_negligible_pivot; bool feasible; struct lsqp_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 LSQP_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_ nbacts
the total number of “wasted” function evaluations during the linesearch
rpc_ obj
the value of the objective function at the best estimate of the solution determined by LSQP_solve_qp
rpc_ potential
the value of the logarithmic potential function sum -log(distance to constraint boundary)
rpc_ non_negligible_pivot
the smallest pivot which was not judged to be zero when detecting linear dependent constraints
bool feasible
is the returned “solution” feasible?
struct lsqp_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
example calls#
This is an example of how to use the package to solve a separable quadratic program; the code is available in $GALAHAD/src/lsqp/C/lsqpt.c . A variety of supported Hessian and constraint matrix storage formats are shown.
Notice that C-style indexing is used, and that this is flagged 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 preprocessor 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 preprocessor variable INTEGER_64 is defined.
/* lsqpt.c */
/* Full test for the LSQP C interface using C sparse matrix indexing */
#include <stdio.h>
#include <math.h>
#include "galahad_precision.h"
#include "galahad_cfunctions.h"
#include "galahad_lsqp.h"
#ifdef REAL_128
#include <quadmath.h>
#endif
int main(void) {
// Derived types
void *data;
struct lsqp_control_type control;
struct lsqp_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
rpc_ f = 1.0; // constant 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
rpc_ w[] = {1.0,1.0,1.0};
rpc_ x_0[] = {0.0,0.0,0.0};
// 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 qp storage formats\n\n");
for( ipc_ d=1; d <= 3; d++){
// Initialize LSQP
lsqp_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[] = {0.0,0.0};
rpc_ z[] = {0.0,0.0,0.0};
switch(d){
case 1: // sparse co-ordinate storage
st = 'C';
lsqp_import( &control, &data, &status, n, m,
"coordinate", A_ne, A_row, A_col, NULL );
lsqp_solve_qp( &data, &status, n, m, w, x_0, g, f,
A_ne, A_val, c_l, c_u, x_l, x_u, x, c, y, z,
x_stat, c_stat );
break;
printf(" case %1" i_ipc_ " break\n",d);
case 2: // sparse by rows
st = 'R';
lsqp_import( &control, &data, &status, n, m,
"sparse_by_rows", A_ne, NULL, A_col, A_ptr );
lsqp_solve_qp( &data, &status, n, m, w, x_0, g, f,
A_ne, A_val, c_l, c_u, x_l, x_u, x, c, y, z,
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};
lsqp_import( &control, &data, &status, n, m,
"dense", A_dense_ne, NULL, NULL, NULL );
lsqp_solve_qp( &data, &status, n, m, w, x_0, g, f,
A_dense_ne, A_dense, c_l, c_u, x_l, x_u,
x, c, y, z, x_stat, c_stat );
break;
}
lsqp_information( &data, &inform, &status );
if(inform.status == 0){
#ifdef REAL_128
// interim replacement for quad output: $GALAHAD/include/galahad_pquad_f.h
#include "galahad_pquad_f.h"
#else
printf("%c:%6" i_ipc_ " iterations. Optimal objective "
"value = %.2f status = %1" i_ipc_ "\n",
st, inform.iter, inform.obj, inform.status);
#endif
}else{
printf("%c: LSQP_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
lsqp_terminate( &data, &control, &inform );
}
}This is the same example, but now fortran-style indexing is used; the code is available in $GALAHAD/src/lsqp/C/lsqptf.c .
/* lsqptf.c */
/* Full test for the LSQP C interface using Fortran sparse matrix indexing */
#include <stdio.h>
#include <math.h>
#include "galahad_precision.h"
#include "galahad_cfunctions.h"
#include "galahad_lsqp.h"
#ifdef REAL_128
#include <quadmath.h>
#endif
int main(void) {
// Derived types
void *data;
struct lsqp_control_type control;
struct lsqp_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
rpc_ f = 1.0; // constant 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
rpc_ w[] = {1.0,1.0,1.0};
rpc_ x_0[] = {0.0,0.0,0.0};
// 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 qp storage formats\n\n");
for( ipc_ d=1; d <= 3; d++){
// Initialize LSQP
lsqp_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[] = {0.0,0.0};
rpc_ z[] = {0.0,0.0,0.0};
switch(d){
case 1: // sparse co-ordinate storage
st = 'C';
lsqp_import( &control, &data, &status, n, m,
"coordinate", A_ne, A_row, A_col, NULL );
lsqp_solve_qp( &data, &status, n, m, w, x_0, g, f,
A_ne, A_val, c_l, c_u, x_l, x_u, x, c, y, z,
x_stat, c_stat );
break;
printf(" case %1" i_ipc_ " break\n",d);
case 2: // sparse by rows
st = 'R';
lsqp_import( &control, &data, &status, n, m,
"sparse_by_rows", A_ne, NULL, A_col, A_ptr );
lsqp_solve_qp( &data, &status, n, m, w, x_0, g, f,
A_ne, A_val, c_l, c_u, x_l, x_u, x, c, y, z,
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};
lsqp_import( &control, &data, &status, n, m,
"dense", A_dense_ne, NULL, NULL, NULL );
lsqp_solve_qp( &data, &status, n, m, w, x_0, g, f,
A_dense_ne, A_dense, c_l, c_u, x_l, x_u,
x, c, y, z, x_stat, c_stat );
break;
}
lsqp_information( &data, &inform, &status );
if(inform.status == 0){
#ifdef REAL_128
// interim replacement for quad output: $GALAHAD/include/galahad_pquad_f.h
#include "galahad_pquad_f.h"
#else
printf("%c:%6" i_ipc_ " iterations. Optimal objective "
"value = %.2f status = %1" i_ipc_ "\n",
st, inform.iter, inform.obj, inform.status);
#endif
}else{
printf("%c: LSQP_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
lsqp_terminate( &data, &control, &inform );
}
}