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
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).
Calable functions as described are with T as Float64, but variants
(with the additional suffix _s, e.g., gls_initialize_s)
are available with T as Float32.
callable functions#
function gls_initialize(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(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(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:
|
function gls_reset_control(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:
|
function gls_information(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):
|
function gls_finalize(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):
|
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.