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 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 sils_initialize(T, INT, 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 INT that gives the exit status from the package. Possible values are (currently):

  • 0

    The values were recorded successfully

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

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

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 sils_information(T, INT, 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 INT that gives the exit status from the package. Possible values are (currently):

  • 0

    The values were recorded successfully

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

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

  • \(\neq\) 0

    The Fortran STAT value of a deallocate statement that has failed

available structures#

sils_control_type structure#

    struct sils_control_type{T,INT}
      f_indexing::Bool
      ICNTL::NTuple{30,INT}
      lp::INT
      wp::INT
      mp::INT
      sp::INT
      ldiag::INT
      la::INT
      liw::INT
      maxla::INT
      maxliw::INT
      pivoting::INT
      nemin::INT
      factorblocking::INT
      solveblocking::INT
      thresh::INT
      ordering::INT
      scaling::INT
      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

INT ICNTL[30]

MA27 internal integer controls.

INT lp

Unit for error messages.

INT wp

Unit for warning messages.

INT mp

Unit for monitor output.

INT sp

Unit for statistical output.

INT ldiag

Controls level of diagnostic output.

INT la

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

INT liw

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

INT maxla

Max. size for real array for the factors.

INT maxliw

Max. size for integer array for the factors.

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

INT nemin

Minimum number of eliminations in a step (unused)

INT factorblocking

Level 3 blocking in factorize (unused)

INT solveblocking

Level 2 and 3 blocking in solve.

INT thresh

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

INT 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

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

Number of elimination steps.

INT nrltot

Size for a without compression.

INT nirtot

Size for iw without compression.

INT nrlnec

Size for a with compression.

INT nirnec

Size for iw with compression.

INT nrladu

Number of reals to hold factors.

INT niradu

Number of integers to hold factors.

INT ncmpa

Number of compresses.

INT oor

Number of indices out-of-range.

INT dup

Number of duplicates.

INT maxfrt

Forecast maximum front size.

INT stat

STAT value after allocate failure.

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

Largest front size.

INT nebdu

Number of entries in factors.

INT nrlbdu

Number of reals that hold factors.

INT nirbdu

Number of integers that hold factors.

INT nrltot

Size for a without compression.

INT nirtot

Size for iw without compression.

INT nrlnec

Size for a with compression.

INT nirnec

Size for iw with compression.

INT ncmpbr

Number of compresses of real data.

INT ncmpbi

Number of compresses of integer data.

INT ntwo

Number of 2x2 pivots.

INT neig

Number of negative eigenvalues.

INT delay

Number of delayed pivots (total)

INT signc

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

INT nstatic

Number of static pivots chosen.

INT modstep

First pivot modification when control.pivoting=4.

INT rank

Rank of original factorization.

INT stat

STAT value after allocate failure.

INT faulty

legacy component, now not used

INT 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,INT}
      flag::INT
      stat::INT
      cond::T
      cond2::T
      berr::T
      berr2::T
      error::T

detailed documentation#

sinfo derived type as a Julia structure

components#

INT flag

Flags success or failure case.

INT 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