Struct igraph_sparsemat_t 

pub struct igraph_sparsemat_t { /* private fields */ }

Implementations

impl igraph_sparsemat_t

pub fn eigen_symmetric( &self, which: &EigenWhich, algorithm: EigenAlgorithm, options: &ArpackOptions, ) -> Result<SymmetricEigen>

Selected eigenvalues and eigenvectors of a symmetric sparse matrix (igraph_eigen_matrix_symmetric with a sparse input); see eigen_matrix_symmetric.

pub fn eigen( &self, which: &EigenWhich, algorithm: EigenAlgorithm, ) -> Result<ComplexEigen>

Selected eigenvalues and eigenvectors of a general sparse matrix (igraph_eigen_matrix with a sparse input); see eigen_matrix.

impl igraph_sparsemat_t

pub fn new(nrow: usize, ncol: usize) -> Result<Self>

Creates an empty nrow × ncol sparse matrix in triplet format (igraph_sparsemat_init), ready to receive entries with entry.

Binds igraph_sparsemat_init.

pub fn with_capacity(nrow: usize, ncol: usize, nzmax: usize) -> Result<Self>

Creates an empty nrow × ncol triplet matrix with room for nzmax entries (igraph_sparsemat_init). The capacity is only a hint: the matrix grows as needed.

Binds igraph_sparsemat_init.

pub fn from_triplets( nrow: usize, ncol: usize, triplets: &[(usize, usize, f64)], ) -> Result<Self>

Builds a triplet matrix from (row, col, value) entries; entries at the same position are summed.

Errors

If an index is out of bounds.

pub fn eye(n: usize, value: f64, compress: bool) -> Result<Self>

Creates the n × n diagonal matrix with value on the diagonal (igraph_sparsemat_init_eye), in column-compressed format if compress is true, in triplet format otherwise. Time complexity: O(n).

Binds igraph_sparsemat_init_eye.

use igraph::linalg::SparseMat;
let i3 = SparseMat::eye(3, 1.0, true).unwrap();
assert!(i3.is_cc());
assert_eq!(i3.to_dense().unwrap().to_rows(), vec![vec![1.0, 0.0, 0.0], vec![0.0, 1.0, 0.0], vec![0.0, 0.0, 1.0]]);

pub fn identity(n: usize) -> Result<Self>

The n × n identity matrix, in column-compressed format.

pub fn diag(values: &[f64], compress: bool) -> Result<Self>

Creates a diagonal matrix with the given diagonal (igraph_sparsemat_init_diag), column-compressed if compress is true. Time complexity: O(n).

Binds igraph_sparsemat_init_diag.

pub fn from_dense(m: &Matrix, tol: f64) -> Result<Self>

Converts a dense matrix to a triplet sparse matrix, keeping only the elements whose absolute value is larger than tol (igraph_matrix_as_sparsemat). Time complexity: O(mn).

Binds igraph_matrix_as_sparsemat.

use igraph::{linalg::SparseMat, prelude::*};
let m = Matrix::from_rows(&[[1.0, 1e-12], [0.0, 2.0]]).unwrap();
let s = SparseMat::from_dense(&m, 1e-9).unwrap();
assert_eq!(s.nonzero_storage(), 2);

pub fn to_dense(&self) -> Result<Matrix>

Converts to a dense Matrix (igraph_sparsemat_as_matrix); works with both formats, duplicate entries are summed. Time complexity: O(mn).

Binds igraph_sparsemat_as_matrix.

pub fn realloc(&mut self, nzmax: usize) -> Result<()>

Changes the capacity (maximum number of stored entries) of the matrix (igraph_sparsemat_realloc). Rarely needed: matrices grow automatically.

Binds igraph_sparsemat_realloc.

pub fn nrow(&self) -> usize

Number of rows (igraph_sparsemat_nrow).

pub fn ncol(&self) -> usize

Number of columns (igraph_sparsemat_ncol).

pub fn shape(&self) -> (usize, usize)

(nrow, ncol).

pub fn sparse_type(&self) -> SparseMatType

The storage format (igraph_sparsemat_type).

pub fn is_triplet(&self) -> bool

Whether the matrix is in triplet format (igraph_sparsemat_is_triplet).

pub fn is_cc(&self) -> bool

Whether the matrix is column-compressed (igraph_sparsemat_is_cc).

pub fn nonzero_storage(&self) -> usize

Number of stored entries (igraph_sparsemat_nonzero_storage); they may include zeros and duplicates, see dupl and dropzeros.

pub fn nzmax(&self) -> usize

