GALAHAD BSC package#

purpose#

The bsc package takes given matrices $A$ and (diagonal) $D$, and builds the Schur complement $S = A D A^T$ in sparse co-ordinate (and optionally sparse column) format(s). Full advantage is taken of any zero coefficients in the matrix $A$.

Currently only the options and inform dictionaries are exposed; these are provided and used by other GALAHAD packages with Python interfaces. Please contact us if you would like full functionality!

See Section 4 of $GALAHAD/doc/bsc.pdf for a brief description of the method employed and other details.

introduction to function calls#

To solve a given problem, functions from the bsc package must be called in the following order:

bsc_initialize - provide default control parameters and set up initial data structures
bsc_read_specfile (optional) - override control values by reading replacement values from a file
bsc_import - set up matrix data structures for $A$.
bsc_reset_control (optional) - possibly change control parameters if a sequence of problems are being solved
bsc_form - form the Schur complement $S$
bsc_information (optional) - recover information about the process
bsc_terminate - deallocate data structures

See the examples section for illustrations of use.

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

callable functions#

    function bsc_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 bsc_control_type)

status

is a scalar variable of type Int32 that gives the exit status from the package. Possible values are (currently):

0
The initialization was successful.

    function bsc_information(data, inform, status)

Provides output information

Parameters:

data

holds private internal data

inform

is a structure containing output information (see bsc_inform_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 bsc_terminate(data, control, inform)

Deallocate all internal private storage

Parameters:

data	holds private internal data
control	is a structure containing control information (see bsc_control_type)
inform	is a structure containing output information (see bsc_inform_type)

available structures#

bsc_control_type structure#

    struct bsc_control_type
      f_indexing::Bool
      error::Int32
      out::Int32
      print_level::Int32
      max_col::Int32
      new_a::Int32
      extra_space_s::Int32
      s_also_by_column::Bool
      space_critical::Bool
      deallocate_error_fatal::Bool
      prefix::NTuple{31,Cchar}

detailed documentation#

control derived type as a Julia structure

components#

Bool f_indexing

use C or Fortran sparse matrix indexing

Int32 error

error and warning diagnostics occur on stream error

Int32 out

general output occurs on stream out

Int32 print_level

the level of output required is specified by print_level

Int32 max_col

maximum permitted number of nonzeros in a column of $A$; -ve means unlimit

Int32 new_a

how much has $A$ changed since it was last accessed:

0 = not changed,
1 = values changed,
2 = structure changed
3 = structure changed but values not required

Int32 extra_space_s

how much extra space is to be allocated in $S$ above that needed to hold the Schur complement

Bool s_also_by_column

should s.ptr also be set to indicate the first entry in each column of $S$

Bool space_critical

if .space_critical true, every effort will be made to use as little space as possible. This may result in longer computation time

Bool deallocate_error_fatal

if .deallocate_error_fatal is true, any array/pointer deallocation error will terminate execution. Otherwise, computation will continue

NTuple{31,Cchar} prefix

all output lines will be prefixed by .prefix(2:LEN(TRIM(.prefix))-1) where .prefix contains the required string enclosed in quotes, e.g. “string” or ‘string’

bsc_inform_type structure#

    struct bsc_inform_type{T}
      status::Int32
      alloc_status::Int32
      bad_alloc::NTuple{81,Cchar}
      max_col_a::Int32
      exceeds_max_col::Int32
      time::T
      clock_time::T

detailed documentation#

inform derived type as a Julia structure

components#

Int32 status

the return status from the package. Possible values are:

0

The call was succcesful
-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 restrictions n > 0 or m > 0 or requirement that a type contains its relevant string ‘dense’, ‘coordinate’ or ‘sparse_by_rows’ has been violated.

Int32 alloc_status

the status of the last attempted allocation/deallocation

NTuple{81,Cchar} bad_alloc

the name of the array for which an allocation/deallocation error occurred.

Int32 max_col_a

the maximum number of entries in a column of $A$

Int32 exceeds_max_col

the number of columns of $A$ that have more than control.max_col entries

T time

the total CPU time spent in the package

T clock_time

the total clock time spent in the package

Index