Previous  Up  Next

Module Sundials_Matrix.Band

module Band: sig .. end

Banded matrices

type t

A band matrix. Values of this type are typically passed to linear solver callback functions (like Cvode.Dls.jac_fn, Ida.Dls.jac_fn, and Kinsol.Dls.jac_fn).

type dimensions = {
   n : int; (*

Matrix size: n by n.

*)
   mu : int; (*

Upper bandwidth.

*)
   smu : int; (*

Storage upper bandwidth.

*)
   ml : int; (*

Lower bandwidth.

*)
}

Band matrix dimensions. If the result will not be LU factored then $\mathtt{smu} = \mathtt{mu}$ , otherwise $\mathtt{smu} = \min(\mathtt{n}-1, \mathtt{mu} + \mathtt{ml})$ . The extra space is used to store U.

Basic access

val make : dimensions -> float -> t

Returns a band matrix with the given Sundials_Matrix.Band.dimensions and all elements initialized to the given value.

val create : dimensions -> t

Returns an uninitialized band matrix with the given Sundials_Matrix.Band.dimensions.

val size : t -> int * int

m, n = size a returns the numbers of rows m and columns n of a.

NB: m and n are always equal for band matrices.

val dims : t -> dimensions

Returns the dimensions of a band matrix.

val pp : Stdlib.Format.formatter -> t -> unit

Pretty-print a band matrix using the Format module.

val ppi : ?start:string ->
       ?stop:string ->
       ?sep:string ->
       ?indent:int ->
       ?itemsep:string ->
       ?empty:string ->
       ?item:(Stdlib.Format.formatter -> int -> int -> float -> unit) ->
       unit -> Stdlib.Format.formatter -> t -> unit

Pretty-print a band matrix using the Format module. The defaults are: start="[", stop="]", sep=";", indent=4, itemsep=" ", empty="           ~           " and item=fun f r c->Format.fprintf f "(%2d,%2d)=% -15e" r c (see fprintf). The indent argument specifies the indent for wrapped rows.

val get : t -> int -> int -> float

get a i j returns the value at row i and column j of a. Only rows and columns satisfying $\mathtt{i} \leq \mathtt{j} + \mathtt{ml}$ and $\mathtt{j} \leq \mathtt{i} + \mathtt{smu}$ are valid.

val set : t -> int -> int -> float -> unit

set a i j v sets the value at row i and column j of a to v. Only rows and columns satisfying $\mathtt{i} \leq \mathtt{j} + \mathtt{ml}$ and $\mathtt{j} \leq \mathtt{i} + \mathtt{smu}$ are valid.

val update : t -> int -> int -> (float -> float) -> unit

update a i j f sets the value at row i and column j of a to f v. Only rows and columns satisfying $\mathtt{i} \leq \mathtt{j} + \mathtt{ml}$ and $\mathtt{j} \leq \mathtt{i} + \mathtt{smu}$ are valid.

val unwrap : t -> Sundials.RealArray2.data

Direct access to the underlying storage array, which is accessed column first (unlike in Sundials_Matrix.Band.get).

NB: The Sundials_Matrix.Band.scale_add operation, invoked either directly or from within a solver, will replace the underlying storage of its first matrix argument if the second matrix has a strictly larger bandwidth. Similarly, the Sundials_Matrix.Band.blit operation, invoked either directly or from within a solver, will replace the underlying storage of its second matrix argument if the first matrix has a strictly larger bandwidth. In both cases, any previously 'unwrapped' array is no longer associated with the matrix storage.

NB: For Config.sundials_version < 3.0.0, this access is potentially unsafe and must only be used when the underlying storage is valid, which will be the case in callbacks.

Operations

val ops : (t, Nvector_serial.data) Sundials_Matrix.matrix_ops

Operations on band matrices.

val scale_add : float -> t -> t -> unit

scale_add c A B calculates $A = cA + B$.

NB: This operation, invoked either directly or from within a solver, will replace the underlying storage of its first matrix argument if the second matrix has a strictly larger bandwidth.

val scale_addi : float -> t -> unit

scale_addi c A calculates $A = cA + I$.

val matvec : t ->
       Sundials.RealArray.t -> Sundials.RealArray.t -> unit

The call matvec a x y computes the matrix-vector product $y = Ax$.

val set_to_zero : t -> unit

Fills a matrix with zeros.

val blit : src:t -> dst:t -> unit

blit ~src ~dst copies the contents of src into dst. Both must have the same size.

NB: This operation, invoked either directly or from within a solver, will replace the underlying storage of its second matrix argument if the first matrix has a strictly larger bandwidth.

val space : t -> int * int

lrw, liw = space a returns the storage requirements of a as lrw realtype words and liw integer words.

Low-level details

val invalidate : t -> unit

Called internally when the corresponding value in the underlying library ceases to exist. Has no effect when Config.sundials_version >= 3.0.0.