BSC

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.

functions

bsc.initialize()

Set default option values and initialize private data.

Returns:

optionsdict

dictionary containing default control options:

errorint

error and warning diagnostics occur on stream error.

outint

general output occurs on stream out.

print_levelint

the level of output required is specified by print_level.

max_colint

maximum permitted number of nonzeros in a column of \f\(A\f\); -ve means unlimit.

new_aint

how much has \(A\) changed since it was last accessed:

• 0

  unchanged.

• 1

  values changed.

• 2

  structure changed.

• 3

  structure changed but values not required.

extra_space_sint

how much extra space is to be allocated in \(S\) above that needed to hold the Schur complement.

s_also_by_columnbool

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

space_criticalbool

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

deallocate_error_fatalbool

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

prefixstr

all output lines will be prefixed by the string contained in quotes within prefix, e.g. ‘word’ (note the qutoes) will result in the prefix word.

[optional] bsc.information()

Provide optional output information.

Returns:

informdict

dictionary containing output information:

statusint

the return status. Possible values are:

• 0

  The call was successful.

• -1

  An allocation error occurred. A message indicating the offending array is written on unit options[‘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 options[‘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 m > 0 or requirement that type contains its relevant string ‘dense’, ‘coordinate’ or ‘sparse_by_rows’ has been violated.

alloc_statusint

the status of the last attempted allocation/deallocation.

bad_allocstr

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

max_col_aint

the maximum number of entries in a column of \(A\).

exceeds_max_colint

the number of columns of \(A\) that have more than control.max_col entries.

timefloat

the total CPU time spent in the package.

clock_timefloat

the total clock time spent in the package.

bsc.finalize()

Deallocate all internal private storage.