GALAHAD gls package#

purpose#

The gls package solves sparse unsymmetric systems of linear equations using a variant of Gaussian elimination. Given a sparse symmetric matrix $A = \{ a_{ij} \}_{m \times n}$, and an $n$-vector $b$, this function solves the system $A x = b$. If instead $b$ is an $m$-vector, the function may solve instead $A^T x = b$. gls is based upon a modern fortran interface to the HSL Archive fortran 77 package MA28, which itself relies on MA33. To obtain HSL Archive packages, see

http://hsl.rl.ac.uk/archive/ .

Currently only the options and info dictionaries are exposed; these are provided and used by other GALAHAD packages with Python interfaces. Extended functionality is available with the uls function.

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

callable functions#

overview of functions provided#

// typedefs

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

// structs

struct gls_ainfo;
struct gls_control;
struct gls_finfo;
struct gls_sinfo;

// global functions

void gls_initialize(void **data, struct gls_control* control);
void gls_read_specfile(struct gls_control* control, const char specfile[]);
void gls_import(struct gls_control* control, void **data, ipc_ *status);
void gls_reset_control(struct gls_control* control, void **data, ipc_ *status);

void gls_information(
    void **data,
    struct gls_ainfo* ainfo,
    struct gls_finfo* finfo,
    struct gls_sinfo* sinfo,
    ipc_ *status
);

void gls_finalize(void **data, struct gls_control* control, ipc_ *status);

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 gls_initialize(void **data, struct gls_control* control)

Set default control values and initialize private data

Parameters:

data	holds private internal data
control	is a struct containing control information (see gls_control)

void gls_read_specfile(struct gls_control* 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/gls/GLS.template. See also Table 2.1 in the Fortran documentation provided in $GALAHAD/doc/gls.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 gls_control)
specfile	is a character string containing the name of the specification file

void gls_import(struct gls_control* control, void **data, ipc_ *status)

Import problem data into internal storage prior to solution.

Parameters:

control

is a struct whose members provide control paramters for the remaining prcedures (see gls_control)

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 restriction n > 0 or requirement that type contains its relevant string ‘dense’, ‘coordinate’, ‘sparse_by_rows’, ‘diagonal’ or ‘absent’ has been violated.

void gls_reset_control(struct gls_control* 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 gls_control)

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

void gls_information(
    void **data,
    struct gls_ainfo* ainfo,
    struct gls_finfo* finfo,
    struct gls_sinfo* sinfo,
    ipc_ *status
)

Provides output information

Parameters:

data	holds private internal data
ainfo	is a struct containing analysis output information (see gls_ainfo)
finfo	is a struct containing factorization output information (see gls_finfo)
sinfo	is a struct containing solver output information (see gls_sinfo)
status	is a scalar variable of type ipc_, that gives the exit status from the package. Possible values are (currently): The values were recorded successfully

void gls_finalize(void **data, struct gls_control* control, ipc_ *status)

Deallocate all internal private storage

Parameters:

data

holds private internal data

control

is a struct containing control information (see gls_control)

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

available structures#

struct gls_control#

#include <galahad_gls.h>

struct gls_control {
    // fields

    bool f_indexing;
    ipc_ lp;
    ipc_ wp;
    ipc_ mp;
    ipc_ ldiag;
    ipc_ btf;
    ipc_ maxit;
    ipc_ factor_blocking;
    ipc_ solve_blas;
    ipc_ la;
    ipc_ la_int;
    ipc_ maxla;
    ipc_ pivoting;
    ipc_ fill_in;
    rpc_ multiplier;
    rpc_ reduce;
    rpc_ u;
    rpc_ switch_full;
    rpc_ drop;
    rpc_ tolerance;
    rpc_ cgce;
    bool diagonal_pivoting;
    bool struct_abort;
};

detailed documentation#

control derived type as a C struct

components#

bool f_indexing

use C or Fortran sparse matrix indexing

ipc_ lp

Unit for error messages.

ipc_ wp

Unit for warning messages.

ipc_ mp

Unit for monitor output.

ipc_ ldiag

Controls level of diagnostic output.

ipc_ btf

Minimum block size for block-triangular form (BTF). Set to $n$ to avoid.

ipc_ maxit

Maximum number of iterations.

ipc_ factor_blocking

Level 3 blocking in factorize.

ipc_ solve_blas

Switch for using Level 1 or 2 BLAS in solve.

ipc_ la

Initial size for real array for the factors.

ipc_ la_int

Initial size for integer array for the factors.

ipc_ maxla

Maximum size for real array for the factors.

ipc_ pivoting

Controls pivoting: Number of columns searched. Zero for Markowitz.

ipc_ fill_in

Initially fill_in * ne space allocated for factors.

rpc_ multiplier

Factor by which arrays sizes are to be increased if they are too small.

rpc_ reduce

if previously allocated internal workspace arrays are greater than reduce times the currently required sizes, they are reset to current requirment

rpc_ u

Pivot threshold.

rpc_ switch_full

Density for switch to full code.

rpc_ drop

Drop tolerance.

rpc_ tolerance

anything < this is considered zero

rpc_ cgce

Ratio for required reduction using IR.

bool diagonal_pivoting

Set to 0 for diagonal pivoting.

bool struct_abort

Control to abort if structurally singular.

gls_ainfo structure#

#include <galahad_gls.h>

struct gls_ainfo {
    // fields

    ipc_ flag;
    ipc_ more;
    ipc_ len_analyse;
    ipc_ len_factorize;
    ipc_ ncmpa;
    ipc_ rank;
    ipc_ drop;
    ipc_ struc_rank;
    ipc_ oor;
    ipc_ dup;
    ipc_ stat;
    ipc_ lblock;
    ipc_ sblock;
    ipc_ tblock;
    rpc_ ops;
};

detailed documentation#

ainfo derived type as a C struct

components#

ipc_ flag

Flags success or failure case.

ipc_ more

More information on failure.

ipc_ len_analyse

Size for analysis.

ipc_ len_factorize

Size for factorize.

ipc_ ncmpa

Number of compresses.

ipc_ rank

Estimated rank.

ipc_ drop

Number of entries dropped.

ipc_ struc_rank

Structural rank of matrix.

ipc_ oor

Number of indices out-of-range.

ipc_ dup

Number of duplicates.

ipc_ stat

STAT value after allocate failure.

ipc_ lblock

Size largest non-triangular block.

ipc_ sblock

Sum of orders of non-triangular blocks.

ipc_ tblock

Total entries in all non-tringular blocks.

rpc_ ops

Number of operations in elimination.

gls_finfo structure#

#include <galahad_gls.h>

struct gls_finfo {
    // fields

    ipc_ flag;
    ipc_ more;
    ipc_ size_factor;
    ipc_ len_factorize;
    ipc_ drop;
    ipc_ rank;
    ipc_ stat;
    rpc_ ops;
};

detailed documentation#

finfo derived type as a C struct

components#

ipc_ flag

Flags success or failure case.

ipc_ more

More information on failure.

ipc_ size_factor

Number of words to hold factors.

ipc_ len_factorize

Size for subsequent factorization.

ipc_ drop

Number of entries dropped.

ipc_ rank

Estimated rank.

ipc_ stat

Status value after allocate failure.

rpc_ ops

Number of operations in elimination.

gls_sinfo structure#

#include <galahad_gls.h>

struct gls_sinfo {
    // fields

    ipc_ flag;
    ipc_ more;
    ipc_ stat;
};

detailed documentation#

sinfo derived type as a C struct

components#

ipc_ flag

Flags success or failure case.

ipc_ more

More information on failure.

ipc_ stat

Status value after allocate failure.

Index