Previous  Up  Next

Module Sundials.Matrix

module Matrix: Sundials_Matrix

Generic matrices.

Shared definitions

type ('m, 'd) matrix_ops = {
   m_clone : 'm -> 'm; (*

Create a new, distinct matrix from an existing one without copying the contents of the original matrix.

*)
   m_zero : 'm -> unit; (*

Set all elements to zero.

*)
   m_copy : 'm -> 'm -> unit; (*

m_copy a b copies the contents of a into b.

*)
   m_scale_add : float -> 'm -> 'm -> unit; (*

m_scale_add c a b calculates $a = ca + b$.

*)
   m_scale_addi : float -> 'm -> unit; (*

m_scale_addi c a calculates $a = ca + I$.

*)
   m_matvec_setup : ('m -> unit) option; (*

Performs any setup necessary to perform a matrix-vector product.

*)
   m_matvec : 'm -> 'd -> 'd -> unit; (*

m_matvec a x y calculates $y = ax$.

*)
   m_space : 'm -> int * int; (*

lrw, liw = m_space a returns the number of realtype words lrw and integer words liw required to store the matrix a.

*)
}

Generic operations that all matrix types must implement. Failure is signalled by raising an exception.

There are two type variables:

exception Invalidated

Raised in Config.sundials_version < 3.0.0 on an attempt to access a value that has become invalid. Such values refer to matrices that no longer exist in the underlying library. Values never become invalid in Config.sundials_version >= 3.0.0.

exception IncompatibleArguments

Raised if matrix operation arguments are mutually incompatible.

exception ZeroDiagonalElement of int

Raised if a zero diagonal element is found during factorization using a low-level routine like LinearSolver.Iterative.Algorithms.qr_fact, LinearSolver.Iterative.Algorithms.qr_sol, or Sundials_Matrix.ArrayDense.getrf. The argument gives the equation number (from 1).

Matrix content

module Dense: sig .. end

Dense matrices

module Band: sig .. end

Banded matrices

module Sparse: sig .. end

Sparse matrices

Arrays as matrices

module ArrayDense: sig .. end

General purpose dense matrix operations on arrays.

module ArrayBand: sig .. end

General-purpose band matrix operations on arrays.

Generic matrices

type standard

Distinguishes a library-supplied matrix from a custom one.

type custom

Distinguishes a user-supplied matrix from a standard one.

type ('k, 'm, 'nd, 'nk) t

A generic matrix with a payload of type 'm. The 'k type argument tracks whether the matrix is Sundials_Matrix.standard or Sundials_Matrix.custom. The 'nd and 'nk type arguments track the compatiblity of the m_matvec vector parameters.

