Previous  Up  Next

Module Sundials_Matrix.Sparse

module Sparse: sig .. end

Sparse matrices

type csc

Compressed-sparse-column format.

type csr

Compressed-sparse-row format.

type '_ sformat =
| CSC : csc sformat (*

Compressed-sparse-column format (CSC_MAT).

*)
| CSR : csr sformat (*

Compressed-sparse-row format (CSR_MAT).

*)

Matrix storage formats.

type 's t

A sparse 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).

The type argument specifies the storage format, either compressed-sparse-column format or compressed-sparse-row format.

type index_array = (Sundials.Index.t, Sundials.Index.index_elt, Stdlib.Bigarray.c_layout)
       Stdlib.Bigarray.Array1.t

Array of row or column indices

Basic access

val make : 's sformat ->
       int -> int -> int -> 's t

make fmt m n nnz returns an m by n sparse matrix in the specified format with a potential for nnz non-zero elements. All elements are initially zero.

The CSR format is only available from Sundials 2.7.0 onwards.

val from_dense : 's sformat ->
       float -> Sundials_Matrix.Dense.t -> 's t

Creates a sparse matrix in in the specified format from a dense matrix by copying all values of magnitude greater than the given tolerance.

The CSR format is only available from Sundials 2.7.0 onwards.

val from_band : 's sformat ->
       float -> Sundials_Matrix.Band.t -> 's t

Creates a sparse matrix in the specified format from a band matrix by copying all values of magnitude greater than the given tolerance.

The CSR format is only available from Sundials 2.7.0 onwards.

val sformat : 's t -> 's sformat

Return the matrix format.

val is_csc : 's t -> bool

Returns true iff the matrix format is CSC. It is essentially a version of Sundials_Matrix.Sparse.sformat with less typing complications.

val size : 's t -> int * int

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

val dims : 's t -> int * int

nnz, np = dims m returns the allocated number of nonzeros nnz and of the number np of columns (for csc) or rows (for csr) in the matrix m.

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

Pretty-print a sparse matrix using the Format module.

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

Pretty-print a sparse matrix using the Format module. The defaults are: start="[", stop="]", sep=";", indent=4, itemsep=" ", rowcol=fun f i->Format.fprintf f "%2d: " i, 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 set_col : csc t -> int -> int -> unit

set_col a j idx sets the data index of column j to idx.

val get_col : csc t -> int -> int

get_col a j returns the data index of column j.

val set_row : csr t -> int -> int -> unit

set_row a j idx sets the data index of row j to idx.

val get_row : csr t -> int -> int

get_row a j returns the data index of row j.

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

set a idx i v sets the idxth row/column to i and its value to v.

val get : 'f t -> int -> int * float

r, v = get a idx returns the row/column r and value v at the idxth position.

val unwrap : 's t ->
       index_array * index_array *
       Sundials.RealArray.t

Direct access to the underlying sparse storage arrays. In the call vals, ptrs, data = unwrap m ,

NB: The Sundials_Matrix.Sparse.scale_add, Sundials_Matrix.Sparse.scale_addi, Sundials_Matrix.Sparse.blit, and Sundials_Matrix.Sparse.resize functions, invoked either directly or from within a solver, may replace the underlying storage. In these cases, any previously 'unwrapped' arrays are 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 unless the Sundials_Matrix.Sparse.scale_add, Sundials_Matrix.Sparse.scale_addi, Sundials_Matrix.Sparse.blit, and Sundials_Matrix.Sparse.resize functions are used.

val resize : ?nnz:int -> 's t -> unit

Reallocates the underlying arrays to the given number of non-zero elements, or otherwise to the current number of non-zero elements .

NB: The Sundials_Matrix.Sparse.resize operation may replace the underlying storage of the matrix argument. In this case, any previously 'unwrapped' array is no longer associated with the matrix storage.

Operations

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

Operations on sparse matrices.

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

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

NB: The Sundials_Matrix.Sparse.scale_add operation, invoked either directly or from within a solver, may replace the underlying storage of its first matrix argument does not contain the sparsity of the second matrix argument. In this case, any previously 'unwrapped' array is no longer associated with the matrix storage.

val scale_addi : float -> 's t -> unit

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

NB: The Sundials_Matrix.Sparse.scale_add operation, invoked either directly or from within a solver, may replace the underlying storage of its matrix argument if it does not already contain a complete diagonal. In this case, any previously 'unwrapped' array is no longer associated with the matrix storage.

val matvec : 's 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 : 's t -> unit

Fills a matrix with zeros.

val blit : src:'s t -> dst:'s 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, may replace the underlying storage of its second matrix argument if it does not contain the sparsity of the first matrix argument. In this case, any previously 'unwrapped' array is no longer associated with the matrix storage.

val copy_to_csr : csc t ->
       csr t

Create a new sparse matrix in CSR format from the contents of an existing one in CSC format.

val copy_to_csc : csr t ->
       csc t

Create a new sparse matrix in CSC format from the contents of an existing one in CSR format.

val space : 's 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 set_rowval : csc t -> int -> int -> unit

set_rowval a idx i sets the idxth row to i.

val get_rowval : csc t -> int -> int

r = get_rowval a idx returns the row r at the idxth position.

val set_colval : csr t -> int -> int -> unit

set_colval a idx i sets the idxth column to i.

val get_colval : csr t -> int -> int

c = get_colval a idx returns the column c at the idxth position.

val set_data : 'f t -> int -> float -> unit

set_data a idx v sets the value of the idxth row v.

val get_data : 'f t -> int -> float

v = get_data a idx returns the value v at the idxth position.

val invalidate : 's 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.