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.

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., sils_initialize_s) are available with T as Float32.

callable functions#

    function sils_initialize(data, control, status)

Set default control values and initialize private data

Parameters:

data

holds private internal data

control

is a structure containing control information (see sils_control_type)

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 sils_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/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 structure containing control information (see sils_control_type)

specfile

is a one-dimensional array of type Vararg{Cchar} that must give the name of the specification file

 
    function sils_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 sils_control_type)

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 sils_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 sils_control_type)

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 sils_information(data, ainfo, finfo, sinfo, status)

Provides output information

Parameters:

data

holds private internal data

ainfo

is a structure containing output information (see sils_ainfo_type)

finfo

is a structure containing output information (see sils_finfo_type)

sinfo

is a structure containing output information (see sils_sinfo_type)

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 sils_finalize(data, control, status)

Deallocate all internal private storage

Parameters:

data

holds private internal data

control

is a structure containing control information (see sils_control_type)

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

  • \(\neq\) 0

    The Fortran STAT value of a deallocate statement that has failed

available structures#

sils_control_type structure#

    struct sils_control_type{T}
      f_indexing::Bool
      ICNTL::NTuple{30,Cint}
      lp::Int32
      wp::Int32
      mp::Int32
      sp::Int32
      ldiag::Int32
      la::Int32
      liw::Int32
      maxla::Int32
      maxliw::Int32
      pivoting::Int32
      nemin::Int32
      factorblocking::Int32
      solveblocking::Int32
      thresh::Int32
      ordering::Int32
      scaling::Int32
      CNTL::NTuple{5,T}
      multiplier::T
      reduce::T
      u::T
      static_tolerance::T
      static_level::T
      tolerance::T
      convergence::T

detailed documentation#

control derived type as a Julia structure

components#

Bool f_indexing

use C or Fortran sparse matrix indexing

Int32 ICNTL[30]

MA27 internal integer controls.

Int32 lp

Unit for error messages.

Int32 wp

Unit for warning messages.

Int32 mp

Unit for monitor output.

Int32 sp

Unit for statistical output.

Int32 ldiag

Controls level of diagnostic output.

Int32 la

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

Int32 liw

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

Int32 maxla

Max. size for real array for the factors.

Int32 maxliw

Max. size for integer array for the factors.

Int32 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.

Int32 nemin

Minimum number of eliminations in a step (unused)

Int32 factorblocking

Level 3 blocking in factorize (unused)

Int32 solveblocking

Level 2 and 3 blocking in solve.

Int32 thresh

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

Int32 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

Int32 scaling

Controls scaling: Possible values are:

  • 0 No scaling

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

T CNTL[5]

MA27 internal real controls.

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 static_tolerance

used for setting static pivot level

T static_level

used for switch to static

T tolerance

Anything less than this is considered zero.

T convergence

used to monitor convergence in iterative refinement

sils_ainfo_type structure#

    struct sils_ainfo_type{T}
      flag::Int32
      more::Int32
      nsteps::Int32
      nrltot::Int32
      nirtot::Int32
      nrlnec::Int32
      nirnec::Int32
      nrladu::Int32
      niradu::Int32
      ncmpa::Int32
      oor::Int32
      dup::Int32
      maxfrt::Int32
      stat::Int32
      faulty::Int32
      opsa::T
      opse::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 nsteps

Number of elimination steps.

Int32 nrltot

Size for a without compression.

Int32 nirtot

Size for iw without compression.

Int32 nrlnec

Size for a with compression.

Int32 nirnec

Size for iw with compression.

Int32 nrladu

Number of reals to hold factors.

Int32 niradu

Number of integers to hold factors.

Int32 ncmpa

Number of compresses.

Int32 oor

Number of indices out-of-range.

Int32 dup

Number of duplicates.

Int32 maxfrt

Forecast maximum front size.

Int32 stat

STAT value after allocate failure.

Int32 faulty

legacy component, now not used

T opsa

Anticipated number of operations in assembly.

T opse

Anticipated number of operations in elimination.

sils_finfo_type structure#

    struct sils_finfo_type{T}
      flag::Int32
      more::Int32
      maxfrt::Int32
      nebdu::Int32
      nrlbdu::Int32
      nirbdu::Int32
      nrltot::Int32
      nirtot::Int32
      nrlnec::Int32
      nirnec::Int32
      ncmpbr::Int32
      ncmpbi::Int32
      ntwo::Int32
      neig::Int32
      delay::Int32
      signc::Int32
      nstatic::Int32
      modstep::Int32
      rank::Int32
      stat::Int32
      faulty::Int32
      step::Int32
      opsa::T
      opse::T
      opsb::T
      maxchange::T
      smin::T
      smax::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 maxfrt

Largest front size.

Int32 nebdu

Number of entries in factors.

Int32 nrlbdu

Number of reals that hold factors.

Int32 nirbdu

Number of integers that hold factors.

Int32 nrltot

Size for a without compression.

Int32 nirtot

Size for iw without compression.

Int32 nrlnec

Size for a with compression.

Int32 nirnec

Size for iw with compression.

Int32 ncmpbr

Number of compresses of real data.

Int32 ncmpbi

Number of compresses of integer data.

Int32 ntwo

Number of 2x2 pivots.

Int32 neig

Number of negative eigenvalues.

Int32 delay

Number of delayed pivots (total)

Int32 signc

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

Int32 nstatic

Number of static pivots chosen.

Int32 modstep

First pivot modification when control.pivoting=4.

Int32 rank

Rank of original factorization.

Int32 stat

STAT value after allocate failure.

Int32 faulty

legacy component, now not used

Int32 step

legacy component, now not used

T opsa

operations in assembly#

T opse

number of operations in elimination

T opsb

Additional number of operations for BLAS.

T maxchange

Largest control.pivoting=4 modification.

T smin

Minimum scaling factor.

T smax

Maximum scaling factor.

sils_sinfo_type structure#

    struct sils_sinfo_type{T}
      flag::Int32
      stat::Int32
      cond::T
      cond2::T
      berr::T
      berr2::T
      error::T

detailed documentation#

sinfo derived type as a Julia structure

components#

Int32 flag

Flags success or failure case.

Int32 stat

STAT value after allocate failure.

T cond

Condition number of matrix (category 1 eqs)

T cond2

Condition number of matrix (category 2 eqs)

T berr

Backward error for the system (category 1 eqs)

T berr2

Backward error for the system (category 2 eqs)

T error

Estimate of forward error.

Index