overview of functions provided

// typedefs

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

// structs

struct expo_control_type;
struct expo_inform_type;
struct expo_time_type;

// function calls

void expo_initialize(
    void **data,
    struct expo_control_type* control,
    struct expo_inform_type* inform
);

void expo_read_specfile(struct expo_control_type* control, const char specfile[]);

void expo_import(
    struct expo_control_type* control,
    void **data,
    ipc_ *status,
    ipc_ n,
    ipc_ m,
    const char J_type[],
    ipc_ J_ne,
    const ipc_ J_row[],
    const ipc_ J_col[],
    const ipc_ J_ptr[],
    const char H_type[],
    ipc_ H_ne,
    const ipc_ H_row[],
    const ipc_ H_col[],
    const ipc_ H_ptr[]
);

void expo_reset_control(
    struct expo_control_type* control,
    void **data,
    ipc_ *status
);

void expo_solve_hessian_direct(
    void **data,
    void *userdata,
    ipc_ *status,
    ipc_ n,
    ipc_ m,
    ipc_ J_ne,
    ipc_ H_ne,
    const rpc_ c_l[],
    const rpc_ c_u[],
    const rpc_ x_l[],
    const rpc_ x_u[],
    rpc_ x[],
    rpc_ y[],
    rpc_ z[],
    rpc_ c[],
    rpc_ gl[],
    ipc_(*)(ipc_, ipc_, const rpc_[], rpc_, rpc_[],
             const void*) eval_fc,
    ipc_(*)(ipc_, ipc_, ipc_, const rpc_[], rpc_[], , rpc_[],
             const void*) eval_gj,
    ipc_(*)(ipc_, ipc_, ipc_, const rpc_[], const rpc_[], rpc_[],
             const void*) eval_hl
);

void expo_information(void **data, struct expo_inform_type* inform, ipc_ *status);

