# Module Dls.BandMatrix

module BandMatrix: sig .. end
Band matrices as passed to callback functions.
See sundials: The BAND Module

type t = Dls_impl.BandTypes.t
An abstract band matrix. Values of this type are typically passed to linear solver callback functions (like Cvode.Dls.band_jac_fn, Ida.Dls.band_jac_fn, and Kinsol.Dls.band_jac_fn), in which case their lifetimes are determined by the underlying library and they should only be used within the callback to avoid the Invalidated exception.
See sundials: Type DlsMat
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 after a call to Dls.BandMatrix.gbtrf.

#### Basic access

val make : dimensions -> float -> t
Returns a band matrix with the given Dls.BandMatrix.dimensions and all elements initialized to the given value.
See sundials: NewBandMat
val create : dimensions -> t
Returns an uninitialized band matrix with the given Dls.BandMatrix.dimensions.
See sundials: NewBandMat
val size : t -> dimensions
Returns the dimensions of a band matrix.
val print : t -> unit
Prints a band matrix to stdout.
See sundials: PrintMat
val pp : Format.formatter -> t -> unit
Pretty-print a band matrix using the Format module.
val ppi : ?start:string ->
?stop:string ->
?rowsep:string ->
?indent:int ->
?sep:string ->
?empty:string ->
?item:(Format.formatter -> int -> int -> float -> unit) ->
Format.formatter -> t -> unit
Pretty-print a band matrix using the Format module. The defaults are: start="[", stop="]", rowsep=";", indent=4, sep=" ", 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.
See sundials: BAND_ELEM
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.
See sundials: BAND_ELEM
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.
See sundials: DENSE_ELEM

#### Calculations

val set_to_zero : t -> unit
Fills a matrix with zeros.
See sundials: SetToZero
val add_identity : t -> unit
Increment a square matrix by the identity matrix.
val matvec : t -> x:Sundials.RealArray.t -> y:Sundials.RealArray.t -> unit
Compute the matrix-vector product $y = Ax$.
Since 2.6.0
See sundials: BandMatvec
val blit : t -> t -> int -> int -> unit
blit src dst copymu copyml copies the contents of src into dst. The bandwidth to copy is given by copy_mu and copy_ml. Both matrices must have the same size.
See sundials: BandCopy
val scale : float -> t -> unit
Multiplies each element by a constant.
See sundials: BandScale
val gbtrf : t -> Sundials.LintArray.t -> unit
gbtrf a p performs the LU factorization of a with partial pivoting according to p. The values in a are overwritten with those of the calculated L and U matrices. The diagonal belongs to U. The diagonal of L is all 1s. U may occupy elements up to bandwidth smu (rather than to mu).
See sundials: BandGBTRF
val gbtrs : t -> Sundials.LintArray.t -> Sundials.RealArray.t -> unit
gbtrs a p b finds the solution of ax = b using an LU factorization found by Dls.BandMatrix.gbtrf. Both p and b must have the same number of rows as a.
See sundials: BandGBTRS

#### Low-level details

exception Invalidated
Raised on an attempt to access a value that has become invalid. Such values refer to matrices that no longer exist in the underlying library.
val invalidate : t -> unit
Called internally when the corresponding value in the underlying library ceases to exist.
val unsafe_unwrap : t ->
(float, Bigarray.float64_elt, Bigarray.c_layout) Bigarray.Array2.t
Potentially unsafe access to the underlying storage. This array must only be used when the underlying storage is valid, which will be the case in callbacks. The array is accessed column first (unlike in Dls.BandMatrix.get).