Trait Matrix 

pub trait Matrix:
    MatrixCommon
    + Mul<Scale<Self::T>, Output = Self>
    + Clone
    + Send
    + 'static {
    type Sparsity: MatrixSparsity<Self>;
    type SparsityRef<'a>: MatrixSparsityRef<'a, Self>
       where Self: 'a;

    // Required methods
    fn sparsity(&self) -> Option<Self::SparsityRef<'_>>;
    fn context(&self) -> &Self::C;
    fn inner_mut(&mut self) -> &mut Self::Inner;
    fn partition_indices_by_zero_diagonal(
        &self,
    ) -> (<Self::V as Vector>::Index, <Self::V as Vector>::Index);
    fn gemv(&self, alpha: Self::T, x: &Self::V, beta: Self::T, y: &mut Self::V);
    fn copy_from(&mut self, other: &Self);
    fn zeros(nrows: IndexType, ncols: IndexType, ctx: Self::C) -> Self;
    fn new_from_sparsity(
        nrows: IndexType,
        ncols: IndexType,
        sparsity: Option<Self::Sparsity>,
        ctx: Self::C,
    ) -> Self;
    fn from_diagonal(v: &Self::V) -> Self;
    fn set_column(&mut self, j: IndexType, v: &Self::V);
    fn add_column_to_vector(&self, j: IndexType, v: &mut Self::V);
    fn set_data_with_indices(
        &mut self,
        dst_indices: &<Self::V as Vector>::Index,
        src_indices: &<Self::V as Vector>::Index,
        data: &Self::V,
    );
    fn gather(&mut self, other: &Self, indices: &<Self::V as Vector>::Index);
    fn scale_add_and_assign(&mut self, x: &Self, beta: Self::T, y: &Self);
    fn triplet_iter(
        &self,
    ) -> (impl Iterator<Item = (IndexType, IndexType)> + '_, impl Iterator<Item = Self::T> + '_);
    fn try_from_triplets(
        nrows: IndexType,
        ncols: IndexType,
        indices: Vec<(IndexType, IndexType)>,
        values: Vec<Self::T>,
        ctx: Self::C,
    ) -> Result<Self, LaError>;

    // Provided methods
    fn is_sparse() -> bool { ... }
    fn split(
        &self,
        algebraic_indices: &<Self::V as Vector>::Index,
    ) -> [(Self, <Self::V as Vector>::Index); 4] { ... }
    fn combine(
        ul: &Self,
        ur: &Self,
        ll: &Self,
        lr: &Self,
        algebraic_indices: &<Self::V as Vector>::Index,
    ) -> Self { ... }
}

A base matrix trait supporting both sparse and dense matrices.

This trait provides a complete interface for matrix operations including:

• Matrix creation and memory management
• Matrix-vector and matrix-matrix multiplication
• Element access and modification
• Sparsity information and handling
• Matrix decomposition and combination operations
• Triplet-based construction for sparse matrices

Implementing matrices can be dense or sparse, and may be hosted on CPU or GPU. Users typically do not need to implement this trait; use provided implementations.

Required Associated Types

type Sparsity: MatrixSparsity<Self>

type SparsityRef<'a>: MatrixSparsityRef<'a, Self> where Self: 'a

Required Methods

fn sparsity(&self) -> Option<Self::SparsityRef<'_>>

Return sparsity information, or None if the matrix is dense.

fn context(&self) -> &Self::C

Get the context associated with this matrix (for device placement, memory management, etc.).

fn inner_mut(&mut self) -> &mut Self::Inner

Get a mutable reference to the inner representation of the matrix.

fn partition_indices_by_zero_diagonal( &self, ) -> (<Self::V as Vector>::Index, <Self::V as Vector>::Index)

Partition the diagonal indices into two groups: those with zero diagonal elements and those with non-zero diagonal elements.

This is useful for identifying algebraic constraints, which typically have zero diagonal elements in the mass matrix. Returns a tuple of (zero_diagonal_indices, non_zero_diagonal_indices).

fn gemv(&self, alpha: Self::T, x: &Self::V, beta: Self::T, y: &mut Self::V)

Perform a matrix-vector multiplication: y = alpha * self * x + beta * y

fn copy_from(&mut self, other: &Self)

Copy the contents of other into this matrix.

fn zeros(nrows: IndexType, ncols: IndexType, ctx: Self::C) -> Self

