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.

parametric real type T and integer type INT

Below, the symbol T refers to a parametric real type that may be Float32 (single precision), Float64 (double precision) or, if supported, Float128 (quadruple precision). The symbol INT refers to a parametric integer type that may be Int32 (32-bit integer) or Int64 (64-bit integer).

callable functions

    function gls_initialize(T, INT, data, control)

Set default control values and initialize private data

Parameters:

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

    function gls_read_specfile(T, INT, control, 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 structure containing control information (see gls_control)
specfile	is a one-dimensional array of type Vararg{Cchar} that must give the name of the specification file

    function gls_import(T, INT, control, data, status)

Import problem data into internal storage prior to solution.

Parameters:

control	is a structure whose members provide control parameters for the remaining procedures (see gls_control)
data	holds private internal data
status	is a scalar variable of type INT 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.

    function gls_reset_control(T, INT, control, data, status)

Reset control parameters after import if required.

Parameters:

control	is a structure whose members provide control parameters for the remaining procedures (see gls_control)
data	holds private internal data
status	is a scalar variable of type INT 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

    function gls_information(T, INT, data, ainfo, finfo, sinfo, status)

Provides output information

Parameters:

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

    function gls_finalize(T, INT, data, control, status)

Deallocate all internal private storage

Parameters:

data	holds private internal data
control	is a structure containing control information (see gls_control)
status	is a scalar variable of type INT that gives the exit status from the package. Possible values are (currently): 0 The values were recorded successfully

available structures

struct gls_control

    struct gls_control_type{T,INT}
      f_indexing::Bool
      lp::INT
      wp::INT
      mp::INT
      ldiag::INT
      btf::INT
      maxit::INT
      factor_blocking::INT
      solve_blas::INT
      la::INT
      la_int::INT
      maxla::INT
      pivoting::INT
      fill_in::INT
      multiplier::T
      reduce::T
      u::T
      switch_full::T
      drop::T
      tolerance::T
      cgce::T
      diagonal_pivoting::Bool
      struct_abort::Bool

detailed documentation

control derived type as a Julia structure

components

Bool f_indexing

use C or Fortran sparse matrix indexing

INT lp

Unit for error messages.

INT wp

Unit for warning messages.

INT mp

Unit for monitor output.

INT ldiag

Controls level of diagnostic output.

INT btf

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

INT maxit

Maximum number of iterations.

INT factor_blocking

Level 3 blocking in factorize.

INT solve_blas

Switch for using Level 1 or 2 BLAS in solve.

INT la

Initial size for real array for the factors.

INT la_int

Initial size for integer array for the factors.

INT maxla

Maximum size for real array for the factors.

INT pivoting

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

INT fill_in

Initially fill_in * ne space allocated for factors.

T multiplier

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

T reduce

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

T u

Pivot threshold.

T switch_full

Density for switch to full code.

T drop

Drop tolerance.

T tolerance

anything < this is considered zero

T 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

    struct gls_ainfo_type{T,INT}
      flag::INT
      more::INT
      len_analyse::INT
      len_factorize::INT
      ncmpa::INT
      rank::INT
      drop::INT
      struc_rank::INT
      oor::INT
      dup::INT
      stat::INT
      lblock::INT
      sblock::INT
      tblock::INT
      ops::T

detailed documentation

ainfo derived type as a Julia structure

components

INT flag

Flags success or failure case.

INT more

More information on failure.

INT len_analyse

Size for analysis.

INT len_factorize

Size for factorize.

INT ncmpa

Number of compresses.

INT rank

Estimated rank.

INT drop

Number of entries dropped.

INT struc_rank

Structural rank of matrix.

INT oor

Number of indices out-of-range.

INT dup

Number of duplicates.

INT stat

STAT value after allocate failure.

INT lblock

Size largest non-triangular block.

INT sblock

Sum of orders of non-triangular blocks.

INT tblock

Total entries in all non-tringular blocks.

T ops

Number of operations in elimination.

gls_finfo structure

    struct gls_finfo_type{T,INT}
      flag::INT
      more::INT
      size_factor::INT
      len_factorize::INT
      drop::INT
      rank::INT
      stat::INT
      ops::T

detailed documentation

finfo derived type as a Julia structure

components

INT flag

Flags success or failure case.

INT more

More information on failure.

INT size_factor

Number of words to hold factors.

INT len_factorize

Size for subsequent factorization.

INT drop

Number of entries dropped.

INT rank

Estimated rank.

INT stat

Status value after allocate failure.

T ops

Number of operations in elimination.

gls_sinfo structure

    struct gls_sinfo_type{INT}
      flag::INT
      more::INT
      stat::INT

detailed documentation

sinfo derived type as a Julia structure

components

INT flag

Flags success or failure case.

INT more

More information on failure.

INT stat

Status value after allocate failure.

Index