void expo_terminate(
    void **data,
    struct expo_control_type* control,
    struct expo_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 and structure names

The function and structure names described below are appropriate for the default real working precision (double) and integer word length (int32_t). To use the functions and structures with different precisions and integer word lengths, an additional suffix must be added to their names (and the arguments set accordingly). The appropriate suffices are:

_s for single precision (float) reals and standard 32-bit (int32_t) integers;

_q for quadruple precision (__real128) reals (if supported) and standard 32-bit (int32_t) integers;

_64 for standard precision (double) reals and 64-bit (int64_t) integers;

_s_64 for single precision (float) reals and 64-bit (int64_t) integers; and

_q_64 for quadruple precision (__real128) reals (if supported) and 64-bit (int64_t) integers.

Thus a call to arc_initialize below will instead be

void arc_initialize_s_64(void **data, struct arc_control_type_s_64* control,
                         int64_t *status)

if single precision (float) reals and 64-bit (int64_t) integers are required. Thus it is possible to call functions for this package with more that one precision and/or integer word length at same time. An example illustrates this feature.

function calls

void expo_initialize(
    void **data,
    struct expo_control_type* control,
    struct expo_inform_type* inform
)

Set default control values and initialize private data

Parameters:

data	holds private internal data
control	is a struct containing control information (see expo_control_type)
inform	is a struct containing output information (see expo_inform_type)

void expo_read_specfile(struct expo_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/expo/EXPO.template. See also Table 2.1 in the Fortran documentation provided in $GALAHAD/doc/expo.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 expo_control_type)
specfile	is a character string containing the name of the specification file

void expo_import(
    struct expo_control_type* control,
    void **data,
    ipc_ *status,
    ipc_ n,
    ipc_ m,
    const char J_type[],
    ipc_ J_ne,
    const ipc_ J_row[],
    const ipc_ J_col[],
    const ipc_ J_ptr[],
    const char H_type[],
    ipc_ H_ne,
    const ipc_ H_row[],
    const ipc_ H_col[],
    const ipc_ H_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 expo_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: 1 The import was successful, and the package is ready for the solve phase -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, m \(\geq\) 0 or requirement that J/H_type contains its relevant string ‘dense’, ‘dense_by_columns’, ‘coordinate’, ‘sparse_by_rows’, ‘sparse_by_columns’, ‘diagonal’ or ‘absent’ 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 constraints.
J_type	is a one-dimensional array of type char that specifies the unsymmetric storage scheme used for the Jacobian, \(J\). It should be one of ‘coordinate’, ‘sparse_by_rows’, ‘dense’ or ‘absent’, the latter if access to the Jacobian is via matrix-vector products; lower or upper case variants are allowed.
J_ne	is a scalar variable of type ipc_, that holds the number of entries in \(J\) in the sparse co-ordinate storage scheme. It need not be set for any of the other schemes.
J_row	is a one-dimensional array of size J_ne and type ipc_, that holds the row indices of \(J\) 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.
J_col	is a one-dimensional array of size J_ne and type ipc_, that holds the column indices of \(J\) 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.
J_ptr	is a one-dimensional array of size m+1 and type ipc_, that holds the starting position of each row of \(J\), 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.
H_type	is a one-dimensional array of type char that specifies the symmetric storage scheme used for the Hessian, \(H_L\). It should be one of ‘coordinate’, ‘sparse_by_rows’, ‘dense’, ‘diagonal’ or ‘absent’, the latter if access to \(H\) is via matrix-vector products; lower or upper case variants are allowed.
H_ne	is a scalar variable of type ipc_, that holds the number of entries in the lower triangular part of \(H_L\) in the sparse co-ordinate storage scheme. It need not be set for any of the other three schemes.
H_row	is a one-dimensional array of size H_ne and type ipc_, that holds the row indices of the lower triangular part of \(H\) in the sparse co-ordinate storage scheme. It need not be set for any of the other three schemes, and in this case can be NULL.
H_col	is a one-dimensional array of size H_ne and type ipc_, that holds the column indices of the lower triangular part of \(H_L\) 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.
H_ptr	is a one-dimensional array of size n+1 and type ipc_, that holds the starting position of each row of the lower triangular part of \(H_L\), 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 expo_reset_control(
    struct expo_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 expo_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: The import was successful, and the package is ready for the solve phase

void expo_solve_hessian_direct(
    void **data,
    void *userdata,
    ipc_ *status,
    ipc_ n,
    ipc_ m,
    ipc_ J_ne,
    ipc_ H_ne,
    const rpc_ c_l[],
    const rpc_ c_u[],
    const rpc_ x_l[],
    const rpc_ x_u[],
    rpc_ x[],
    rpc_ y[],
    rpc_ z[],
    rpc_ c[],
    rpc_ gl[],
    ipc_(*)(ipc_, ipc_, const rpc_[], rpc_[],
            const void*) eval_c,
    ipc_(*)(ipc_, ipc_, ipc_, const rpc_[], rpc_[],
            const void*) eval_j,
    ipc_(*)(ipc_, ipc_, ipc_, const rpc_[], const rpc_[], rpc_[],
            const void*) eval_h,
)

Find a local minimizer of a given constrained optimization problem.

This call is for the case where \(H(x,y) = \nabla_{xx}f(x) - \sum_i y_i \nabla_{xx}c_i(x)\) is provided specifically, and all function/derivative information is available by function calls.

Parameters:

data	holds private internal data
userdata	is a structure that allows data to be passed into the function and derivative evaluation programs.
status	is a scalar variable of type ipc_, that gives the entry and exit status from the package. On initial entry, status must be set to 1. 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 restriction n > 0, m \(\geq\) 0 or requirement that type contains its relevant string ‘dense’, ‘coordinate’, ‘sparse_by_rows’, or ‘diagonal’ has been violated. -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.max_it or control.max_eval 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. -82 The user has forced termination of solver by removing the file named control.alive_file from unit unit control.alive_unit.
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 constraints.
J_ne	is a scalar variable of type ipc_, that holds the number of entries in \(J\).
H_ne	is a scalar variable of type ipc_, that holds the number of entries in \(H_L\).
c_l	is a one-dimensional array of size m and type rpc_, that holds the values \(c_l\) of the lower bounds on the constraint functions \(c(x)\). The i-th component of c_l, \(i = 0, \ldots, m-1\), contains \(c_{li}\).
c_u	is a one-dimensional array of size m and type rpc_, that holds the values \(c_u\) of the upper bounds on the constraint functions \(c(x)\). The i-th component of c_u, \(i = 0, \ldots, m-1\), contains \(c_{ui}\).
x_l	is a one-dimensional array of size n and type rpc_, that holds the values \(x_l\) of the lower bounds on the optimization variables \(x\). The j-th component of x_l, \(j = 0, \ldots, n-1\), contains \(x_{lj}\).
x_u	is a one-dimensional array of size n and type rpc_, that holds the values \(x_u\) of the upper bounds on the optimization variables \(x\). The j-th component of x_u, \(j = 0, \ldots, n-1\), contains \(x_{uj}\).
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\). This should be set on input to an estimate of the minimizer.
y	is a one-dimensional array of size m and type rpc_, that holds the values \(y\) of the Lagrange multipliers. 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. The j-th component of z, j = 0, … , n-1, contains \(z_j\).
c	is a one-dimensional array of size m and type rpc_, that holds the constraints \(c(x)\). The i-th component of c, i = 0, … , n-1, contains \(c_i(x)\).
gl	is a one-dimensional array of size n and type rpc_, that holds the gradient \(g_L(x,y)\) of the Lagrangian function. The j-th component of gl, j = 0, … , n-1, contains \(g_{Lj}\).
eval_fc	is a user-supplied function that must have the following signature: ipc_ eval_fc( ipc_ n, const rpc_ x[], rpc_ f, rpc_ c[], const void *userdata ) The value of the objective function \(f(x)\) and the components of the constraint function \(c(x)\) evaluated at x= \(x\) must be assigned to f and c, respectively, and the function return value set to 0. If the evaluation is impossible at x, return should be set to a nonzero value. Data may be passed into eval_fc via the structure userdata.
eval_gj	is a user-supplied function that must have the following signature: ipc_ eval_gj( ipc_ n, ipc_ m, ipc_ jne, const rpc_ x[], rpc_ g[], rpc_ j[], const void *userdata ) The components of the gradient \(g = g(x)\) of the objective and Jacobian \(J = \nabla_x c(x\)) of the constraints must be assigned to g and to j, in the same order as presented to expo_import, and the function return value set to 0. If the evaluation is impossible at x, return should be set to a nonzero value. Data may be passed into eval_gj via the structure userdata.
eval_hl	is a user-supplied function that must have the following signature: ipc_ eval_hl( ipc_ n, ipc_ m, ipc_ hne, const rpc_ x[], const rpc_ y[], rpc_ h[], const void *userdata ) The nonzeros of the matrix \(H_L(x,y) = \nabla_{xx}f(x) -\sum_i y_i \nabla_{xx}c_i(x)\) of the Hessian of the Lagrangian function evaluated at x= \(x\) and y= \(y\) must be assigned to h in the same order as presented to expo_import, and the function return value set to 0. If the evaluation is impossible at x, return should be set to a nonzero value. Data may be passed into eval_hl via the structure userdata.

void expo_information(void **data, struct expo_inform_type* inform, ipc_ *status)

Provides output information

Parameters:

data	holds private internal data
inform	is a struct containing output information (see expo_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 expo_terminate(
    void **data,
    struct expo_control_type* control,
    struct expo_inform_type* inform
)

Deallocate all internal private storage

Parameters:

data	holds private internal data
control	is a struct containing control information (see expo_control_type)
inform	is a struct containing output information (see expo_inform_type)