diff --git a/Project.toml b/Project.toml index 5593f18..9143a0a 100644 --- a/Project.toml +++ b/Project.toml @@ -34,7 +34,7 @@ GPUArrays = "8.4, 9, 10, 11" JLArrays = "0.1, 0.2, 0.3" LinearAlgebra = "1" SafeTestsets = "0.0.1, 0.1, 1" -SciMLTesting = "1" +SciMLTesting = "2.1" SemiseparableMatrices = "0.4.0" SparseArrays = "1" SpecialMatrices = "3.1.0" diff --git a/docs/make.jl b/docs/make.jl index b14094f..831447a 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -10,6 +10,7 @@ makedocs( sitename = "SparseMatrixIdentification.jl", authors = "Anastasia Dunca", modules = [SparseMatrixIdentification], + checkdocs = :exports, clean = true, doctest = false, linkcheck = true, diff --git a/src/SparseMatrixIdentification.jl b/src/SparseMatrixIdentification.jl index 881143e..54a2b9e 100644 --- a/src/SparseMatrixIdentification.jl +++ b/src/SparseMatrixIdentification.jl @@ -341,23 +341,25 @@ export getstructure """ getstructure(A::AbstractMatrix) -Compute structure metrics for a matrix. +Compute the bandedness and sparsity metrics for `A`. -Returns a tuple `(percentage_banded, percentage_sparsity)` where: -- `percentage_banded`: The percentage of positions within bandwidth=1 that contain non-zero elements -- `percentage_sparsity`: The proportion of zero elements in the matrix (1 - density) +Returns `(percentage_banded, percentage_sparsity)`, where `percentage_banded` is +the percentage of entries in the bandwidth-1 band that are nonzero, and +`percentage_sparsity` is the fraction of entries in `A` that are zero. # Arguments -- `A::AbstractMatrix`: The input matrix to analyze +- `A`: matrix to analyze. # Returns -- `Tuple{Float64, Float64}`: A tuple of (bandedness percentage, sparsity percentage) +- `percentage_banded`: percentage of nonzero entries in the bandwidth-1 band. +- `percentage_sparsity`: fraction of zero entries in `A`. # Examples ```julia -julia> A = [1 2 0; 3 4 5; 0 6 7] -julia> getstructure(A) -(100.0, 0.2222222222222222) +using SparseMatrixIdentification + +A = [1 2 0; 3 4 5; 0 6 7] +getstructure(A) ``` """ function getstructure(A::AbstractMatrix)::Any @@ -391,40 +393,54 @@ const _fastalmostbandedmatrices_loaded = Ref(false) """ try_special_matrices(Ad, n, m) -Extension point for SpecialMatrices.jl. Returns nothing when SpecialMatrices is not loaded. -When SpecialMatrices is loaded, returns Hilbert, Strang, Vandermonde, or Cauchy if detected. +Extension hook used by the SpecialMatrices.jl integration. + +Extension methods return a `Hilbert`, `Strang`, `Vandermonde`, or `Cauchy` +matrix when `Ad` matches one of those structures, and `nothing` otherwise. +The base package defines only the generic function. """ function try_special_matrices end """ try_toeplitz(A) -Extension point for ToeplitzMatrices.jl. Returns nothing when ToeplitzMatrices is not loaded. -When ToeplitzMatrices is loaded, returns Toeplitz if detected. +Extension hook used by the ToeplitzMatrices.jl integration. + +Extension methods return a `Toeplitz` matrix when `A` has constant diagonals, +and `nothing` otherwise. The base package defines only the generic function. """ function try_toeplitz end """ try_blockbanded(Ad, n) -Extension point for BlockBandedMatrices.jl. Returns nothing when BlockBandedMatrices is not loaded. -When BlockBandedMatrices is loaded, returns BlockBandedMatrix if detected. +Extension hook used by the BlockBandedMatrices.jl integration. + +Extension methods return a `BlockBandedMatrix` when `Ad` has a detected +block-banded structure, and `nothing` otherwise. The base package defines only +the generic function. """ function try_blockbanded end """ try_almostbanded(Ad, n) -Extension point for FastAlmostBandedMatrices.jl. Returns nothing when FastAlmostBandedMatrices is not loaded. -When FastAlmostBandedMatrices is loaded, returns AlmostBandedMatrix if detected. +Extension hook used by the FastAlmostBandedMatrices.jl integration. + +Extension methods return an `AlmostBandedMatrix` when `Ad` is banded with +low-rank fill outside the band, and `nothing` otherwise. The base package +defines only the generic function. """ function try_almostbanded end """ try_banded(A, threshold) -Extension point for BandedMatrices.jl. Returns nothing when BandedMatrices is not loaded. -When BandedMatrices is loaded, returns BandedMatrix if detected. +Extension hook used by the BandedMatrices.jl integration. + +Extension methods return a `BandedMatrix` when nonzero entries in `A` are +confined to the `threshold` band, and `nothing` otherwise. The base package +defines only the generic function. """ function try_banded end @@ -470,12 +486,15 @@ One of the following matrix types based on detected structure: # Examples ```julia -julia> using SparseArrays -julia> A = sparse([1 2 2; 2 3 4; 2 4 5]) -julia> sparsestructure(A, 0.5) # Returns Symmetric +using LinearAlgebra +using SparseArrays +using SparseMatrixIdentification + +A = sparse([1 2 2; 2 3 4; 2 4 5]) +sparsestructure(A, 0.5) isa Symmetric -julia> L = sparse([1 0 0; 2 3 0; 4 5 6]) -julia> sparsestructure(L, 0.5) # Returns LowerTriangular +L = sparse([1 0 0; 2 3 0; 4 5 6]) +sparsestructure(L, 0.5) isa LowerTriangular ``` """ function sparsestructure(A::AbstractSparseMatrix, threshold) diff --git a/test/qa/Project.toml b/test/qa/Project.toml index b28b74f..b6a1719 100644 --- a/test/qa/Project.toml +++ b/test/qa/Project.toml @@ -5,12 +5,9 @@ SciMLTesting = "09d9d899-5365-40a9-917a-5f67fddea283" SparseMatrixIdentification = "2607229e-3272-44a7-bc4a-cd97a328dfbf" Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" -[sources] -SparseMatrixIdentification = {path = "../.."} - [compat] Aqua = "0.8" JET = "0.9,0.10,0.11" -SciMLTesting = "1.6" +SciMLTesting = "2.1" Test = "1" julia = "1.10" diff --git a/test/qa/qa.jl b/test/qa/qa.jl index 3121153..14af5fc 100644 --- a/test/qa/qa.jl +++ b/test/qa/qa.jl @@ -1,4 +1,4 @@ -using SciMLTesting, SparseMatrixIdentification, Test +using SciMLTesting, SparseMatrixIdentification using JET run_qa( @@ -9,4 +9,5 @@ run_qa( # ArrayInterface; it is the only non-public name this package accesses. all_qualified_accesses_are_public = (; ignore = (:fast_scalar_indexing,)), ), + api_docs_kwargs = (; rendered = true), )