The allocated capacity for entries (igraph_sparsemat_nzmax).

pub fn entry(&mut self, row: usize, col: usize, value: f64) -> Result<()>

Appends an entry to a triplet matrix (igraph_sparsemat_entry). Entries at the same position are summed. Time complexity: O(1) amortized.

Binds igraph_sparsemat_entry.

Errors

If the matrix is column-compressed, or the position is out of bounds (use add_rows/add_cols to grow it).

pub fn get(&self, row: usize, col: usize) -> f64

The value at (row, col) (igraph_sparsemat_get), summing duplicate entries; zero if nothing is stored there or the position is out of bounds. Time complexity: O(entries in the column) for a column-compressed matrix, O(nz) for a triplet matrix.

For triplet matrices the lookup is done on the Rust side: igraph 1.0.0 and 1.0.1 scans them with its sparse matrix iterator, which reads past the end of the column index array (see iter).

Binds igraph_sparsemat_get.

pub fn compress(&self) -> Result<SparseMat>

Returns a column-compressed copy of the matrix (igraph_sparsemat_compress); if the matrix is already compressed, a plain copy. Time complexity: O(nz).

Binds igraph_sparsemat_compress.

pub fn transpose(&self) -> Result<SparseMat>

The transposed matrix (igraph_sparsemat_transpose), in the same format as self.

In igraph 1.0.0 and 1.0.1 the transpose of a non-square triplet matrix swaps the indices but forgets to swap the dimensions; this wrapper builds that case entry by entry instead.

Binds igraph_sparsemat_transpose.

pub fn is_symmetric(&self) -> Result<bool>

Whether the matrix is symmetric (igraph_sparsemat_is_symmetric); non-square matrices are not.

Duplicates are summed first, but the comparison is otherwise structural and exact: an explicitly stored zero at (i, j) without a stored counterpart at (j, i) makes the matrix non-symmetric (use dropzeros first), and so do values differing by rounding errors.

Binds igraph_sparsemat_is_symmetric.

pub fn dupl(&mut self) -> Result<()>

Sums duplicate entries of the same position into one (igraph_sparsemat_dupl). A triplet matrix is first converted to column-compressed format in place.

Binds igraph_sparsemat_dupl.

pub fn fkeep<F: FnMut(usize, usize, f64) -> bool>( &mut self, keep: F, ) -> Result<()>

Keeps only the stored entries for which keep(row, col, value) returns true (igraph_sparsemat_fkeep). A triplet matrix is first converted to column-compressed format in place.

Binds igraph_sparsemat_fkeep.

use igraph::linalg::SparseMat;
// Keep the upper triangle of a 3x3 matrix of ones.
let mut m = SparseMat::from_dense(&igraph::prelude::Matrix::from_rows(&[[1.0; 3]; 3]).unwrap(), 0.0).unwrap();
m.fkeep(|i, j, _| i <= j).unwrap();
assert_eq!(m.nonzero_storage(), 6);
assert_eq!(m.get(2, 0), 0.0);

pub fn dropzeros(&mut self) -> Result<()>

Removes the stored entries that are exactly zero (igraph_sparsemat_dropzeros); a triplet matrix is first compressed in place.

Binds igraph_sparsemat_dropzeros.

pub fn droptol(&mut self, tol: f64) -> Result<()>

Removes the stored entries whose absolute value is at most tol (igraph_sparsemat_droptol); a triplet matrix is first compressed in place.

Binds igraph_sparsemat_droptol.

pub fn multiply(&self, other: &SparseMat) -> Result<SparseMat>

Matrix product self * other (igraph_sparsemat_multiply), a column-compressed matrix. Also available as &a * &b.

Binds igraph_sparsemat_multiply.

Errors

If the inner dimensions do not match.

pub fn add(&self, other: &SparseMat, alpha: f64, beta: f64) -> Result<SparseMat>

Linear combination alpha * self + beta * other (igraph_sparsemat_add), a column-compressed matrix. &a + &b and &a - &b are shorthands.

Binds igraph_sparsemat_add.

Errors

If the shapes differ.

pub fn gaxpy(&self, x: &[f64], y: &[f64]) -> Result<Vec<f64>>

Computes y + A x (igraph_sparsemat_gaxpy, “generalized A x plus y”).

Binds igraph_sparsemat_gaxpy.

Errors

If x.len() != ncol or y.len() != nrow.

pub fn mul_vec(&self, x: &[f64]) -> Result<Vec<f64>>

The matrix-vector product A x (via gaxpy).