type [> Nvector_serial.kind ] dense = (standard, Dense.t, Nvector_serial.data,
        [> Nvector_serial.kind ] as 'nk)
       t

Generic matrix with Dense content.

val dense : ?context:Sundials.Context.t ->
       ?m:int -> ?i:float -> int -> [> Nvector_serial.kind ] dense

By default, dense n returns an n by n dense matrix with all elements initialized to 0.0. Optional arguments allow specifying the number of rows (m) and the initial value (i).

By default, the matrix is created using the context returned by Sundials.Context.default, but this can be overridden by passing an optional context argument.

val wrap_dense : ?context:Sundials.Context.t ->
       Dense.t -> [> Nvector_serial.kind ] dense

Creates a (dense) matrix by wrapping an existing dense matrix. The two values share the same underlying storage.

type [> Nvector_serial.kind ] band = (standard, Band.t, Nvector_serial.data,
        [> Nvector_serial.kind ] as 'nk)
       t

Generic matrix with Band content.

val band : ?context:Sundials.Context.t ->
       ?mu:int ->
       ?smu:int ->
       ?ml:int -> ?i:float -> int -> [> Nvector_serial.kind ] band

By default, band n returns an n by n band matrix with all bandwidths equal to 2 and all values initialized to 0.0. Optional arguments allow specifying the upper bandwidth mu, the lower bandwidth ml, the storage upper bandwidth smu and the initial values i. If mu is given but not ml, then ml is set to mu. If mu is given but not smu, then smu is set to mu+ml.

By default, the matrix is created using the context returned by Sundials.Context.default, but this can be overridden by passing an optional context argument.

val wrap_band : ?context:Sundials.Context.t ->
       Band.t -> [> Nvector_serial.kind ] band

Creates a (band) matrix by wrapping an existing band matrix. The two values share the same underlying storage.

By default, the matrix is created using the context returned by Sundials.Context.default, but this can be overridden by passing an optional context argument.

type ('s, [> Nvector_serial.kind ]) sparse = (standard, 's Sparse.t, Nvector_serial.data,
        [> Nvector_serial.kind ] as 'nk)
       t

Generic matrix with Sparse content.

val sparse_csc : ?context:Sundials.Context.t ->
       ?m:int ->
       ?nnz:int ->
       int ->
       (Sparse.csc, [> Nvector_serial.kind ]) sparse

By default, sparse_csc n returns an n by n sparse matrix in CSC format with the capacity for n / 10 non-zero elements and all elements initialized to 0.0. Optional arguments allow specifying the number of rows m, and the number of non-zero elements nnz.

By default, the matrix is created using the context returned by Sundials.Context.default, but this can be overridden by passing an optional context argument.

val sparse_csr : ?context:Sundials.Context.t ->
       ?m:int ->
       ?nnz:int ->
       int ->
       (Sparse.csr, [> Nvector_serial.kind ]) sparse

As for Sundials_Matrix.sparse_csc but the returned matrix is in CSR format.

The CSR format is only available from Sundials 2.7.0 onwards.

By default, the matrix is created using the context returned by Sundials.Context.default, but this can be overridden by passing an optional context argument.

val wrap_sparse : ?context:Sundials.Context.t ->
       's Sparse.t ->
       ('s, [> Nvector_serial.kind ]) sparse

Creates a (sparse) matrix by wrapping an existing sparse matrix. The two values share the same underlying storage.

By default, the matrix is created using the context returned by Sundials.Context.default, but this can be overridden by passing an optional context argument.

type 'nk arraydense = (custom, ArrayDense.t, Sundials.RealArray.t,
        'nk)
       t

Generic matrix with array-based dense content.

val arraydense : ?context:Sundials.Context.t ->
       ?m:int -> ?i:float -> int -> 'nk arraydense

By default, arraydense n returns an n by n dense matrix with all elements initialized to 0.0. Optional arguments allow specifying the number of rows (m) and the initial value (i).

By default, the matrix is created using the context returned by Sundials.Context.default, but this can be overridden by passing an optional context argument.

val wrap_arraydense : ?context:Sundials.Context.t ->
       ArrayDense.t -> 'nk arraydense

Creates an (array-based dense) matrix by wrapping an existing array-based dense matrix. The two values share the same underlying storage.

By default, the matrix is created using the context returned by Sundials.Context.default, but this can be overridden by passing an optional context argument.

type 'nk arrayband = (custom, ArrayBand.t, Sundials.RealArray.t,
        'nk)
       t

Generic matrix with array-based band content.

val arrayband : ?context:Sundials.Context.t ->
       ?mu:int ->
       ?smu:int -> ?ml:int -> ?i:float -> int -> 'nk arrayband

By default, band n returns an n by n band matrix with all bandwidths equal to 2 and all values initialized to 0.0. Optional arguments allow specifying the upper bandwidth mu, the lower bandwidth ml, the storage upper bandwidth smu and the initial values i. If mu is given but not smu, then smu is set to mu, otherwise if smu is given but not mu, then mu is set to smu. If ml is not given, then it is set to mu.

By default, the matrix is created using the context returned by Sundials.Context.default, but this can be overridden by passing an optional context argument.

val wrap_arrayband : ?context:Sundials.Context.t ->
       ArrayBand.t -> 'nk arrayband

Creates an (array-based band) matrix by wrapping an existing array-based band matrix. The two values share the same underlying storage.

By default, the matrix is created using the context returned by Sundials.Context.default, but this can be overridden by passing an optional context argument.

val wrap_custom : ('m, 'nd) matrix_ops ->
       ?context:Sundials.Context.t ->
       'm -> (custom, 'm, 'nd, 'nk) t

Wrap a custom matrix value.

By default, the matrix is created using the context returned by Sundials.Context.default, but this can be overridden by passing an optional context argument.

type ('_, '_, '_, '_) id =
| Dense : (standard, Dense.t, Nvector_serial.data,
[> Nvector_serial.kind ])
id
| Band : (standard, Band.t, Nvector_serial.data,
[> Nvector_serial.kind ])
id
| Sparse : (standard, 's Sparse.t, Nvector_serial.data,
[> Nvector_serial.kind ])
id
| Custom : (custom, 'm, 'nd, 'nk) id
| ArrayDense : (custom, ArrayDense.t, Sundials.RealArray.t,
'nk0)
id
| ArrayBand : (custom, ArrayBand.t, Sundials.RealArray.t,
'nk1)
id

Matrix internal type identifiers.

val get_ops : ('k, 'm, 'nd, 'nk) t -> ('m, 'nd) matrix_ops

Return a record of matrix operations.

val get_id : ('k, 'm, 'nd, 'nk) t -> ('k, 'm, 'nd, 'nk) id

Return the internal type identifier of a matrix.

val unwrap : ('k, 'm, 'nd, 'nk) t -> 'm

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

Operations

val scale_add : float ->
       ('k, 'm, 'nd, 'nk) t ->
       ('k, 'm, 'nd, 'nk) t -> unit

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

val scale_addi : float -> ('k, 'm, 'nd, 'nk) t -> unit

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

val matvec_setup : ('k, 'm, 'nd, 'nk) t -> unit

Perform any setup required before a matrix-vector product.

val matvec : ('k, 'm, 'nd, 'nk) t ->
       ('nd, 'nk) Nvector.t -> ('nd, 'nk) Nvector.t -> unit

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

val set_to_zero : ('k, 'm, 'nd, 'nk) t -> unit

Fills a matrix with zeros.

val blit : src:('k, 'm, 'nd, 'nk) t ->
       dst:('k, 'm, 'nd, 'nk) t -> unit

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

val space : ('k, 'm, 'nd, 'nk) t -> int * int

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

val print_dense : [> Nvector_serial.kind ] dense -> Sundials.Logfile.t -> unit

Prints a dense matrix to the given log file.

NB: Not supported in Config.sundials_version < 3.0.0.

val print_band : [> Nvector_serial.kind ] band -> Sundials.Logfile.t -> unit

Prints a band matrix to the given log file.

NB: Not supported in Config.sundials_version < 3.0.0.

val print_sparse : ('s, [> Nvector_serial.kind ]) sparse ->
       Sundials.Logfile.t -> unit

Prints a sparse matrix to the given log file.

NB: Not supported in Config.sundials_version < 3.0.0.

val pp : Stdlib.Format.formatter -> ('k, 'm, 'nd, 'nk) t -> unit

Pretty-print a generic matrix using the Format module. For Custom matrices, it simply prints <custom matrix>.