GALAHAD SILS package#

purpose#

The sils package solves sparse symmetric systems of linear equations using a multifrontal variant of Gaussian elimination. Given a sparse symmetric matrix \(A = \{ a_{ij} \}_{n \times n}\), and an \(n\)-vector \(b\), this function solves the system \(A x = b\). The matrix \(A\) need not be definite. sils is based upon a modern fortran interface to the HSL Archive fortran 77 package MA27. To obtain HSL Archive packages, see

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 sls function.

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

callable functions#

overview of functions provided#

// namespaces

namespace conf;

// typedefs

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

// structs

struct sils_ainfo_type;
struct sils_control_type;
struct sils_finfo_type;
struct sils_sinfo_type;

// global functions

void sils_initialize(
    void **data,
    struct sils_control_type* control,
    ipc_ *status
);

void sils_read_specfile(
    struct sils_control_type* control,
    const char specfile[]
);

void sils_import(struct sils_control_type* control, void **data, ipc_ *status);

void sils_reset_control(
    struct sils_control_type* control,
    void **data,
    ipc_ *status
);

void sils_information(
    void **data,
    struct sils_ainfo_type* ainfo,
    struct sils_finfo_type* finfo,
    struct sils_sinfo_type* sinfo,
    ipc_ *status
);

void sils_finalize(void **data, struct sils_control_type* 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 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 sils_initialize below will instead be

void sils_initialize_s_64(void **data, struct sils_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 is provided for the package expo, and the obvious modifications apply equally here.

function calls#

void sils_initialize(
    void **data,
    struct sils_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 sils_control_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 sils_read_specfile(
    struct sils_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/sils/SILS.template. See also Table 2.1 in the Fortran documentation provided in $GALAHAD/doc/sils.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 sils_control_type)

specfile

is a character string containing the name of the specification file

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

 
void sils_reset_control(
    struct sils_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 sils_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

 
void sils_information(
    void **data,
    struct sils_ainfo_type* ainfo,
    struct sils_finfo_type* finfo,
    struct sils_sinfo_type* sinfo,
    ipc_ *status
)

Provides output information

Parameters:

data

holds private internal data

ainfo

is a struct containing output information (see sils_ainfo_type)

finfo

is a struct containing output information (see sils_finfo_type)

sinfo

is a struct containing output information (see sils_sinfo_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 sils_finalize(void **data, struct sils_control_type* control, ipc_ *status)

Deallocate all internal private storage

Parameters:

data

holds private internal data

control

is a struct containing control information (see sils_control_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

  • \(\neq\) 0. The Fortran STAT value of an allocate or deallocate statement that has failed.

available structures#

sils_control_type structure#

#include <galahad_sils.h>

struct sils_control_type {
    // fields

    bool f_indexing;
    ipc_ ICNTL[30];
    ipc_ lp;
    ipc_ wp;
    ipc_ mp;
    ipc_ sp;
    ipc_ ldiag;
    ipc_ la;
    ipc_ liw;
    ipc_ maxla;
    ipc_ maxliw;
    ipc_ pivoting;
    ipc_ nemin;
    ipc_ factorblocking;
    ipc_ solveblocking;
    ipc_ thresh;
    ipc_ ordering;
    ipc_ scaling;
    rpc_ CNTL[5];
    rpc_ multiplier;
    rpc_ reduce;
    rpc_ u;
    rpc_ static_tolerance;
    rpc_ static_level;
    rpc_ tolerance;
    rpc_ convergence;
};

detailed documentation#

control derived type as a C struct

components#

bool f_indexing

use C or Fortran sparse matrix indexing

ipc_ ICNTL[30]

MA27 internal integer controls.

ipc_ lp

Unit for error messages.

ipc_ wp

Unit for warning messages.

ipc_ mp

Unit for monitor output.

ipc_ sp

Unit for statistical output.

ipc_ ldiag

Controls level of diagnostic output.

ipc_ la

Initial size for real array for the factors. If less than nrlnec, default size used.

ipc_ liw

Initial size for integer array for the factors. If less than nirnec, default size used.

ipc_ maxla

Max. size for real array for the factors.

ipc_ maxliw

Max. size for integer array for the factors.

ipc_ pivoting

Controls pivoting. Possible values are:

  • 1 Numerical pivoting will be performed.

  • 2 No pivoting will be performed and an error exit will occur immediately a pivot sign change is detected.

  • 3 No pivoting will be performed and an error exit will occur if a zero pivot is detected.

  • 4 No pivoting is performed but pivots are changed to all be positive.

ipc_ nemin

Minimum number of eliminations in a step (unused)

ipc_ factorblocking

Level 3 blocking in factorize (unused)

ipc_ solveblocking

Level 2 and 3 blocking in solve.

ipc_ thresh

Controls threshold for detecting full rows in analyse, registered as percentage of N, 100 Only fully dense rows detected (default)

ipc_ ordering

Controls ordering: Possible values are:

  • 0 AMD using HSL’s MC47

  • 1 User defined

  • 2 AMD using HSL’s MC50

  • 3 Min deg as in HSL’s MA57

  • 4 Metis_nodend ordering

  • 5 Ordering chosen depending on matrix characteristics. At the moment choices are HSL’s MC50 or Metis_nodend

  • >5 Presently equivalent to 5 but may chnage

ipc_ scaling

Controls scaling: Possible values are:

  • 0 No scaling

  • >0 Scaling using HSL’s MC64 but may change for > 1

rpc_ CNTL[5]

MA27 internal real controls.

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_ static_tolerance

used for setting static pivot level

rpc_ static_level

used for switch to static

rpc_ tolerance

Anything less than this is considered zero.

rpc_ convergence

used to monitor convergence in iterative refinement

sils_ainfo_type structure#

#include <galahad_sils.h>

struct sils_ainfo_type {
    // fields

    ipc_ flag;
    ipc_ more;
    ipc_ nsteps;
    ipc_ nrltot;
    ipc_ nirtot;
    ipc_ nrlnec;
    ipc_ nirnec;
    ipc_ nrladu;
    ipc_ niradu;
    ipc_ ncmpa;
    ipc_ oor;
    ipc_ dup;
    ipc_ maxfrt;
    ipc_ stat;
    ipc_ faulty;
    rpc_ opsa;
    rpc_ opse;
};

detailed documentation#

ainfo derived type as a C struct

components#

ipc_ flag

Flags success or failure case.

ipc_ more

More information on failure.

ipc_ nsteps

Number of elimination steps.

ipc_ nrltot

Size for a without compression.

ipc_ nirtot

Size for iw without compression.

ipc_ nrlnec

Size for a with compression.

ipc_ nirnec

Size for iw with compression.

ipc_ nrladu

Number of reals to hold factors.

ipc_ niradu

Number of integers to hold factors.

ipc_ ncmpa

Number of compresses.

ipc_ oor

Number of indices out-of-range.

ipc_ dup

Number of duplicates.

ipc_ maxfrt

Forecast maximum front size.

ipc_ stat

STAT value after allocate failure.

ipc_ faulty

legacy component, now not used

rpc_ opsa

Anticipated number of operations in assembly.

rpc_ opse

Anticipated number of operations in elimination.

sils_finfo_type structure#

#include <galahad_sils.h>

struct sils_finfo_type {
    // fields

    ipc_ flag;
    ipc_ more;
    ipc_ maxfrt;
    ipc_ nebdu;
    ipc_ nrlbdu;
    ipc_ nirbdu;
    ipc_ nrltot;
    ipc_ nirtot;
    ipc_ nrlnec;
    ipc_ nirnec;
    ipc_ ncmpbr;
    ipc_ ncmpbi;
    ipc_ ntwo;
    ipc_ neig;
    ipc_ delay;
    ipc_ signc;
    ipc_ nstatic;
    ipc_ modstep;
    ipc_ rank;
    ipc_ stat;
    ipc_ faulty;
    ipc_ step;
    rpc_ opsa;
    rpc_ opse;
    rpc_ opsb;
    rpc_ maxchange;
    rpc_ smin;
    rpc_ smax;
};

detailed documentation#

finfo derived type as a C struct

components#

ipc_ flag

Flags success or failure case.

ipc_ more

More information on failure.

ipc_ maxfrt

Largest front size.

ipc_ nebdu

Number of entries in factors.

ipc_ nrlbdu

Number of reals that hold factors.

ipc_ nirbdu

Number of integers that hold factors.

ipc_ nrltot

Size for a without compression.

ipc_ nirtot

Size for iw without compression.

ipc_ nrlnec

Size for a with compression.

ipc_ nirnec

Size for iw with compression.

ipc_ ncmpbr

Number of compresses of real data.

ipc_ ncmpbi

Number of compresses of integer data.

ipc_ ntwo

Number of 2x2 pivots.

ipc_ neig

Number of negative eigenvalues.

ipc_ delay

Number of delayed pivots (total)

ipc_ signc

Number of pivot sign changes when control.pivoting=3.

ipc_ nstatic

Number of static pivots chosen.

ipc_ modstep

First pivot modification when control.pivoting=4.

ipc_ rank

Rank of original factorization.

ipc_ stat

STAT value after allocate failure.

ipc_ faulty

legacy component, now not used

ipc_ step

legacy component, now not used

rpc_ opsa

operations in assembly#

rpc_ opse

number of operations in elimination

rpc_ opsb

Additional number of operations for BLAS.

rpc_ maxchange

Largest control.pivoting=4 modification.

rpc_ smin

Minimum scaling factor.

rpc_ smax

Maximum scaling factor.

sils_sinfo_type structure#

#include <galahad_sils.h>

struct sils_sinfo_type {
    // fields

    ipc_ flag;
    ipc_ stat;
    rpc_ cond;
    rpc_ cond2;
    rpc_ berr;
    rpc_ berr2;
    rpc_ error;
};

detailed documentation#

sinfo derived type as a C struct

components#

ipc_ flag

Flags success or failure case.

ipc_ stat

STAT value after allocate failure.

rpc_ cond

Condition number of matrix (category 1 eqs)

rpc_ cond2

Condition number of matrix (category 2 eqs)

rpc_ berr

Backward error for the system (category 1 eqs)

rpc_ berr2

Backward error for the system (category 2 eqs)

rpc_ error

Estimate of forward error.

Index