pub fn lsolve(&self, b: &[f64]) -> Result<Vec<f64>>

Solves the lower triangular system L x = b (igraph_sparsemat_lsolve).

The matrix must be square, lower triangular, and have all its diagonal elements stored (a zero on the diagonal gives infinite or NaN values).

Binds igraph_sparsemat_lsolve.

pub fn ltsolve(&self, b: &[f64]) -> Result<Vec<f64>>

Solves L' x = b where L (this matrix) is lower triangular (igraph_sparsemat_ltsolve); requirements as in lsolve.

Binds igraph_sparsemat_ltsolve.

pub fn usolve(&self, b: &[f64]) -> Result<Vec<f64>>

Solves the upper triangular system U x = b (igraph_sparsemat_usolve).

The matrix must be square, upper triangular, with a stored diagonal.

Binds igraph_sparsemat_usolve.

pub fn utsolve(&self, b: &[f64]) -> Result<Vec<f64>>

Solves U' x = b where U (this matrix) is upper triangular (igraph_sparsemat_utsolve); requirements as in usolve.

Binds igraph_sparsemat_utsolve.

pub fn cholsol(&self, b: &[f64], order: SparseOrdering) -> Result<Vec<f64>>

Solves A x = b for a symmetric positive definite A via a sparse Cholesky factorization (igraph_sparsemat_cholsol). Only the upper triangular part of A is used.

Binds igraph_sparsemat_cholsol.

Errors

If A is not square, b has the wrong length, or A is not positive definite.

pub fn lusol( &self, b: &[f64], order: SparseOrdering, tol: f64, ) -> Result<Vec<f64>>

Solves A x = b via a sparse LU factorization (igraph_sparsemat_lusol). tol is the partial pivoting threshold: 1.0 means classic partial pivoting, smaller values (e.g. 0.001) favor sparsity, together with a fill-reducing order.

Binds igraph_sparsemat_lusol.

Errors

If A is not square, b has the wrong length or A is singular.

pub fn print_to_string(&self) -> Result<String>

Prints the stored entries into a string (igraph_sparsemat_print).

Triplet matrices print one row col : value line per entry; column-compressed ones print, for each column, a col j: locations a to b header followed by row : value lines. Also used by the Display implementation.

Binds igraph_sparsemat_print.

pub fn permute(&self, p: &[usize], q: &[usize]) -> Result<SparseMat>

Permutes rows and columns (igraph_sparsemat_permute): row i of the result is row p[i] of self, and column j of the result is column q[j] of self. The result is column-compressed. Time complexity: O(m + n + nz).

Binds igraph_sparsemat_permute.

Errors

If p (resp. q) is not a permutation of 0..nrow (resp. 0..ncol).

pub fn index( &self, rows: Option<&[usize]>, cols: Option<&[usize]>, ) -> Result<SparseMat>

Extracts the submatrix made of the given rows and columns (igraph_sparsemat_index); None selects all rows (resp. columns). Indices may repeat. The result is column-compressed.

Binds igraph_sparsemat_index.

Errors

If an index is out of bounds.

pub fn lu(&self, order: SparseOrdering, tol: f64) -> Result<SparseLu>

Computes the symbolic analysis and numeric LU factorization of a square matrix (igraph_sparsemat_symblu + igraph_sparsemat_lu), to solve many systems with the same coefficient matrix via SparseLu::solve. tol is the partial pivoting threshold, as in lusol.

Binds igraph_sparsemat_symblu and igraph_sparsemat_lu.

use igraph::linalg::{SparseMat, SparseOrdering};
let a = SparseMat::from_triplets(2, 2, &[(0, 0, 2.0), (0, 1, 1.0), (1, 0, 1.0), (1, 1, 3.0)]).unwrap();
let lu = a.lu(SparseOrdering::Natural, 1.0).unwrap();
let x = lu.solve(&[3.0, 4.0]).unwrap();
assert!((x[0] - 1.0).abs() < 1e-12 && (x[1] - 1.0).abs() < 1e-12);

Errors

If the matrix is not square or is singular.

pub fn qr(&self, order: SparseOrdering) -> Result<SparseQr>

Computes the symbolic analysis and numeric QR factorization of a square matrix (igraph_sparsemat_symbqr + igraph_sparsemat_qr), to solve many systems with the same coefficient matrix via SparseQr::solve.

Binds igraph_sparsemat_symbqr and igraph_sparsemat_qr.

Errors

If the matrix is not square or the factorization fails.

pub fn arpack_rssolve( &self, options: &ArpackOptions, method: SparseSolveMethod, ) -> Result<ArpackSymmetricResult>

