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

Below, the symbol T refers to a parametric real type that may be Float32 (single precision) or Float64 (double precision).

callable functions

    function gls_initialize(T, 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, 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, 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 Int32 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, 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 Int32 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, 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 Int32 that gives the exit status from the package. Possible values are (currently): 0 The values were recorded successfully

    function gls_finalize(T, 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 Int32 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}
      f_indexing::Bool
      lp::Int32
      wp::Int32
      mp::Int32
      ldiag::Int32
      btf::Int32
      maxit::Int32
      factor_blocking::Int32
      solve_blas::Int32
      la::Int32
      la_int::Int32
      maxla::Int32
      pivoting::Int32
      fill_in::Int32
      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

Int32 lp

Unit for error messages.

Int32 wp

Unit for warning messages.

Int32 mp

Unit for monitor output.

Int32 ldiag

Controls level of diagnostic output.

Int32 btf

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

Int32 maxit

Maximum number of iterations.

Int32 factor_blocking

Level 3 blocking in factorize.

Int32 solve_blas

Switch for using Level 1 or 2 BLAS in solve.

Int32 la

Initial size for real array for the factors.

Int32 la_int

Initial size for integer array for the factors.

Int32 maxla

Maximum size for real array for the factors.

Int32 pivoting

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

Int32 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}
      flag::Int32
      more::Int32
      len_analyse::Int32
      len_factorize::Int32
      ncmpa::Int32
      rank::Int32
      drop::Int32
      struc_rank::Int32
      oor::Int32
      dup::Int32
      stat::Int32
      lblock::Int32
      sblock::Int32
      tblock::Int32
      ops::T

detailed documentation

ainfo derived type as a Julia structure

components

Int32 flag

Flags success or failure case.

Int32 more

More information on failure.

Int32 len_analyse

Size for analysis.

Int32 len_factorize

Size for factorize.

Int32 ncmpa

Number of compresses.

Int32 rank

Estimated rank.

Int32 drop

Number of entries dropped.

Int32 struc_rank

Structural rank of matrix.

Int32 oor

Number of indices out-of-range.

Int32 dup

Number of duplicates.

Int32 stat

STAT value after allocate failure.

Int32 lblock

Size largest non-triangular block.

Int32 sblock

Sum of orders of non-triangular blocks.

Int32 tblock

Total entries in all non-tringular blocks.

T ops

Number of operations in elimination.

gls_finfo structure

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

detailed documentation

finfo derived type as a Julia structure

components

Int32 flag

Flags success or failure case.

Int32 more

More information on failure.

Int32 size_factor

Number of words to hold factors.

Int32 len_factorize

Size for subsequent factorization.

Int32 drop

Number of entries dropped.

Int32 rank

Estimated rank.

Int32 stat

Status value after allocate failure.

T ops

Number of operations in elimination.

gls_sinfo structure

    struct gls_sinfo_type
      flag::Int32
      more::Int32
      stat::Int32

detailed documentation

sinfo derived type as a Julia structure

components

Int32 flag

Flags success or failure case.

Int32 more

More information on failure.

Int32 stat

Status value after allocate failure.

Index