Create a new matrix of shape nrows x ncols filled with zeros.

fn new_from_sparsity( nrows: IndexType, ncols: IndexType, sparsity: Option<Self::Sparsity>, ctx: Self::C, ) -> Self

Create a new matrix from a sparsity pattern. Non-zero elements are not initialized.

fn from_diagonal(v: &Self::V) -> Self

Create a new diagonal matrix from a vector holding the diagonal elements.

fn set_column(&mut self, j: IndexType, v: &Self::V)

Set the values of column j to be equal to the values in v.

For sparse matrices, only the existing non-zero elements are updated.

fn add_column_to_vector(&self, j: IndexType, v: &mut Self::V)

Add a column of this matrix to a vector: v += self[:, j]

fn set_data_with_indices( &mut self, dst_indices: &<Self::V as Vector>::Index, src_indices: &<Self::V as Vector>::Index, data: &Self::V, )

Assign the values in the data vector to this matrix at the indices in dst_indices from the indices in src_indices.

For dense matrices, the index is the data index in column-major order. For sparse matrices, the index is the index into the data array.

fn gather(&mut self, other: &Self, indices: &<Self::V as Vector>::Index)

Gather values from another matrix at specified indices into this matrix.

For sparse matrices: the index idx_i in indices is an index into the data array for other, and is copied to the index idx_i in the data array for this matrix. For dense matrices: the index is the data index in column-major order.

fn scale_add_and_assign(&mut self, x: &Self, beta: Self::T, y: &Self)

Perform the assignment: self = x + beta * y where x and y are matrices and beta is a scalar.

Note: Panics if the sparsity patterns of self, x, and y do not match. The sparsity of self must be the union of the sparsity of x and y.

fn triplet_iter( &self, ) -> (impl Iterator<Item = (IndexType, IndexType)> + '_, impl Iterator<Item = Self::T> + '_)

Iterate over structural positions and values of the matrix.

Returns a tuple:

• First iterator: (row, col) pairs for each non-zero element (length nnz)
• Second iterator: values (length nnz * nbatch), laid out batch-contiguously: [batch0_val0..batch0_valN, batch1_val0..batch1_valN, ...]

fn try_from_triplets( nrows: IndexType, ncols: IndexType, indices: Vec<(IndexType, IndexType)>, values: Vec<Self::T>, ctx: Self::C, ) -> Result<Self, LaError>

Create a new matrix from structural indices and values.

• indices: (row, col) pairs for each non-zero element (length nnz)
• values: values laid out batch-contiguously (length nnz * ctx.nbatch()): [batch0_val0..batch0_valN, batch1_val0..batch1_valN, ...]

Provided Methods

fn is_sparse() -> bool

Returns true if this matrix is stored in a sparse format

fn split( &self, algebraic_indices: &<Self::V as Vector>::Index, ) -> [(Self, <Self::V as Vector>::Index); 4]

Split this matrix into four submatrices based on algebraic constraint indices.

Partitions the matrix into blocks:

M = [UL, UR]
    [LL, LR]

where:

• UL contains rows and columns NOT in algebraic_indices
• UR contains rows NOT in algebraic_indices and columns in algebraic_indices
• LL contains rows in algebraic_indices and columns NOT in algebraic_indices
• LR contains rows and columns in algebraic_indices

Returns an array of tuples, where each tuple contains a submatrix and the indices that were used to create it. These indices can be used with gather() to update the submatrix.

fn combine( ul: &Self, ur: &Self, ll: &Self, lr: &Self, algebraic_indices: &<Self::V as Vector>::Index, ) -> Self

Combine four submatrices back into a single matrix based on algebraic constraint indices.

Inverse operation of split(). Takes submatrices ul, ur, ll, lr and combines them back into the original matrix structure.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<T: FaerScalar> Matrix for FaerMat<T>

type Sparsity = Dense<FaerMat<T>>

type SparsityRef<'a> = DenseRef<'a, FaerMat<T>>

impl<T: FaerScalar> Matrix for FaerSparseMat<T>

type Sparsity = SymbolicSparseColMat<Own<usize>>

type SparsityRef<'a> = SymbolicSparseColMat<Ref<'a, usize>>

impl<T: NalgebraScalar> Matrix for NalgebraMat<T>

type Sparsity = Dense<NalgebraMat<T>>

type SparsityRef<'a> = DenseRef<'a, NalgebraMat<T>>