Eigenvalues and eigenvectors of a symmetric sparse matrix with ARPACK (igraph_sparsemat_arpack_rssolve).

With ArpackMode::Regular ARPACK works with products A x (this is igraph’s driver). With ArpackMode::ShiftInvert{ sigma } it works with (A - sigma I)^-1 x, computed by factorizing A - sigma I once with the given method (an LU decomposition with partial pivoting, or a QR decomposition); combined with ArpackWhich::LargestMagnitude this finds the eigenvalues closest to sigma. method is ignored in regular mode.

As with arpack_rssolve, 2 × 2 matrices in regular mode are solved in closed form, with the eigenpairs selected and normalized on the Rust side.

The shift-and-invert mode is driven from Rust (with lu/qr and arpack_rssolve): igraph’s own driver (1.0.0 and 1.0.1) factorizes without pivoting, which breaks down — and makes ARPACK abort the process — whenever A - sigma I has a zero on the diagonal.

Binds igraph_sparsemat_arpack_rssolve.

Errors

If the matrix is not square, contains non-finite values, the options are invalid, A - sigma I is singular, or ARPACK fails.

pub fn arpack_rnsolve( &self, options: &ArpackOptions, ) -> Result<ArpackNonSymmetricResult>

Eigenvalues and eigenvectors of a general (non-symmetric) sparse matrix with ARPACK (igraph_sparsemat_arpack_rnsolve). Only ArpackMode::Regular is supported.

Binds igraph_sparsemat_arpack_rnsolve.

pub fn max(&mut self) -> Result<f64>

The largest stored value, after summing duplicates (igraph_sparsemat_max); -inf if nothing is stored. Implicit zeros are not considered. A triplet matrix is compressed in place.

In igraph 1.0.0 and 1.0.1, igraph_sparsemat_max skips the last stored element, so this wrapper computes the maximum over the entries it reads with getelements after igraph_sparsemat_dupl.

pub fn min(&mut self) -> Result<f64>

The smallest stored value, after summing duplicates (igraph_sparsemat_min); +inf if nothing is stored. See max for the caveats.

pub fn minmax(&mut self) -> Result<(f64, f64)>

(min, max) of the stored values (igraph_sparsemat_minmax), see max.

pub fn count_nonzero(&mut self) -> Result<usize>

Number of stored entries that are not zero, after summing duplicates (igraph_sparsemat_count_nonzero). A triplet matrix is compressed in place.

Binds igraph_sparsemat_count_nonzero.

pub fn count_nonzerotol(&mut self, tol: f64) -> Result<usize>

Number of stored entries whose absolute value exceeds tol, after summing duplicates (igraph_sparsemat_count_nonzerotol).

Binds igraph_sparsemat_count_nonzerotol.

pub fn rowsums(&self) -> Result<Vec<f64>>

Row sums (igraph_sparsemat_rowsums). Time complexity: O(nz).

Binds igraph_sparsemat_rowsums.

pub fn colsums(&self) -> Result<Vec<f64>>

Column sums (igraph_sparsemat_colsums).

Binds igraph_sparsemat_colsums.

pub fn rowmins(&mut self) -> Result<Vec<f64>>

Minimum of the stored values of each row (igraph_sparsemat_rowmins); +inf for rows without stored values. Implicit zeros are not considered. A triplet matrix is compressed in place first, and duplicate entries are summed.

pub fn colmins(&mut self) -> Result<Vec<f64>>

Minimum of the stored values of each column (igraph_sparsemat_colmins), see rowmins.

pub fn rowmaxs(&mut self) -> Result<Vec<f64>>

Maximum of the stored values of each row (igraph_sparsemat_rowmaxs); -inf for rows without stored values.

pub fn colmaxs(&mut self) -> Result<Vec<f64>>

Maximum of the stored values of each column (igraph_sparsemat_colmaxs), see rowmaxs.

pub fn which_min_rows(&mut self) -> Result<(Vec<f64>, Vec<usize>)>

For each row, the minimum stored value and the column where it is found (igraph_sparsemat_which_min_rows); rows without stored values give (+inf, 0). A triplet matrix is compressed in place first.

pub fn which_min_cols(&mut self) -> Result<(Vec<f64>, Vec<usize>)>

For each column, the minimum stored value and the row where it is found (igraph_sparsemat_which_min_cols); columns without stored values give (+inf, 0). A triplet matrix is compressed in place first.

pub fn scale(&mut self, by: f64) -> Result<()>

Multiplies every element by by (igraph_sparsemat_scale). Time complexity: O(nz).

