SF_SPARSE

Description

Local sparse matrices with dynamic row or column storage, in double real (D) and double complex (Z) arithmetic.

The implementations are contained in explicit Fortran modules: SF_SPARSE_CSR_D, SF_SPARSE_CSR_Z, SF_SPARSE_CSC_D, and SF_SPARSE_CSC_Z.

Storage and insertion contract

These objects contain an array of allocatable sparse rows (CSR) or columns (CSC), rather than a single packed CSR/CSC buffer.

Warning

Insertion MUST preserve sorted indices. For CSR, append new column indices in strictly increasing order within each row. For CSC, append new row indices in strictly increasing order within each column. Neither insert nor fast_insert sorts indices or reorders values.

insert(value,i,j) adds to an existing coordinate, or appends a new one. An existing coordinate can be revisited without disturbing the ordering.

fast_insert(value,i,j) always appends: the caller must guarantee both uniqueness and increasing order. Rows/columns can be interleaved during construction; the ordering requirement applies independently within each. The same contract applies when directly filling the public storage components. Violating it can produce incorrect merge and multiplication results.

nnz() counts stored entries, including exact zeros. Algebra does not apply an implicit tolerance. Matrix multiplication omits exact-zero results to avoid performance losses.

Dimensions and indices use default Fortran integers.

Construction and access

The four public types retain their names: sparse_dmatrix_csr, sparse_zmatrix_csr, sparse_dmatrix_csc, and sparse_zmatrix_csc.

use SF_SPARSE
type(sparse_dmatrix_csr) :: A, B, C
real(8) :: dense(3,5), x(5)
real(8), allocatable :: y(:)

call A%init(3,5)
call A%insert(2d0,1,1)
call A%insert(3d0,1,4) ! increasing columns within row 1
call A%insert(1d0,2,2) ! row 2 has its own insertion order
x = 1d0
y = matmul(A,x)       ! length 3
call A%dump(dense)    ! replaces the destination contents
B = as_csr(dense)
C = transpose(A)     ! shape [5,3], CSR storage

init(n) constructs an empty square matrix; init(m,n) constructs an empty rectangular matrix.

free() is safe on fresh and already freed objects.

shape(A) and A%shape() return the physical row/column counts.

get(i,j) returns zero for an absent coordinate.

as_csr(dense) and as_csc(dense) select storage explicitly and overload on real/complex input. Type-name constructors also accept dense input.

as_sparse and sparse remain available when importing a single orientation; they are intentionally absent from the combined facade because Fortran cannot choose an orientation from the result type alone.

as_matrix(A) / A%as_matrix() returns a dense array; dump overwrites an existing dense array of matching shape. copy and intrinsic matrix assignment perform deep copies. Assigning a scalar changes only stored values, not the sparsity pattern. The inherited Nelements field caches the stored-entry count and is maintained by the library. nnz() computes the count from the concrete storage. If filling storage arrays directly, keep their sizes and Nelements consistent.

Common parent and polymorphism

All four types extend the concrete sparse_matrix parent from SF_SPARSE_COMMON; it is also exported by SF_SPARSE and SCIFOR. Dimensions, Nelements, and initialization status live in that parent.

use SF_SPARSE
class(sparse_matrix), allocatable :: A

allocate(sparse_zmatrix_csc :: A)
call A%init(3,5)        ! dispatches to CSC_Z initialization
print *, A%shape(), A%nnz(), A%bytes()
select type(A)
type is(sparse_zmatrix_csc)
   call A%insert((2d0,1d0),1,2)
end select
call A%free()           ! frees the concrete CSC storage

The common interface provides init, free, shape, nnz, bytes, and (in MPI builds) bcast. The concrete implementations override operations that depend on storage. Numerical insertion, extraction, and algebra remain on the concrete types; use select type when starting from a parent polymorphic declaration. Generic numerical operators do not dispatch from the parent’s declared type.

A plain type(sparse_matrix) object contains metadata only. Its initialization creates no numerical entries. An allocatable class(sparse_matrix) object can hold any concrete child. A polymorphic array has one dynamic type for the whole array; for heterogeneous collections, use a wrapper with an allocatable class(sparse_matrix) component per element.

For bcast through the parent interface, every rank must already have an object of the same concrete dynamic type. The method transfers its contents; it does not allocate or change the receiver’s dynamic type.

Algebra

Supported operations for each type are addition, subtraction, scalar multiplication/division, transpose, Hermitian conjugate, matrix multiplication, both left and right vector multiplication, and Kronecker products.

• matmul(A,B) and A .m. B multiply sparse matrices of the same type and return the same storage orientation. The implementation intersects sorted index streams against a transposed operand.

• matmul(A,v) and A%dot(v) return a vector of length A%Nrow.

• matmul(v,A) returns a vector of length A%Ncol.

  Warning

  This is an ordinary product: it does not conjugate the complex vector.

• transpose(A), A%transpose() and A%t() transpose without conjugation.

• hconjg(A) and A%dgr() return the Hermitian conjugate; for real matrices these are the ordinary transpose. Complex types also provide A%conjg().

• kron(A,B) and A .x. B use the convention C((i-1)*B%Nrow+k,(j-1)*B%Ncol+l)=A(i,j)*B(k,l).

• sp_eye_csr_d(n), sp_eye_csr_z(n), sp_eye_csc_d(n), and sp_eye_csc_z(n) construct sparse identities directly.

Mixed CSR/CSC and mixed real/complex sparse matrix products are not provided. Filtering, restricted Kronecker products, and parallel multiplication are outside this implementation.

I/O and diagnostics

write(file=...) / read(file=...) serialize the dimensions followed by one size and its index/value entries per stored row or column. Files preserve the physical row/column counts but have orientation-specific payloads: read with the same orientation and numerical type. Exactly one of file or unit must be supplied. Caller-owned units remain open. Reads require valid, strictly increasing indices.

show(fmt=...,file=...) prints the dense matrix; display() prints stored coordinates and values. spy(header) writes coordinate data and a Gnuplot command file; it does not execute an external plotting program. bytes() returns the local stored payload in decimal kilobytes, excluding allocatable descriptors, allocation overhead, and padding. It is available with or without MPI.

MPI helpers

With USE_MPI=ON, each sparse matrix remains an ordinary local object. No distributed ownership of its rows or columns is implied.

A%bcast(comm,root) collectively replaces the object on receivers with the root’s object, including dimensions and initialization status. The defaults are MPI_COMM_WORLD and root zero; a supplied root is a rank in the supplied communicator. An initialized empty matrix and an uninitialized object remain distinct. Only members of that communicator participate.

AllGather_MPI(comm,array) assembles rank-one or rank-two arrays of whole matrix objects. Array extents must agree on all participating ranks. Each entry must be initialized on at most one rank; an entry with no owner remains uninitialized. Inconsistent extents or multiple owners cause a collective MPI_Abort. After gathering, all ranks hold replicas: free replicas before using initialization status to express ownership in a subsequent gather.

Validation

Numerical regression tests have been carried out for all four types against small dense reference calculations, including rectangular and empty matrices, complex arithmetic, the polymorphic parent interface, and stored-entry counts. MPI tests cover split communicators, nonzero roots, whole-object array gathering, and rejection of duplicate owners or inconsistent array extents. Both MPI and serial library builds have been checked.

Used modules

• sf_sparse_common: Common sparse-matrix parent, metadata, and storage helpers

  • sparse_matrix

• sf_sparse_csr_d: Double real sparse matrices stored as dynamic rows

  • allgather_mpi()

• sf_sparse_csr_z: Double complex sparse matrices stored as dynamic rows

  • allgather_mpi()

• sf_sparse_csc_d: Double real sparse matrices stored as dynamic columns

  • allgather_mpi()

• sf_sparse_csc_z: Double complex sparse matrices stored as dynamic columns

  • allgather_mpi()

Common parent and helpers

Description

The concrete CSR/CSC numerical types extend sparse_matrix. The parent defines the value-independent lifecycle and communication interface. A plain parent object contains metadata only; an allocatable class(sparse_matrix) object can hold any concrete sparse child.

Quick access

Types:

sparse_matrix

Routines:

append(), append_d(), append_da(), append_i(), append_ia(), append_z(), append_za(), bcast_matrix(), binary_search(), bytes_matrix(), free_matrix(), init_matrix(), nnz_matrix(), shape(), shape_matrix(), sort_array()

Used modules

• sf_mpi: SciFortran MPI interface

  • bcast_mpi()

  • check_mpi()

External modules

• mpi

Types

type  sf_sparse_common/sparse_matrix

Common parent for the four concrete sparse types. Use class(sparse_matrix) for runtime selection of a concrete type. Bindings init, free, nnz, bytes, and (with MPI) bcast are overridden by the children; shape is inherited. Numerical insertion and algebra require a concrete declaration or select type. A plain parent has no numerical row/column storage.

Type fields:

• nrow [integer] – Physical row count; zero for a fresh or freed object.

• ncol [integer] – Physical column count; zero for a fresh or freed object.

• nelements [integer] – Cached stored-entry count, including exact zeros; maintained by library operations.

• status [logical] – True for initialized objects, including initialized empty matrices.

Subroutines and functions

interface  sf_sparse_common/append(vec, val, values)

Append an integer, double real, or double complex scalar/array without sorting.

Parameters:

• vec (•) [integer/real/complex, inout,allocatable] – Allocatable destination vector; existing entries are retained.

• val [integer/real/complex, in] – Scalar to append.

• values (•) [integer/real/complex, in] – Array to append in its existing order.

interface  sf_sparse_common/shape(self)

Return physical row/column counts for the parent or any concrete extension.

Parameters:

self [real]

Result:

shape (2) [integer]

subroutine  sf_sparse_common/init_matrix(sparse, nrow[, ncol])

Initialize parent metadata with nonnegative dimensions and zero stored entries. The optional column count defaults to the row count. Concrete children override this binding to allocate their row/column storage.

Parameters:

• sparse [real] – Parent object; overridden bindings dispatch on its concrete dynamic type.

• nrow [integer, in] – Nonnegative physical row count.

Options:

ncol [integer, in] – Optional physical column count; defaults to Nrow.

subroutine  sf_sparse_common/free_matrix(sparse)

Reset parent dimensions, cached count, and initialization status. Safe for fresh or already freed objects; children override it to release storage.

Parameters:

sparse [real] – Parent object; overridden bindings dispatch on its concrete dynamic type.

function  sf_sparse_common/nnz_matrix(sparse)

Return the cached stored-entry count for a metadata-only parent. Concrete children override this binding to count their actual storage.

Parameters:

sparse [real] – Parent object; overridden bindings dispatch on its concrete dynamic type.

Result:

nnz [integer]

function  sf_sparse_common/bytes_matrix(self)

Return the parent metadata payload in decimal kilobytes. Excludes padding and descriptors. Children include their numerical storage. This is a local estimate, available without MPI.

Parameters:

self [real] – Parent object or a concrete extension.

Result:

kbytes [real]

subroutine  sf_sparse_common/bcast_matrix(self[, comm, root])

Collectively broadcast metadata for a plain parent object. Defaults are MPI_COMM_WORLD and root zero in the supplied communicator. MPI must be initialized. Concrete children override this binding to transfer complete storage; all ranks must already hold the same concrete dynamic type.

Parameters:

self [real] – Parent object or a concrete extension.

Options:

• comm [integer, in]

• root [integer, in] – Communicator and source rank; defaults MPI_COMM_WORLD and zero.

function  sf_sparse_common/shape_matrix(self)

Return physical dimensions [Nrow,Ncol]. Accepts the parent and every concrete extension through class(sparse_matrix). Available as shape(A) and A%shape().

Parameters:

self [real]

Result:

shape (2) [integer]

subroutine  sf_sparse_common/sort_array(array, order)

Sort an integer array in place and return its permutation. After sorting, each output element equals the original element at the corresponding position of order. This legacy quicksort uses random pivots and advances the Fortran random-number generator. Sparse insertion does not call this routine or automatically sort stored values.

Parameters:

• array (•) [integer, in,required] – Integer array to sort in place.

• order (size(array)) [integer] – Permutation mapping sorted positions to original positions.

function  sf_sparse_common/binary_search(ain, value)

Search a strictly increasing integer index array without modifying it. Returns its one-based position, or zero when the value is absent, including for an empty array. No allocation or sorting is performed.

Parameters:

• ain (•) [integer, in]

• value [integer, in]

Result:

pos [integer]

subroutine  sf_sparse_common/append_i(vec, val)

Append one scalar to an allocatable vector, preserving existing entries. An unallocated vector is allocated. Storage may be reallocated; intended for dynamic assembly rather than bulk numerical kernels.

Parameters:

• vec (•) [integer, inout,allocatable] – Allocatable destination vector; existing entries are retained.

• val [integer, in] – Scalar to append.

subroutine  sf_sparse_common/append_d(vec, val)

Append one scalar to an allocatable vector, preserving existing entries. An unallocated vector is allocated. Storage may be reallocated; intended for dynamic assembly rather than bulk numerical kernels.

Parameters:

• vec (•) [real, inout,allocatable] – Allocatable destination vector; existing entries are retained.

• val [real, in] – Scalar to append.

subroutine  sf_sparse_common/append_z(vec, val)

Append one scalar to an allocatable vector, preserving existing entries. An unallocated vector is allocated. Storage may be reallocated; intended for dynamic assembly rather than bulk numerical kernels.

Parameters:

• vec (•) [complex, inout,allocatable] – Allocatable destination vector; existing entries are retained.

• val [complex, in] – Scalar to append.

subroutine  sf_sparse_common/append_ia(vec, values)

Append an array to an allocatable vector, preserving entry order. An unallocated destination is allocated. This helper does not sort indices, combine duplicates, or prune zeros.

Parameters:

• vec (•) [integer, inout,allocatable] – Allocatable destination vector; existing entries are retained.

• values (•) [integer, in] – Array to append in its existing order.

subroutine  sf_sparse_common/append_da(vec, values)

Append an array to an allocatable vector, preserving entry order. An unallocated destination is allocated. This helper does not sort indices, combine duplicates, or prune zeros.

Parameters:

• vec (•) [real, inout,allocatable] – Allocatable destination vector; existing entries are retained.

• values (•) [real, in] – Array to append in its existing order.

subroutine  sf_sparse_common/append_za(vec, values)

Append an array to an allocatable vector, preserving entry order. An unallocated destination is allocated. This helper does not sort indices, combine duplicates, or prune zeros.

Parameters:

• vec (•) [complex, inout,allocatable] – Allocatable destination vector; existing entries are retained.

• values (•) [complex, in] – Array to append in its existing order.

CSR: double real

Description

Concrete implementation of sparse_dmatrix_csr, extending the common sparse_matrix parent. Import SF_SPARSE for the combined public API.

Warning

NEW column indices MUST increase strictly within each stored row. insert accumulates existing coordinates; fast_insert requires unique coordinates. Neither operation sorts indices or reorders values.

Dimensions and coordinates are physical row/column counts and one-based indices. Matrices are local objects. Optional MPI collectives transfer complete objects.

Quick access

Types:

sparse_row, sparse_dmatrix_csr

Routines:

allgather_mpi(), as_csr(), as_matrix(), as_sparse(), assignment(=)(), hconjg(), kron(), matmul(), operator(*)(), operator(.m.)(), operator(.x.)(), operator(/)(), sp_as_matrix_csr_d(), sp_bcast_matrix_csr_d(), sp_copy_matrix_csr_d(), sp_display_matrix_csr_d(), sp_dump_matrix_csr_d(), sp_eye_csr_d(), sp_fast_insert_element_csr_d(), sp_free_matrix_csr_d(), sp_get_bytes_matrix_csr_d(), sp_get_element_csr_d(), sp_hconjg_matrix_csr_d(), sp_init_matrix_csr_d(), sp_insert_element_csr_d(), sp_load_matrix_csr_d(), sp_matmul_vector_csr_d(), sp_nnz_matrix_csr_d(), sp_read_matrix_csr_d(), sp_show_matrix_csr_d(), sp_spy_matrix_csr_d(), sp_transpose_matrix_csr_d(), sp_write_matrix_csr_d(), sparse(), sparse_dmatrix_csr(), transpose()

Used modules

• sf_sparse_common: Common sparse-matrix parent, metadata, and storage helpers

  • sparse_matrix

  • shape()

  • append()

  • binary_search()

• sf_iotools: SciFortran module for reading and writing data

  • str()

  • free_unit()

• sf_misc: SciFortran module for sundry functions

  • assert_shape()

• sf_mpi: SciFortran MPI interface

External modules

• mpi

Types

type  sf_sparse_csr_d/sparse_row

One dynamic sparse row. Indices are strictly increasing and values have matching length.

Type fields:

• size [integer]

• cols (•) [integer, allocatable]

• vals (•) [real, allocatable]

type  sf_sparse_csr_d/sparse_dmatrix_csr

Double real local sparse matrix with inherited metadata and lifecycle interface. Each stored row holds increasing column indices and matching values. The inherited Nelements cache is maintained by library operations; direct storage edits must also maintain sizes, ordering, and this cache. Use class(sparse_matrix) for value-independent polymorphic operations.

Type fields:

• row (•) [sparse_row, allocatable] – Concrete sparse row storage; never distributed across MPI ranks.

Subroutines and functions

interface  sf_sparse_csr_d/sparse_dmatrix_csr(matrix)

Dense-array constructor for sparse_dmatrix_csr.

Parameters:

matrix (•, •) [real, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_dmatrix_csr] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csr_d/as_csr(matrix)

Construct this CSR numerical type from a dense array with as_csr(matrix).

Parameters:

matrix (•, •) [real, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_dmatrix_csr] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csr_d/as_sparse(matrix)

Dense-to-sparse constructor alias available when importing one storage orientation.

Parameters:

matrix (•, •) [real, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_dmatrix_csr] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csr_d/as_matrix(sparse)

Return the physical dense representation of a sparse object.

Parameters:

sparse [real]

Result:

matrix (sparse%nrow, sparse%ncol) [real] – Dense array with physical row/column shape, or returned dense representation.

interface  sf_sparse_csr_d/sparse(matrix)

Dense-to-sparse constructor alias available when importing one storage orientation.

Parameters:

matrix (•, •) [real, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_dmatrix_csr] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csr_d/assignment(=)(a, c)

Scalar assignment changes stored values only. Matrix-to-matrix copying uses intrinsic assignment.

Parameters:

• a [sparse_dmatrix_csr, inout] – First sparse operand or source matrix.

• c [real, in] – Scalar value; a divisor must be nonzero.

interface  sf_sparse_csr_d/operator(*)(c, a)

Multiply stored values by an integer, real, or supported complex scalar.

Parameters:

• c [integer/real, in] – Scalar value; a divisor must be nonzero.

• a [sparse_dmatrix_csr, in]

Result:

b [sparse_dmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_d/operator(/)(a, c)

Divide stored values by a nonzero integer, real, or supported complex scalar.

Parameters:

• a [sparse_dmatrix_csr, in] – First sparse operand or source matrix.

• c [integer/real, in]

Result:

b [sparse_dmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_d/operator(.m.)(a, b)

Ordinary sparse matrix multiplication, equivalent to matmul(A,B).

Parameters:

• a [sparse_dmatrix_csr, in]

• b [sparse_dmatrix_csr, in]

Result:

axb [sparse_dmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_d/operator(.x.)(a, b)

Kronecker product, equivalent to kron(A,B).

Parameters:

• a [sparse_dmatrix_csr, in]

• b [sparse_dmatrix_csr, in]

Result:

c [sparse_dmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_d/kron(a, b)

Kronecker product preserving orientation and numerical type.

Parameters:

• a [sparse_dmatrix_csr, in]

• b [sparse_dmatrix_csr, in]

Result:

c [sparse_dmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_d/transpose(a)

Transpose without conjugating values; the output keeps the input storage orientation.

Parameters:

a [real] – tranpose

Result:

c [sparse_dmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_d/hconjg(a)

Hermitian conjugate; equivalent to ordinary transpose for real values.

Parameters:

a [real] – tranpose

Result:

c [sparse_dmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_d/matmul(a, b, h, v, vector, matrix)

Ordinary sparse matrix-matrix, matrix-vector, and vector-matrix products. Complex inputs are not conjugated.

Parameters:

• a [sparse_dmatrix_csr, in]

• b [sparse_dmatrix_csr, in]

• h [real] – Initialized sparse matrix.

• v (•) [real, in]

• vector (•) [real, in] – Input left vector; its length must match the matrix row count.

• matrix [integer] – Dense array with physical row/column shape, or returned dense representation.

Result:

• axb [sparse_dmatrix_csr] – Returned result; its physical shape and semantics are specified above.

• hv (•) [real, allocatable] – Returned product vector with the length specified above.

interface  sf_sparse_csr_d/allgather_mpi(comm, a)

Collectively replicate rank-one or rank-two arrays of whole matrices from unique owners.

Parameters:

• comm [integer, in] – MPI communicator; broadcast defaults to MPI_COMM_WORLD.

• a [external] – Rank-one or rank-two array of matrices; initialization marks unique ownership.

subroutine  sf_sparse_csr_d/sp_init_matrix_csr_d(sparse, nrow[, ncol])

Initialize an empty local matrix through A%init(Nrow,Ncol). The optional second dimension defaults to Nrow. Existing storage is released. Dimensions must be nonnegative; all row/column arrays start empty.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• nrow [integer, in] – Physical number of rows; must be nonnegative.

Options:

ncol [integer, in] – Physical number of columns; defaults to Nrow.

subroutine  sf_sparse_csr_d/sp_copy_matrix_csr_d(sparse, b)

Deep-copy b into sparse, including dimensions and status. An uninitialized source leaves the destination uninitialized. Numerical arrays are copied independently. Ordinary matrix assignment also performs a deep copy.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• b [sparse_dmatrix_csr, in] – Second sparse operand or source matrix.

subroutine  sf_sparse_csr_d/sp_free_matrix_csr_d(sparse)

Release all concrete sparse storage and reset dimensions, entry count, and status. Safe for fresh objects and repeated calls. Overrides the common parent binding.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

subroutine  sf_sparse_csr_d/sp_load_matrix_csr_d(sparse, matrix)

Replace this object by the sparse representation of matrix. The physical shape is preserved and exact zeros are omitted. The construction order satisfies the sorted-index contract without requiring a caller-side sort.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• matrix (•, •) [real, in] – Dense array with physical row/column ordering.

subroutine  sf_sparse_csr_d/sp_dump_matrix_csr_d(sparse, matrix)

Write the dense representation into an existing array of matching shape. The destination is cleared first: this operation replaces its contents rather than accumulating into them. The sparse object is unchanged.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• matrix (•, •) [real, inout] – Dense array with physical row/column ordering.

function  sf_sparse_csr_d/sp_as_matrix_csr_d(sparse)

Return a dense rank-two array with physical shape [Nrow,Ncol]. Absent coordinates are zero. Available as A%as_matrix() and as_matrix(A). An uninitialized object has the default zero-by-zero shape.

Parameters:

sparse [real]

Result:

matrix (sparse%nrow, sparse%ncol) [real] – Dense array with physical row/column shape, or returned dense representation.

subroutine  sf_sparse_csr_d/sp_insert_element_csr_d(sparse, value, i, j)

Add value to a physical matrix coordinate, called as A%insert(value,row,column). Existing coordinates are accumulated.

Warning

NEW indices MUST be appended in strictly increasing order within each stored row (CSR) or column (CSC). This routine does not sort indices or reorder values. Revisiting an existing coordinate preserves the ordering.

The matrix must be initialized and the physical coordinate must be in bounds. Exact zero values remain stored and contribute to nnz() / Nelements.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• value [real, in] – Value to accumulate (insert) or append (fast_insert).

• i [integer, in] – check if column already exist

• j [integer, in] – Physical coordinate arguments; call with row, column.

subroutine  sf_sparse_csr_d/sp_fast_insert_element_csr_d(sparse, value, i, j)

Append a value at a physical coordinate through A%fast_insert(value,row,column), without searching for an existing entry.

Warning

The caller MUST guarantee unique coordinates and strictly increasing indices within each stored CSR row or CSC column. No sorting or duplicate accumulation is performed.

The object must be initialized and the coordinate must be in bounds.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• value [real, in] – Value to accumulate (insert) or append (fast_insert).

• i [integer, in]

• j [integer, in] – Physical coordinate arguments; call with row, column.

function  sf_sparse_csr_d/sp_get_element_csr_d(sparse, i, j)

Return the value at a physical coordinate through A%get(row,column). An absent coordinate returns exact zero. The object must be initialized, the coordinate must be in bounds, and stored indices must satisfy the ordering contract.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• i [integer, in]

• j [integer, in]

Result:

val [real] – Value at the requested physical coordinate; zero when absent.

function  sf_sparse_csr_d/sp_nnz_matrix_csr_d(sparse)

Count stored entries from the concrete row/column sizes. Exact zeros are counted. Uninitialized objects return zero. This storage-based count is independent of the inherited cache Nelements.

Parameters:

sparse [real]

Result:

nnz [integer] – Number of stored entries, including exact zeros.

subroutine  sf_sparse_csr_d/sp_show_matrix_csr_d(sparse[, fmt, file])

Print the dense matrix in physical row/column order. The default edit descriptor is ES16.8; fmt may supply another real edit descriptor, also used for each component of complex values. Output goes to unit 6 unless file is supplied. An uninitialized object produces no output. The object is unchanged.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

Options:

• fmt [character(len=*), in]

• file [character(len=*), in]

subroutine  sf_sparse_csr_d/sp_display_matrix_csr_d(sparse)

Print stored physical row indices, column indices, and values to standard output. Absent coordinates are not printed. An uninitialized object produces no output.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

subroutine  sf_sparse_csr_d/sp_write_matrix_csr_d(sparse[, file, unit])

Serialize an initialized matrix as formatted dimensions and index/value records. Supply exactly one of file or unit. A named file is replaced and closed by this routine; a caller-owned unit remains open. The payload is orientation-specific and must be read with the same storage and numerical type.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

Options:

• file [character(len=*)] – File name; owned and closed by this routine.

• unit [integer] – Caller-owned formatted unit, left open on return.

subroutine  sf_sparse_csr_d/sp_read_matrix_csr_d(sparse[, file, unit])

Replace this object by a matrix read from formatted dimensions and index/value records. Supply exactly one of file or unit. A named file must exist and is closed after reading; a caller-owned unit remains open. Stored sizes and index bounds are checked, and indices must be strictly increasing within each record. Use the same orientation and numerical type as the writer.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

Options:

• file [character(len=*)] – File name; owned and closed by this routine.

• unit [integer] – Caller-owned formatted unit, left open on return.

subroutine  sf_sparse_csr_d/sp_spy_matrix_csr_d(sparse, header)

Write stored coordinates to header_data.dat and plotting instructions to plot_header_commands.gp. Coordinates are written as column, row for plotting. The script requests PDF output through Gnuplot/PostScript utilities, but this routine does not execute those programs. An uninitialized object produces no files.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• header [character(len=*)] – Prefix for coordinate data and Gnuplot command files.

function  sf_sparse_csr_d/sp_matmul_vector_csr_d(h, v)

Return \(H v\) as an allocated vector of length H%Nrow. The input length must be H%Ncol and H must be initialized. No complex conjugation is applied. Available as matmul(H,v) and H%dot(v).

Parameters:

• h [real] – Initialized sparse matrix.

• v (•) [real, in]

Result:

hv (•) [real, allocatable] – Returned product vector with the length specified above.

function  sf_sparse_csr_d/sp_transpose_matrix_csr_d(a)

Return the transpose with shape [A%Ncol,A%Nrow] and the same storage type. Values are not conjugated. A count-allocate-fill pass constructs sorted output indices. Available as transpose(A), A%transpose(), and A%t().

Parameters:

a [real] – tranpose

Result:

c [sparse_dmatrix_csr] – Returned result; its physical shape and semantics are specified above.

function  sf_sparse_csr_d/sp_hconjg_matrix_csr_d(a)

Return the Hermitian conjugate with shape [A%Ncol,A%Nrow]. Complex values are conjugated; for real matrices this is the ordinary transpose. The count-allocate-fill construction preserves sorted output indices. Available as hconjg(A) and A%dgr().

Parameters:

a [real] – tranpose

Result:

c [sparse_dmatrix_csr] – Returned result; its physical shape and semantics are specified above.

function  sf_sparse_csr_d/sp_eye_csr_d(ndim)

Construct an initialized sparse identity of size ndim in this concrete type. The diagonal is assembled directly without a dense temporary. The dimension must be nonnegative. Use the explicitly named identity constructor to select orientation and numerical type.

Parameters:

ndim [integer, in] – Nonnegative number of identity rows and columns.

Result:

self [sparse_dmatrix_csr] – Constructed sparse object, including dimensions, storage, and entry count.

subroutine  sf_sparse_csr_d/sp_bcast_matrix_csr_d(self[, comm, root])

Collectively broadcast a complete local sparse matrix from root. Defaults are MPI_COMM_WORLD and root zero. The root is a rank in the supplied communicator. Dimensions, stored entries, cached count, and initialization status are copied; existing receiver contents are replaced. An initialized empty matrix remains distinct from an uninitialized object.

Every participant must hold the same concrete dynamic type, including when calling through class(sparse_matrix). This binding does not allocate or change the dynamic type of the receiver. MPI must already be initialized.

Parameters:

self [real] – Sparse object or constructed result, including inherited metadata.

Options:

• comm [integer, in] – MPI communicator; broadcast defaults to MPI_COMM_WORLD.

• root [integer, in] – Source rank within comm; default zero.

function  sf_sparse_csr_d/sp_get_bytes_matrix_csr_d(self)

Estimate the local stored payload in decimal kilobytes (\(1\,kB=1000\) bytes). Includes parent metadata, row/column size integers, stored indices, and numerical values. Excludes allocatable descriptors, allocation overhead, and padding. Available as A%bytes() with or without MPI; no collective is performed.

Parameters:

self [real] – Constructed sparse object, including dimensions, storage, and entry count.

Result:

kbytes [real] – Estimated local payload in decimal kilobytes.

CSR: double complex

Description

Concrete implementation of sparse_zmatrix_csr, extending the common sparse_matrix parent. Import SF_SPARSE for the combined public API.

Warning

NEW column indices MUST increase strictly within each stored row. insert accumulates existing coordinates; fast_insert requires unique coordinates. Neither operation sorts indices or reorders values.

Dimensions and coordinates are physical row/column counts and one-based indices. Matrices are local objects. Optional MPI collectives transfer complete objects.

Quick access

Types:

sparse_row, sparse_zmatrix_csr

Routines:

allgather_mpi(), as_csr(), as_matrix(), as_sparse(), assignment(=)(), hconjg(), kron(), matmul(), operator(*)(), operator(.m.)(), operator(.x.)(), operator(/)(), sp_as_matrix_csr_z(), sp_bcast_matrix_csr_z(), sp_conjg_matrix_csr_z(), sp_copy_matrix_csr_z(), sp_display_matrix_csr_z(), sp_dump_matrix_csr_z(), sp_eye_csr_z(), sp_fast_insert_element_csr_z(), sp_free_matrix_csr_z(), sp_get_bytes_matrix_csr_z(), sp_get_element_csr_z(), sp_hconjg_matrix_csr_z(), sp_init_matrix_csr_z(), sp_insert_element_csr_z(), sp_load_matrix_csr_z(), sp_matmul_vector_csr_z(), sp_nnz_matrix_csr_z(), sp_read_matrix_csr_z(), sp_show_matrix_csr_z(), sp_spy_matrix_csr_z(), sp_transpose_matrix_csr_z(), sp_write_matrix_csr_z(), sparse(), sparse_zmatrix_csr(), transpose()

Used modules

• sf_sparse_common: Common sparse-matrix parent, metadata, and storage helpers

  • sparse_matrix

  • shape()

  • append()

  • binary_search()

• sf_iotools: SciFortran module for reading and writing data

  • str()

  • free_unit()

• sf_misc: SciFortran module for sundry functions

  • assert_shape()

• sf_mpi: SciFortran MPI interface

External modules

• mpi

Types

type  sf_sparse_csr_z/sparse_row

One dynamic sparse row. Indices are strictly increasing and values have matching length.

Type fields:

• size [integer] – Stored-entry count, including exact zeros.

• cols (•) [integer, allocatable] – One-based column indices, strictly increasing.

• vals (•) [complex, allocatable] – Values in the same order as the indices.

type  sf_sparse_csr_z/sparse_zmatrix_csr

Double complex local sparse matrix with inherited metadata and lifecycle interface. Each stored row holds increasing column indices and matching values. The inherited Nelements cache is maintained by library operations; direct storage edits must also maintain sizes, ordering, and this cache. Use class(sparse_matrix) for value-independent polymorphic operations.

Type fields:

• row (•) [sparse_row, allocatable] – Concrete sparse row storage; never distributed across MPI ranks.

Subroutines and functions

interface  sf_sparse_csr_z/sparse_zmatrix_csr(matrix)

Dense-array constructor for sparse_zmatrix_csr.

Parameters:

matrix (•, •) [complex, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_zmatrix_csr] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csr_z/as_csr(matrix)

Construct this CSR numerical type from a dense array with as_csr(matrix).

Parameters:

matrix (•, •) [complex, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_zmatrix_csr] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csr_z/as_sparse(matrix)

Dense-to-sparse constructor alias available when importing one storage orientation.

Parameters:

matrix (•, •) [complex, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_zmatrix_csr] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csr_z/as_matrix(sparse)

Return the physical dense representation of a sparse object.

Parameters:

sparse [real]

Result:

matrix (sparse%nrow, sparse%ncol) [complex] – Dense array with physical row/column shape, or returned dense representation.

interface  sf_sparse_csr_z/sparse(matrix)

Dense-to-sparse constructor alias available when importing one storage orientation.

Parameters:

matrix (•, •) [complex, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_zmatrix_csr] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csr_z/assignment(=)(a, c)

Scalar assignment changes stored values only. Matrix-to-matrix copying uses intrinsic assignment.

Parameters:

• a [sparse_zmatrix_csr, inout] – First sparse operand or source matrix.

• c [complex, in] – Scalar value; a divisor must be nonzero.

interface  sf_sparse_csr_z/operator(*)(c, a)

Multiply stored values by an integer, real, or supported complex scalar.

Parameters:

• c [integer/real/complex, in] – Scalar value; a divisor must be nonzero.

• a [sparse_zmatrix_csr, in]

Result:

b [sparse_zmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_z/operator(/)(a, c)

Divide stored values by a nonzero integer, real, or supported complex scalar.

Parameters:

• a [sparse_zmatrix_csr, in] – First sparse operand or source matrix.

• c [integer/real/complex, in]

Result:

b [sparse_zmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_z/operator(.m.)(a, b)

Ordinary sparse matrix multiplication, equivalent to matmul(A,B).

Parameters:

• a [sparse_zmatrix_csr, in]

• b [sparse_zmatrix_csr, in]

Result:

axb [sparse_zmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_z/operator(.x.)(a, b)

Kronecker product, equivalent to kron(A,B).

Parameters:

• a [sparse_zmatrix_csr, in]

• b [sparse_zmatrix_csr, in]

Result:

c [sparse_zmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_z/kron(a, b)

Kronecker product preserving orientation and numerical type.

Parameters:

• a [sparse_zmatrix_csr, in]

• b [sparse_zmatrix_csr, in]

Result:

c [sparse_zmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_z/transpose(a)

Transpose without conjugating values; the output keeps the input storage orientation.

Parameters:

a [real] – tranpose

Result:

c [sparse_zmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_z/hconjg(a)

Hermitian conjugate; equivalent to ordinary transpose for real values.

Parameters:

a [real] – tranpose

Result:

c [sparse_zmatrix_csr] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csr_z/matmul(a, b, h, v, vector, matrix)

Ordinary sparse matrix-matrix, matrix-vector, and vector-matrix products. Complex inputs are not conjugated.

Parameters:

• a [sparse_zmatrix_csr, in]

• b [sparse_zmatrix_csr, in]

• h [real] – Initialized sparse matrix.

• v (•) [complex, in]

• vector (•) [complex, in] – Input left vector; its length must match the matrix row count.

• matrix [integer] – Dense array with physical row/column shape, or returned dense representation.

Result:

• axb [sparse_zmatrix_csr] – Returned result; its physical shape and semantics are specified above.

• hv (•) [complex, allocatable] – Returned product vector with the length specified above.

interface  sf_sparse_csr_z/allgather_mpi(comm, a)

Collectively replicate rank-one or rank-two arrays of whole matrices from unique owners.

Parameters:

• comm [integer, in] – MPI communicator; broadcast defaults to MPI_COMM_WORLD.

• a [external] – Rank-one or rank-two array of matrices; initialization marks unique ownership.

subroutine  sf_sparse_csr_z/sp_init_matrix_csr_z(sparse, nrow[, ncol])

Initialize an empty local matrix through A%init(Nrow,Ncol). The optional second dimension defaults to Nrow. Existing storage is released. Dimensions must be nonnegative; all row/column arrays start empty.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• nrow [integer, in] – Physical number of rows; must be nonnegative.

Options:

ncol [integer, in] – Physical number of columns; defaults to Nrow.

subroutine  sf_sparse_csr_z/sp_copy_matrix_csr_z(sparse, b)

Deep-copy b into sparse, including dimensions and status. An uninitialized source leaves the destination uninitialized. Numerical arrays are copied independently. Ordinary matrix assignment also performs a deep copy.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• b [sparse_zmatrix_csr, in] – Second sparse operand or source matrix.

subroutine  sf_sparse_csr_z/sp_free_matrix_csr_z(sparse)

Release all concrete sparse storage and reset dimensions, entry count, and status. Safe for fresh objects and repeated calls. Overrides the common parent binding.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

subroutine  sf_sparse_csr_z/sp_load_matrix_csr_z(sparse, matrix)

Replace this object by the sparse representation of matrix. The physical shape is preserved and exact zeros are omitted. The construction order satisfies the sorted-index contract without requiring a caller-side sort.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• matrix (•, •) [complex, in] – Dense array with physical row/column ordering.

subroutine  sf_sparse_csr_z/sp_dump_matrix_csr_z(sparse, matrix)

Write the dense representation into an existing array of matching shape. The destination is cleared first: this operation replaces its contents rather than accumulating into them. The sparse object is unchanged.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• matrix (•, •) [complex, inout] – Dense array with physical row/column ordering.

function  sf_sparse_csr_z/sp_as_matrix_csr_z(sparse)

Return a dense rank-two array with physical shape [Nrow,Ncol]. Absent coordinates are zero. Available as A%as_matrix() and as_matrix(A). An uninitialized object has the default zero-by-zero shape.

Parameters:

sparse [real]

Result:

matrix (sparse%nrow, sparse%ncol) [complex] – Dense array with physical row/column shape, or returned dense representation.

subroutine  sf_sparse_csr_z/sp_insert_element_csr_z(sparse, value, i, j)

Add value to a physical matrix coordinate, called as A%insert(value,row,column). Existing coordinates are accumulated.

Warning

NEW indices MUST be appended in strictly increasing order within each stored row (CSR) or column (CSC). This routine does not sort indices or reorder values. Revisiting an existing coordinate preserves the ordering.

The matrix must be initialized and the physical coordinate must be in bounds. Exact zero values remain stored and contribute to nnz() / Nelements.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• value [complex, in] – Value to accumulate (insert) or append (fast_insert).

• i [integer, in] – check if column already exist

• j [integer, in] – Physical coordinate arguments; call with row, column.

subroutine  sf_sparse_csr_z/sp_fast_insert_element_csr_z(sparse, value, i, j)

Append a value at a physical coordinate through A%fast_insert(value,row,column), without searching for an existing entry.

Warning

The caller MUST guarantee unique coordinates and strictly increasing indices within each stored CSR row or CSC column. No sorting or duplicate accumulation is performed.

The object must be initialized and the coordinate must be in bounds.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• value [complex, in] – Value to accumulate (insert) or append (fast_insert).

• i [integer, in]

• j [integer, in] – Physical coordinate arguments; call with row, column.

function  sf_sparse_csr_z/sp_get_element_csr_z(sparse, i, j)

Return the value at a physical coordinate through A%get(row,column). An absent coordinate returns exact zero. The object must be initialized, the coordinate must be in bounds, and stored indices must satisfy the ordering contract.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• i [integer, in]

• j [integer, in]

Result:

val [complex] – Value at the requested physical coordinate; zero when absent.

function  sf_sparse_csr_z/sp_nnz_matrix_csr_z(sparse)

Count stored entries from the concrete row/column sizes. Exact zeros are counted. Uninitialized objects return zero. This storage-based count is independent of the inherited cache Nelements.

Parameters:

sparse [real]

Result:

nnz [integer] – Number of stored entries, including exact zeros.

subroutine  sf_sparse_csr_z/sp_show_matrix_csr_z(sparse[, fmt, file])

Print the dense matrix in physical row/column order. The default edit descriptor is ES16.8; fmt may supply another real edit descriptor, also used for each component of complex values. Output goes to unit 6 unless file is supplied. An uninitialized object produces no output. The object is unchanged.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

Options:

• fmt [character(len=*), in]

• file [character(len=*), in]

subroutine  sf_sparse_csr_z/sp_display_matrix_csr_z(sparse)

Print stored physical row indices, column indices, and values to standard output. Absent coordinates are not printed. An uninitialized object produces no output.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

subroutine  sf_sparse_csr_z/sp_write_matrix_csr_z(sparse[, file, unit])

Serialize an initialized matrix as formatted dimensions and index/value records. Supply exactly one of file or unit. A named file is replaced and closed by this routine; a caller-owned unit remains open. The payload is orientation-specific and must be read with the same storage and numerical type.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

Options:

• file [character(len=*)] – File name; owned and closed by this routine.

• unit [integer] – Caller-owned formatted unit, left open on return.

subroutine  sf_sparse_csr_z/sp_read_matrix_csr_z(sparse[, file, unit])

Replace this object by a matrix read from formatted dimensions and index/value records. Supply exactly one of file or unit. A named file must exist and is closed after reading; a caller-owned unit remains open. Stored sizes and index bounds are checked, and indices must be strictly increasing within each record. Use the same orientation and numerical type as the writer.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

Options:

• file [character(len=*)] – File name; owned and closed by this routine.

• unit [integer] – Caller-owned formatted unit, left open on return.

subroutine  sf_sparse_csr_z/sp_spy_matrix_csr_z(sparse, header)

Write stored coordinates to header_data.dat and plotting instructions to plot_header_commands.gp. Coordinates are written as column, row for plotting. The script requests PDF output through Gnuplot/PostScript utilities, but this routine does not execute those programs. An uninitialized object produces no files.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• header [character(len=*)] – Prefix for coordinate data and Gnuplot command files.

function  sf_sparse_csr_z/sp_matmul_vector_csr_z(h, v)

Return \(H v\) as an allocated vector of length H%Nrow. The input length must be H%Ncol and H must be initialized. No complex conjugation is applied. Available as matmul(H,v) and H%dot(v).

Parameters:

• h [real] – Initialized sparse matrix.

• v (•) [complex, in]

Result:

hv (•) [complex, allocatable] – Returned product vector with the length specified above.

function  sf_sparse_csr_z/sp_transpose_matrix_csr_z(a)

Return the transpose with shape [A%Ncol,A%Nrow] and the same storage type. Values are not conjugated. A count-allocate-fill pass constructs sorted output indices. Available as transpose(A), A%transpose(), and A%t().

Parameters:

a [real] – tranpose

Result:

c [sparse_zmatrix_csr] – Returned result; its physical shape and semantics are specified above.

function  sf_sparse_csr_z/sp_hconjg_matrix_csr_z(a)

Return the Hermitian conjugate with shape [A%Ncol,A%Nrow]. Complex values are conjugated; for real matrices this is the ordinary transpose. The count-allocate-fill construction preserves sorted output indices. Available as hconjg(A) and A%dgr().

Parameters:

a [real] – tranpose

Result:

c [sparse_zmatrix_csr] – Returned result; its physical shape and semantics are specified above.

function  sf_sparse_csr_z/sp_eye_csr_z(ndim)

Construct an initialized sparse identity of size ndim in this concrete type. The diagonal is assembled directly without a dense temporary. The dimension must be nonnegative. Use the explicitly named identity constructor to select orientation and numerical type.

Parameters:

ndim [integer, in] – Nonnegative number of identity rows and columns.

Result:

self [sparse_zmatrix_csr] – Constructed sparse object, including dimensions, storage, and entry count.

subroutine  sf_sparse_csr_z/sp_bcast_matrix_csr_z(self[, comm, root])

Collectively broadcast a complete local sparse matrix from root. Defaults are MPI_COMM_WORLD and root zero. The root is a rank in the supplied communicator. Dimensions, stored entries, cached count, and initialization status are copied; existing receiver contents are replaced. An initialized empty matrix remains distinct from an uninitialized object.

Every participant must hold the same concrete dynamic type, including when calling through class(sparse_matrix). This binding does not allocate or change the dynamic type of the receiver. MPI must already be initialized.

Parameters:

self [real] – Sparse object or constructed result, including inherited metadata.

Options:

• comm [integer, in] – MPI communicator; broadcast defaults to MPI_COMM_WORLD.

• root [integer, in] – Source rank within comm; default zero.

function  sf_sparse_csr_z/sp_get_bytes_matrix_csr_z(self)

Estimate the local stored payload in decimal kilobytes (\(1\,kB=1000\) bytes). Includes parent metadata, row/column size integers, stored indices, and numerical values. Excludes allocatable descriptors, allocation overhead, and padding. Available as A%bytes() with or without MPI; no collective is performed.

Parameters:

self [real] – Constructed sparse object, including dimensions, storage, and entry count.

Result:

kbytes [real] – Estimated local payload in decimal kilobytes.

function  sf_sparse_csr_z/sp_conjg_matrix_csr_z(a)

Return an elementwise complex conjugate, preserving physical shape and sparsity. This operation does not transpose the matrix. Available as A%conjg().

Parameters:

a [real]

Result:

c [sparse_zmatrix_csr] – Returned result; its physical shape and semantics are specified above.

CSC: double real

Description

Concrete implementation of sparse_dmatrix_csc, extending the common sparse_matrix parent. Import SF_SPARSE for the combined public API.

Warning

NEW row indices MUST increase strictly within each stored column. insert accumulates existing coordinates; fast_insert requires unique coordinates. Neither operation sorts indices or reorders values.

Dimensions and coordinates are physical row/column counts and one-based indices. Matrices are local objects. Optional MPI collectives transfer complete objects.

Quick access

Types:

sparse_col, sparse_dmatrix_csc

Routines:

allgather_mpi(), as_csc(), as_matrix(), as_sparse(), assignment(=)(), hconjg(), kron(), matmul(), operator(*)(), operator(.m.)(), operator(.x.)(), operator(/)(), sp_as_matrix_csc_d(), sp_bcast_matrix_csc_d(), sp_copy_matrix_csc_d(), sp_display_matrix_csc_d(), sp_dump_matrix_csc_d(), sp_eye_csc_d(), sp_fast_insert_element_csc_d(), sp_free_matrix_csc_d(), sp_get_bytes_matrix_csc_d(), sp_get_element_csc_d(), sp_hconjg_matrix_csc_d(), sp_init_matrix_csc_d(), sp_insert_element_csc_d(), sp_load_matrix_csc_d(), sp_matmul_vector_csc_d(), sp_nnz_matrix_csc_d(), sp_read_matrix_csc_d(), sp_show_matrix_csc_d(), sp_spy_matrix_csc_d(), sp_transpose_matrix_csc_d(), sp_write_matrix_csc_d(), sparse(), sparse_dmatrix_csc(), transpose()

Used modules

• sf_sparse_common: Common sparse-matrix parent, metadata, and storage helpers

  • sparse_matrix

  • shape()

  • append()

  • binary_search()

• sf_iotools: SciFortran module for reading and writing data

  • str()

  • free_unit()

• sf_misc: SciFortran module for sundry functions

  • assert_shape()

• sf_mpi: SciFortran MPI interface

External modules

• mpi

Types

type  sf_sparse_csc_d/sparse_col

One dynamic sparse column. Indices are strictly increasing and values have matching length.

Type fields:

• size [integer]

• rows (•) [integer, allocatable]

• vals (•) [real, allocatable]

type  sf_sparse_csc_d/sparse_dmatrix_csc

Double real local sparse matrix with inherited metadata and lifecycle interface. Each stored column holds increasing row indices and matching values. The inherited Nelements cache is maintained by library operations; direct storage edits must also maintain sizes, ordering, and this cache. Use class(sparse_matrix) for value-independent polymorphic operations.

Type fields:

• col (•) [sparse_col, allocatable] – Concrete sparse column storage; never distributed across MPI ranks.

Subroutines and functions

interface  sf_sparse_csc_d/sparse_dmatrix_csc(matrix)

Dense-array constructor for sparse_dmatrix_csc.

Parameters:

matrix (•, •) [real, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_dmatrix_csc] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csc_d/as_csc(matrix)

Construct this CSC numerical type from a dense array with as_csc(matrix).

Parameters:

matrix (•, •) [real, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_dmatrix_csc] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csc_d/as_sparse(matrix)

Dense-to-sparse constructor alias available when importing one storage orientation.

Parameters:

matrix (•, •) [real, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_dmatrix_csc] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csc_d/as_matrix(sparse)

Return the physical dense representation of a sparse object.

Parameters:

sparse [real]

Result:

matrix (sparse%nrow, sparse%ncol) [real] – Dense array with physical row/column shape, or returned dense representation.

interface  sf_sparse_csc_d/sparse(matrix)

Dense-to-sparse constructor alias available when importing one storage orientation.

Parameters:

matrix (•, •) [real, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_dmatrix_csc] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csc_d/assignment(=)(a, c)

Scalar assignment changes stored values only. Matrix-to-matrix copying uses intrinsic assignment.

Parameters:

• a [sparse_dmatrix_csc, inout] – First sparse operand or source matrix.

• c [real, in] – Scalar value; a divisor must be nonzero.

interface  sf_sparse_csc_d/operator(*)(c, a)

Multiply stored values by an integer, real, or supported complex scalar.

Parameters:

• c [integer/real, in] – Scalar value; a divisor must be nonzero.

• a [sparse_dmatrix_csc, in]

Result:

b [sparse_dmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_d/operator(/)(a, c)

Divide stored values by a nonzero integer, real, or supported complex scalar.

Parameters:

• a [sparse_dmatrix_csc, in] – First sparse operand or source matrix.

• c [integer/real, in]

Result:

b [sparse_dmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_d/operator(.m.)(a, b)

Ordinary sparse matrix multiplication, equivalent to matmul(A,B).

Parameters:

• a [sparse_dmatrix_csc, in]

• b [sparse_dmatrix_csc, in]

Result:

axb [sparse_dmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_d/operator(.x.)(a, b)

Kronecker product, equivalent to kron(A,B).

Parameters:

• a [sparse_dmatrix_csc, in]

• b [sparse_dmatrix_csc, in]

Result:

c [sparse_dmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_d/kron(a, b)

Kronecker product preserving orientation and numerical type.

Parameters:

• a [sparse_dmatrix_csc, in]

• b [sparse_dmatrix_csc, in]

Result:

c [sparse_dmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_d/transpose(a)

Transpose without conjugating values; the output keeps the input storage orientation.

Parameters:

a [real] – tranpose

Result:

c [sparse_dmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_d/hconjg(a)

Hermitian conjugate; equivalent to ordinary transpose for real values.

Parameters:

a [real] – tranpose

Result:

c [sparse_dmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_d/matmul(a, b, h, v, vector, matrix)

Ordinary sparse matrix-matrix, matrix-vector, and vector-matrix products. Complex inputs are not conjugated.

Parameters:

• a [sparse_dmatrix_csc, in]

• b [sparse_dmatrix_csc, in]

• h [real] – Initialized sparse matrix.

• v (•) [real, in]

• vector (•) [real, in] – Input left vector; its length must match the matrix row count.

• matrix [integer] – Dense array with physical row/column shape, or returned dense representation.

Result:

• axb [sparse_dmatrix_csc] – Returned result; its physical shape and semantics are specified above.

• hv (•) [real, allocatable] – Returned product vector with the length specified above.

interface  sf_sparse_csc_d/allgather_mpi(comm, a)

Collectively replicate rank-one or rank-two arrays of whole matrices from unique owners.

Parameters:

• comm [integer, in] – MPI communicator; broadcast defaults to MPI_COMM_WORLD.

• a [external] – Rank-one or rank-two array of matrices; initialization marks unique ownership.

subroutine  sf_sparse_csc_d/sp_init_matrix_csc_d(sparse, nrow[, ncol])

Initialize an empty local matrix through A%init(Nrow,Ncol). The optional second dimension defaults to Nrow. Existing storage is released. Dimensions must be nonnegative; all row/column arrays start empty.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• nrow [integer, in] – Physical number of rows; must be nonnegative.

Options:

ncol [integer, in] – Physical number of columns; defaults to Nrow.

subroutine  sf_sparse_csc_d/sp_copy_matrix_csc_d(sparse, b)

Deep-copy b into sparse, including dimensions and status. An uninitialized source leaves the destination uninitialized. Numerical arrays are copied independently. Ordinary matrix assignment also performs a deep copy.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• b [sparse_dmatrix_csc, in] – Second sparse operand or source matrix.

subroutine  sf_sparse_csc_d/sp_free_matrix_csc_d(sparse)

Release all concrete sparse storage and reset dimensions, entry count, and status. Safe for fresh objects and repeated calls. Overrides the common parent binding.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

subroutine  sf_sparse_csc_d/sp_load_matrix_csc_d(sparse, matrix)

Replace this object by the sparse representation of matrix. The physical shape is preserved and exact zeros are omitted. The construction order satisfies the sorted-index contract without requiring a caller-side sort.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• matrix (•, •) [real, in] – Dense array with physical row/column ordering.

subroutine  sf_sparse_csc_d/sp_dump_matrix_csc_d(sparse, matrix)

Write the dense representation into an existing array of matching shape. The destination is cleared first: this operation replaces its contents rather than accumulating into them. The sparse object is unchanged.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• matrix (•, •) [real, inout] – Dense array with physical row/column ordering.

function  sf_sparse_csc_d/sp_as_matrix_csc_d(sparse)

Return a dense rank-two array with physical shape [Nrow,Ncol]. Absent coordinates are zero. Available as A%as_matrix() and as_matrix(A). An uninitialized object has the default zero-by-zero shape.

Parameters:

sparse [real]

Result:

matrix (sparse%nrow, sparse%ncol) [real] – Dense array with physical row/column shape, or returned dense representation.

subroutine  sf_sparse_csc_d/sp_insert_element_csc_d(sparse, value, j, i)

Add value to a physical matrix coordinate, called as A%insert(value,row,column). Existing coordinates are accumulated.

Warning

NEW indices MUST be appended in strictly increasing order within each stored row (CSR) or column (CSC). This routine does not sort indices or reorder values. Revisiting an existing coordinate preserves the ordering.

The matrix must be initialized and the physical coordinate must be in bounds. Exact zero values remain stored and contribute to nnz() / Nelements.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• value [real, in] – Value to accumulate (insert) or append (fast_insert).

• j [integer, in] – i is the physical column; j is the physical row. Call order is (j,i).

• i [integer, in] – check if column already exist

subroutine  sf_sparse_csc_d/sp_fast_insert_element_csc_d(sparse, value, j, i)

Append a value at a physical coordinate through A%fast_insert(value,row,column), without searching for an existing entry.

Warning

The caller MUST guarantee unique coordinates and strictly increasing indices within each stored CSR row or CSC column. No sorting or duplicate accumulation is performed.

The object must be initialized and the coordinate must be in bounds.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• value [real, in] – Value to accumulate (insert) or append (fast_insert).

• j [integer, in] – i is the physical column; j is the physical row. Call order is (j,i).

• i [integer, in]

function  sf_sparse_csc_d/sp_get_element_csc_d(sparse, j, i)

Return the value at a physical coordinate through A%get(row,column). An absent coordinate returns exact zero. The object must be initialized, the coordinate must be in bounds, and stored indices must satisfy the ordering contract.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• j [integer, in]

• i [integer, in]

Result:

val [real] – Value at the requested physical coordinate; zero when absent.

function  sf_sparse_csc_d/sp_nnz_matrix_csc_d(sparse)

Count stored entries from the concrete row/column sizes. Exact zeros are counted. Uninitialized objects return zero. This storage-based count is independent of the inherited cache Nelements.

Parameters:

sparse [real]

Result:

nnz [integer] – Number of stored entries, including exact zeros.

subroutine  sf_sparse_csc_d/sp_show_matrix_csc_d(sparse[, fmt, file])

Print the dense matrix in physical row/column order. The default edit descriptor is ES16.8; fmt may supply another real edit descriptor, also used for each component of complex values. Output goes to unit 6 unless file is supplied. An uninitialized object produces no output. The object is unchanged.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

Options:

• fmt [character(len=*), in]

• file [character(len=*), in]

subroutine  sf_sparse_csc_d/sp_display_matrix_csc_d(sparse)

Print stored physical row indices, column indices, and values to standard output. Absent coordinates are not printed. An uninitialized object produces no output.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

subroutine  sf_sparse_csc_d/sp_write_matrix_csc_d(sparse[, file, unit])

Serialize an initialized matrix as formatted dimensions and index/value records. Supply exactly one of file or unit. A named file is replaced and closed by this routine; a caller-owned unit remains open. The payload is orientation-specific and must be read with the same storage and numerical type.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

Options:

• file [character(len=*)] – File name; owned and closed by this routine.

• unit [integer] – Caller-owned formatted unit, left open on return.

subroutine  sf_sparse_csc_d/sp_read_matrix_csc_d(sparse[, file, unit])

Replace this object by a matrix read from formatted dimensions and index/value records. Supply exactly one of file or unit. A named file must exist and is closed after reading; a caller-owned unit remains open. Stored sizes and index bounds are checked, and indices must be strictly increasing within each record. Use the same orientation and numerical type as the writer.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

Options:

• file [character(len=*)] – File name; owned and closed by this routine.

• unit [integer] – Caller-owned formatted unit, left open on return.

subroutine  sf_sparse_csc_d/sp_spy_matrix_csc_d(sparse, header)

Write stored coordinates to header_data.dat and plotting instructions to plot_header_commands.gp. Coordinates are written as column, row for plotting. The script requests PDF output through Gnuplot/PostScript utilities, but this routine does not execute those programs. An uninitialized object produces no files.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• header [character(len=*)] – Prefix for coordinate data and Gnuplot command files.

function  sf_sparse_csc_d/sp_matmul_vector_csc_d(h, v)

Return \(H v\) as an allocated vector of length H%Nrow. The input length must be H%Ncol and H must be initialized. No complex conjugation is applied. Available as matmul(H,v) and H%dot(v).

Parameters:

• h [real] – Initialized sparse matrix.

• v (•) [real, in]

Result:

hv (•) [real, allocatable] – Returned product vector with the length specified above.

function  sf_sparse_csc_d/sp_transpose_matrix_csc_d(a)

Return the transpose with shape [A%Ncol,A%Nrow] and the same storage type. Values are not conjugated. A count-allocate-fill pass constructs sorted output indices. Available as transpose(A), A%transpose(), and A%t().

Parameters:

a [real] – tranpose

Result:

c [sparse_dmatrix_csc] – Returned result; its physical shape and semantics are specified above.

function  sf_sparse_csc_d/sp_hconjg_matrix_csc_d(a)

Return the Hermitian conjugate with shape [A%Ncol,A%Nrow]. Complex values are conjugated; for real matrices this is the ordinary transpose. The count-allocate-fill construction preserves sorted output indices. Available as hconjg(A) and A%dgr().

Parameters:

a [real] – tranpose

Result:

c [sparse_dmatrix_csc] – Returned result; its physical shape and semantics are specified above.

function  sf_sparse_csc_d/sp_eye_csc_d(ndim)

Construct an initialized sparse identity of size ndim in this concrete type. The diagonal is assembled directly without a dense temporary. The dimension must be nonnegative. Use the explicitly named identity constructor to select orientation and numerical type.

Parameters:

ndim [integer, in] – Nonnegative number of identity rows and columns.

Result:

self [sparse_dmatrix_csc] – Constructed sparse object, including dimensions, storage, and entry count.

subroutine  sf_sparse_csc_d/sp_bcast_matrix_csc_d(self[, comm, root])

Collectively broadcast a complete local sparse matrix from root. Defaults are MPI_COMM_WORLD and root zero. The root is a rank in the supplied communicator. Dimensions, stored entries, cached count, and initialization status are copied; existing receiver contents are replaced. An initialized empty matrix remains distinct from an uninitialized object.

Every participant must hold the same concrete dynamic type, including when calling through class(sparse_matrix). This binding does not allocate or change the dynamic type of the receiver. MPI must already be initialized.

Parameters:

self [real] – Sparse object or constructed result, including inherited metadata.

Options:

• comm [integer, in] – MPI communicator; broadcast defaults to MPI_COMM_WORLD.

• root [integer, in] – Source rank within comm; default zero.

function  sf_sparse_csc_d/sp_get_bytes_matrix_csc_d(self)

Estimate the local stored payload in decimal kilobytes (\(1\,kB=1000\) bytes). Includes parent metadata, row/column size integers, stored indices, and numerical values. Excludes allocatable descriptors, allocation overhead, and padding. Available as A%bytes() with or without MPI; no collective is performed.

Parameters:

self [real] – Constructed sparse object, including dimensions, storage, and entry count.

Result:

kbytes [real] – Estimated local payload in decimal kilobytes.

CSC: double complex

Description

Concrete implementation of sparse_zmatrix_csc, extending the common sparse_matrix parent. Import SF_SPARSE for the combined public API.

Warning

NEW row indices MUST increase strictly within each stored column. insert accumulates existing coordinates; fast_insert requires unique coordinates. Neither operation sorts indices or reorders values.

Dimensions and coordinates are physical row/column counts and one-based indices. Matrices are local objects. Optional MPI collectives transfer complete objects.

Quick access

Types:

sparse_col, sparse_zmatrix_csc

Routines:

allgather_mpi(), as_csc(), as_matrix(), as_sparse(), assignment(=)(), hconjg(), kron(), matmul(), operator(*)(), operator(.m.)(), operator(.x.)(), operator(/)(), sp_as_matrix_csc_z(), sp_bcast_matrix_csc_z(), sp_conjg_matrix_csc_z(), sp_copy_matrix_csc_z(), sp_display_matrix_csc_z(), sp_dump_matrix_csc_z(), sp_eye_csc_z(), sp_fast_insert_element_csc_z(), sp_free_matrix_csc_z(), sp_get_bytes_matrix_csc_z(), sp_get_element_csc_z(), sp_hconjg_matrix_csc_z(), sp_init_matrix_csc_z(), sp_insert_element_csc_z(), sp_load_matrix_csc_z(), sp_matmul_vector_csc_z(), sp_nnz_matrix_csc_z(), sp_read_matrix_csc_z(), sp_show_matrix_csc_z(), sp_spy_matrix_csc_z(), sp_transpose_matrix_csc_z(), sp_write_matrix_csc_z(), sparse(), sparse_zmatrix_csc(), transpose()

Used modules

• sf_sparse_common: Common sparse-matrix parent, metadata, and storage helpers

  • sparse_matrix

  • shape()

  • append()

  • binary_search()

• sf_iotools: SciFortran module for reading and writing data

  • str()

  • free_unit()

• sf_misc: SciFortran module for sundry functions

  • assert_shape()

• sf_mpi: SciFortran MPI interface

External modules

• mpi

Types

type  sf_sparse_csc_z/sparse_col

One dynamic sparse column. Indices are strictly increasing and values have matching length.

Type fields:

• size [integer] – Stored-entry count, including exact zeros.

• rows (•) [integer, allocatable] – One-based row indices, strictly increasing.

• vals (•) [complex, allocatable] – Values in the same order as the indices.

type  sf_sparse_csc_z/sparse_zmatrix_csc

Double complex local sparse matrix with inherited metadata and lifecycle interface. Each stored column holds increasing row indices and matching values. The inherited Nelements cache is maintained by library operations; direct storage edits must also maintain sizes, ordering, and this cache. Use class(sparse_matrix) for value-independent polymorphic operations.

Type fields:

• col (•) [sparse_col, allocatable] – Concrete sparse column storage; never distributed across MPI ranks.

Subroutines and functions

interface  sf_sparse_csc_z/sparse_zmatrix_csc(matrix)

Dense-array constructor for sparse_zmatrix_csc.

Parameters:

matrix (•, •) [complex, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_zmatrix_csc] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csc_z/as_csc(matrix)

Construct this CSC numerical type from a dense array with as_csc(matrix).

Parameters:

matrix (•, •) [complex, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_zmatrix_csc] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csc_z/as_sparse(matrix)

Dense-to-sparse constructor alias available when importing one storage orientation.

Parameters:

matrix (•, •) [complex, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_zmatrix_csc] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csc_z/as_matrix(sparse)

Return the physical dense representation of a sparse object.

Parameters:

sparse [real]

Result:

matrix (sparse%nrow, sparse%ncol) [complex] – Dense array with physical row/column shape, or returned dense representation.

interface  sf_sparse_csc_z/sparse(matrix)

Dense-to-sparse constructor alias available when importing one storage orientation.

Parameters:

matrix (•, •) [complex, in] – Dense array with physical row/column shape, or returned dense representation.

Result:

self [sparse_zmatrix_csc] – Constructed sparse object, including dimensions, storage, and entry count.

interface  sf_sparse_csc_z/assignment(=)(a, c)

Scalar assignment changes stored values only. Matrix-to-matrix copying uses intrinsic assignment.

Parameters:

• a [sparse_zmatrix_csc, inout] – First sparse operand or source matrix.

• c [complex, in] – Scalar value; a divisor must be nonzero.

interface  sf_sparse_csc_z/operator(*)(c, a)

Multiply stored values by an integer, real, or supported complex scalar.

Parameters:

• c [integer/real/complex, in] – Scalar value; a divisor must be nonzero.

• a [sparse_zmatrix_csc, in]

Result:

b [sparse_zmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_z/operator(/)(a, c)

Divide stored values by a nonzero integer, real, or supported complex scalar.

Parameters:

• a [sparse_zmatrix_csc, in] – First sparse operand or source matrix.

• c [integer/real/complex, in]

Result:

b [sparse_zmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_z/operator(.m.)(a, b)

Ordinary sparse matrix multiplication, equivalent to matmul(A,B).

Parameters:

• a [sparse_zmatrix_csc, in]

• b [sparse_zmatrix_csc, in]

Result:

axb [sparse_zmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_z/operator(.x.)(a, b)

Kronecker product, equivalent to kron(A,B).

Parameters:

• a [sparse_zmatrix_csc, in]

• b [sparse_zmatrix_csc, in]

Result:

c [sparse_zmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_z/kron(a, b)

Kronecker product preserving orientation and numerical type.

Parameters:

• a [sparse_zmatrix_csc, in]

• b [sparse_zmatrix_csc, in]

Result:

c [sparse_zmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_z/transpose(a)

Transpose without conjugating values; the output keeps the input storage orientation.

Parameters:

a [real] – tranpose

Result:

c [sparse_zmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_z/hconjg(a)

Hermitian conjugate; equivalent to ordinary transpose for real values.

Parameters:

a [real] – tranpose

Result:

c [sparse_zmatrix_csc] – Returned result; its physical shape and semantics are specified above.

interface  sf_sparse_csc_z/matmul(a, b, h, v, vector, matrix)

Ordinary sparse matrix-matrix, matrix-vector, and vector-matrix products. Complex inputs are not conjugated.

Parameters:

• a [sparse_zmatrix_csc, in]

• b [sparse_zmatrix_csc, in]

• h [real] – Initialized sparse matrix.

• v (•) [complex, in]

• vector (•) [complex, in] – Input left vector; its length must match the matrix row count.

• matrix [integer] – Dense array with physical row/column shape, or returned dense representation.

Result:

• axb [sparse_zmatrix_csc] – Returned result; its physical shape and semantics are specified above.

• hv (•) [complex, allocatable] – Returned product vector with the length specified above.

interface  sf_sparse_csc_z/allgather_mpi(comm, a)

Collectively replicate rank-one or rank-two arrays of whole matrices from unique owners.

Parameters:

• comm [integer, in] – MPI communicator; broadcast defaults to MPI_COMM_WORLD.

• a [external] – Rank-one or rank-two array of matrices; initialization marks unique ownership.

subroutine  sf_sparse_csc_z/sp_init_matrix_csc_z(sparse, nrow[, ncol])

Initialize an empty local matrix through A%init(Nrow,Ncol). The optional second dimension defaults to Nrow. Existing storage is released. Dimensions must be nonnegative; all row/column arrays start empty.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• nrow [integer, in] – Physical number of rows; must be nonnegative.

Options:

ncol [integer, in] – Physical number of columns; defaults to Nrow.

subroutine  sf_sparse_csc_z/sp_copy_matrix_csc_z(sparse, b)

Deep-copy b into sparse, including dimensions and status. An uninitialized source leaves the destination uninitialized. Numerical arrays are copied independently. Ordinary matrix assignment also performs a deep copy.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• b [sparse_zmatrix_csc, in] – Second sparse operand or source matrix.

subroutine  sf_sparse_csc_z/sp_free_matrix_csc_z(sparse)

Release all concrete sparse storage and reset dimensions, entry count, and status. Safe for fresh objects and repeated calls. Overrides the common parent binding.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

subroutine  sf_sparse_csc_z/sp_load_matrix_csc_z(sparse, matrix)

Replace this object by the sparse representation of matrix. The physical shape is preserved and exact zeros are omitted. The construction order satisfies the sorted-index contract without requiring a caller-side sort.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• matrix (•, •) [complex, in] – Dense array with physical row/column ordering.

subroutine  sf_sparse_csc_z/sp_dump_matrix_csc_z(sparse, matrix)

Write the dense representation into an existing array of matching shape. The destination is cleared first: this operation replaces its contents rather than accumulating into them. The sparse object is unchanged.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• matrix (•, •) [complex, inout] – Dense array with physical row/column ordering.

function  sf_sparse_csc_z/sp_as_matrix_csc_z(sparse)

Return a dense rank-two array with physical shape [Nrow,Ncol]. Absent coordinates are zero. Available as A%as_matrix() and as_matrix(A). An uninitialized object has the default zero-by-zero shape.

Parameters:

sparse [real]

Result:

matrix (sparse%nrow, sparse%ncol) [complex] – Dense array with physical row/column shape, or returned dense representation.

subroutine  sf_sparse_csc_z/sp_insert_element_csc_z(sparse, value, j, i)

Add value to a physical matrix coordinate, called as A%insert(value,row,column). Existing coordinates are accumulated.

Warning

NEW indices MUST be appended in strictly increasing order within each stored row (CSR) or column (CSC). This routine does not sort indices or reorder values. Revisiting an existing coordinate preserves the ordering.

The matrix must be initialized and the physical coordinate must be in bounds. Exact zero values remain stored and contribute to nnz() / Nelements.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• value [complex, in] – Value to accumulate (insert) or append (fast_insert).

• j [integer, in] – i is the physical column; j is the physical row. Call order is (j,i).

• i [integer, in] – check if column already exist

subroutine  sf_sparse_csc_z/sp_fast_insert_element_csc_z(sparse, value, j, i)

Append a value at a physical coordinate through A%fast_insert(value,row,column), without searching for an existing entry.

Warning

The caller MUST guarantee unique coordinates and strictly increasing indices within each stored CSR row or CSC column. No sorting or duplicate accumulation is performed.

The object must be initialized and the coordinate must be in bounds.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• value [complex, in] – Value to accumulate (insert) or append (fast_insert).

• j [integer, in] – i is the physical column; j is the physical row. Call order is (j,i).

• i [integer, in]

function  sf_sparse_csc_z/sp_get_element_csc_z(sparse, j, i)

Return the value at a physical coordinate through A%get(row,column). An absent coordinate returns exact zero. The object must be initialized, the coordinate must be in bounds, and stored indices must satisfy the ordering contract.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• j [integer, in]

• i [integer, in]

Result:

val [complex] – Value at the requested physical coordinate; zero when absent.

function  sf_sparse_csc_z/sp_nnz_matrix_csc_z(sparse)

Count stored entries from the concrete row/column sizes. Exact zeros are counted. Uninitialized objects return zero. This storage-based count is independent of the inherited cache Nelements.

Parameters:

sparse [real]

Result:

nnz [integer] – Number of stored entries, including exact zeros.

subroutine  sf_sparse_csc_z/sp_show_matrix_csc_z(sparse[, fmt, file])

Print the dense matrix in physical row/column order. The default edit descriptor is ES16.8; fmt may supply another real edit descriptor, also used for each component of complex values. Output goes to unit 6 unless file is supplied. An uninitialized object produces no output. The object is unchanged.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

Options:

• fmt [character(len=*), in]

• file [character(len=*), in]

subroutine  sf_sparse_csc_z/sp_display_matrix_csc_z(sparse)

Print stored physical row indices, column indices, and values to standard output. Absent coordinates are not printed. An uninitialized object produces no output.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

subroutine  sf_sparse_csc_z/sp_write_matrix_csc_z(sparse[, file, unit])

Serialize an initialized matrix as formatted dimensions and index/value records. Supply exactly one of file or unit. A named file is replaced and closed by this routine; a caller-owned unit remains open. The payload is orientation-specific and must be read with the same storage and numerical type.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

Options:

• file [character(len=*)] – File name; owned and closed by this routine.

• unit [integer] – Caller-owned formatted unit, left open on return.

subroutine  sf_sparse_csc_z/sp_read_matrix_csc_z(sparse[, file, unit])

Replace this object by a matrix read from formatted dimensions and index/value records. Supply exactly one of file or unit. A named file must exist and is closed after reading; a caller-owned unit remains open. Stored sizes and index bounds are checked, and indices must be strictly increasing within each record. Use the same orientation and numerical type as the writer.

Parameters:

sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

Options:

• file [character(len=*)] – File name; owned and closed by this routine.

• unit [integer] – Caller-owned formatted unit, left open on return.

subroutine  sf_sparse_csc_z/sp_spy_matrix_csc_z(sparse, header)

Write stored coordinates to header_data.dat and plotting instructions to plot_header_commands.gp. Coordinates are written as column, row for plotting. The script requests PDF output through Gnuplot/PostScript utilities, but this routine does not execute those programs. An uninitialized object produces no files.

Parameters:

• sparse [real] – Sparse object; concrete storage belongs to this MPI rank.

• header [character(len=*)] – Prefix for coordinate data and Gnuplot command files.

function  sf_sparse_csc_z/sp_matmul_vector_csc_z(h, v)

Return \(H v\) as an allocated vector of length H%Nrow. The input length must be H%Ncol and H must be initialized. No complex conjugation is applied. Available as matmul(H,v) and H%dot(v).

Parameters:

• h [real] – Initialized sparse matrix.

• v (•) [complex, in]

Result:

hv (•) [complex, allocatable] – Returned product vector with the length specified above.

function  sf_sparse_csc_z/sp_transpose_matrix_csc_z(a)

Return the transpose with shape [A%Ncol,A%Nrow] and the same storage type. Values are not conjugated. A count-allocate-fill pass constructs sorted output indices. Available as transpose(A), A%transpose(), and A%t().

Parameters:

a [real] – tranpose

Result:

c [sparse_zmatrix_csc] – Returned result; its physical shape and semantics are specified above.

function  sf_sparse_csc_z/sp_hconjg_matrix_csc_z(a)

Return the Hermitian conjugate with shape [A%Ncol,A%Nrow]. Complex values are conjugated; for real matrices this is the ordinary transpose. The count-allocate-fill construction preserves sorted output indices. Available as hconjg(A) and A%dgr().

Parameters:

a [real] – tranpose

Result:

c [sparse_zmatrix_csc] – Returned result; its physical shape and semantics are specified above.

function  sf_sparse_csc_z/sp_eye_csc_z(ndim)

Construct an initialized sparse identity of size ndim in this concrete type. The diagonal is assembled directly without a dense temporary. The dimension must be nonnegative. Use the explicitly named identity constructor to select orientation and numerical type.

Parameters:

ndim [integer, in] – Nonnegative number of identity rows and columns.

Result:

self [sparse_zmatrix_csc] – Constructed sparse object, including dimensions, storage, and entry count.

subroutine  sf_sparse_csc_z/sp_bcast_matrix_csc_z(self[, comm, root])

Collectively broadcast a complete local sparse matrix from root. Defaults are MPI_COMM_WORLD and root zero. The root is a rank in the supplied communicator. Dimensions, stored entries, cached count, and initialization status are copied; existing receiver contents are replaced. An initialized empty matrix remains distinct from an uninitialized object.

Every participant must hold the same concrete dynamic type, including when calling through class(sparse_matrix). This binding does not allocate or change the dynamic type of the receiver. MPI must already be initialized.

Parameters:

self [real] – Sparse object or constructed result, including inherited metadata.

Options:

• comm [integer, in] – MPI communicator; broadcast defaults to MPI_COMM_WORLD.

• root [integer, in] – Source rank within comm; default zero.

function  sf_sparse_csc_z/sp_get_bytes_matrix_csc_z(self)

Estimate the local stored payload in decimal kilobytes (\(1\,kB=1000\) bytes). Includes parent metadata, row/column size integers, stored indices, and numerical values. Excludes allocatable descriptors, allocation overhead, and padding. Available as A%bytes() with or without MPI; no collective is performed.

Parameters:

self [real] – Constructed sparse object, including dimensions, storage, and entry count.

Result:

kbytes [real] – Estimated local payload in decimal kilobytes.

function  sf_sparse_csc_z/sp_conjg_matrix_csc_z(a)

Return an elementwise complex conjugate, preserving physical shape and sparsity. This operation does not transpose the matrix. Available as A%conjg().

Parameters:

a [real]

Result:

c [sparse_zmatrix_csc] – Returned result; its physical shape and semantics are specified above.