Binds igraph_sparsemat_scale.

pub fn scale_rows(&mut self, factors: &[f64]) -> Result<()>

Multiplies row i by factors[i] (igraph_sparsemat_scale_rows), i.e. computes diag(factors) * A.

Errors

If factors.len() != nrow.

pub fn scale_cols(&mut self, factors: &[f64]) -> Result<()>

Multiplies column j by factors[j] (igraph_sparsemat_scale_cols), i.e. computes A * diag(factors).

Errors

If factors.len() != ncol.

pub fn neg(&mut self) -> Result<()>

Negates every element in place (igraph_sparsemat_neg).

pub fn add_rows(&mut self, n: usize) -> Result<()>

Appends n zero rows (igraph_sparsemat_add_rows). Time complexity: O(1).

Binds igraph_sparsemat_add_rows.

pub fn add_cols(&mut self, n: usize) -> Result<()>

Appends n zero columns (igraph_sparsemat_add_cols).

Binds igraph_sparsemat_add_cols.

pub fn resize(&mut self, nrow: usize, ncol: usize, nzmax: usize) -> Result<()>

Resizes to nrow × ncol and removes all the entries (igraph_sparsemat_resize); the result is an empty triplet matrix with room for nzmax entries.

Binds igraph_sparsemat_resize.

pub fn getelements(&self) -> Result<SparseElements>

The raw stored elements (igraph_sparsemat_getelements), see SparseElements for the layout, which depends on the format.

Binds igraph_sparsemat_getelements.

pub fn getelements_sorted(&self) -> Result<SparseElements>

Like getelements, with the elements sorted by column, then by row (igraph_sparsemat_getelements_sorted).

Binds igraph_sparsemat_getelements_sorted.

pub fn sort(&self) -> Result<SparseMat>

A copy whose entries are sorted by column, then by row (igraph_sparsemat_sort), in the same format as self.

Binds igraph_sparsemat_sort.

pub fn multiply_by_dense(&self, b: &Matrix) -> Result<Matrix>

The dense product self * b of this sparse matrix with a dense matrix (igraph_sparsemat_multiply_by_dense).

Errors

If b.nrow() != self.ncol().

pub fn normalize_cols(&mut self, allow_zeros: bool) -> Result<()>

Divides each column by its sum (igraph_sparsemat_normalize_cols), making the matrix column-stochastic. The matrix must be square (igraph sizes the sums by the number of rows).

Errors

If a column sums to zero and allow_zeros is false, or the matrix is not square.

pub fn normalize_rows(&mut self, allow_zeros: bool) -> Result<()>

Divides each row by its sum (igraph_sparsemat_normalize_rows), making the matrix row-stochastic.

Errors

If a row sums to zero and allow_zeros is false.

pub fn iter(&self) -> SparseMatIter<'_>

Iterates over the stored entries as (row, col, value), in storage order (igraph_sparsemat_iterator_*); duplicates are not merged.

Column-compressed matrices are walked with igraph’s iterator. For triplet matrices, igraph_sparsemat_iterator_next of igraph 1.0.0 and 1.0.1 reads the column array as if it had ncol + 1 entries (it has nzmax), an out-of-bounds read as soon as nzmax <= ncol; the iterator then walks a copy of the entries made with getelements instead.

Panics

If copying the entries of a triplet matrix runs out of memory.

use igraph::linalg::SparseMat;
let m = SparseMat::diag(&[1.0, 2.0, 3.0], true).unwrap();
let entries: Vec<_> = m.iter().collect();
assert_eq!(entries, vec![(0, 0, 1.0), (1, 1, 2.0), (2, 2, 3.0)]);

pub fn triplets(&self) -> Vec<(usize, usize, f64)>

The stored entries as (row, col, value) triplets, in storage order.

Trait Implementations

impl Clone for igraph_sparsemat_t

fn clone(&self) -> Self

Deep copy with igraph_sparsemat_init_copy, keeping the storage format.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for igraph_sparsemat_t

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for igraph_sparsemat_t

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Prints the stored entries in igraph’s format, see SparseMat::print_to_string.

impl Drop for igraph_sparsemat_t

fn drop(&mut self)

Frees the matrix with igraph_sparsemat_destroy.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for igraph_sparsemat_t

impl Sync for igraph_sparsemat_t

impl TryFrom<&igraph_sparsemat_t> for Matrix

fn try_from(m: &SparseMat) -> Result<Self>

See SparseMat::to_dense.

type Error = Error

The type returned in the event of a conversion error.