Constructors refactor: undef, sparsezeros, sparserand and sparserand! (#33)

* Add `sprand` and `sprand!`

* Be a bit more mindful with constructors

* Add `spzeros`

* update `sprand` to take in `rfn` function

* update docstrings

* update README

* Bump v0.3.0

* Bump skeleton

* move functions

* export new functions

* slightly re-organize constructors

* update registrator action

* enable (some of) Aqua

* fix undefined export

* remove tested exports (included in aqua testset)

* update testfunction

* change `rfn` to `rand_function`

* Add `SparseArrayDOK` docstrings

* Revert "remove tested exports (included in aqua testset)"

This reverts commit e7053a8.

* update tested exports

* merge export lists

* change `rand_function` to `randfun`

* change `spzeros`, `sprand` and `sprand!` to `sparsezeros`, `sparserand` and `sparserand!`

* sort exports alphabetically

Author: lkdvos

.github/workflows/IntegrationTestRequest.yml

@@ -0,0 +1,14 @@
+name: "Integration Test Request"
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  integrationrequest:
+    if: |
+      github.event.issue.pull_request &&
+      contains(fromJSON('["OWNER", "COLLABORATOR", "MEMBER"]'), github.event.comment.author_association)
+    uses: ITensor/ITensorActions/.github/workflows/IntegrationTestRequest.yml@main
+    with:
+      localregistry: https://github.com/ITensor/ITensorRegistry.git

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 ITensor developers
+Copyright (c) 2025 ITensor developers
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Project.toml

@@ -1,7 +1,7 @@
 name = "SparseArraysBase"
 uuid = "0d5efcca-f356-4864-8770-e1ed8d78f208"
 authors = ["ITensor developers <[email protected]> and contributors"]
-version = "0.2.11"
+version = "0.3.0"
 
 [deps]
 Accessors = "7d9f7c33-5ae7-4f3b-8dc6-eff91059b697"
@@ -11,6 +11,7 @@ Dictionaries = "85a47980-9c8c-11e8-2b9f-f7ca1fa99fb4"
 FillArrays = "1a297f60-69ca-5386-bcde-b61e274b549b"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MapBroadcast = "ebd9b9da-f48d-417c-9660-449667d60261"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 
 [compat]
 Accessors = "0.1.41"
@@ -21,6 +22,7 @@ Dictionaries = "0.4.3"
 FillArrays = "1.13.0"
 LinearAlgebra = "1.10"
 MapBroadcast = "0.1.5"
+Random = "1.10.0"
 SafeTestsets = "0.1"
 Suppressor = "0.2"
 Test = "1.10"

README.md

@@ -48,7 +48,7 @@ using SparseArraysBase:
   zero!
 using Test: @test, @test_throws
 
-a = SparseArrayDOK{Float64}(2, 2)
+a = SparseArrayDOK{Float64}(undef, 2, 2)
 ````
 
 AbstractArray interface:
@@ -122,32 +122,32 @@ b = a[1:2, 2]
 @test b == [12, 0]
 @test storedlength(b) == 1
 
-a = SparseArrayDOK{Float64}(2, 2)
+a = SparseArrayDOK{Float64}(undef, 2, 2)
 a .= 2
 for I in eachindex(a)
   @test a[I] == 2
 end
 @test storedlength(a) == length(a)
 
-a = SparseArrayDOK{Float64}(2, 2)
+a = SparseArrayDOK{Float64}(undef, 2, 2)
 fill!(a, 2)
 for I in eachindex(a)
   @test a[I] == 2
 end
 @test storedlength(a) == length(a)
 
-a = SparseArrayDOK{Float64}(2, 2)
+a = SparseArrayDOK{Float64}(undef, 2, 2)
 fill!(a, 0)
 @test iszero(a)
 @test iszero(storedlength(a))
 
-a = SparseArrayDOK{Float64}(2, 2)
+a = SparseArrayDOK{Float64}(undef, 2, 2)
 a[1, 2] = 12
 zero!(a)
 @test iszero(a)
 @test iszero(storedlength(a))
 
-a = SparseArrayDOK{Float64}(2, 2)
+a = SparseArrayDOK{Float64}(undef, 2, 2)
 a[1, 2] = 12
 b = zero(a)
 @test iszero(b)

docs/make.jl

@@ -16,7 +16,7 @@ makedocs(;
     edit_link="main",
     assets=String[],
   ),
-  pages=["Home" => "index.md"],
+  pages=["Home" => "index.md", "Reference" => "reference.md"],
 )
 
 deploydocs(;

docs/src/reference.md

@@ -0,0 +1,5 @@
+# Reference
+
+```@autodocs
+Modules = [SparseArraysBase]
+```

examples/README.jl

@@ -53,7 +53,7 @@ using SparseArraysBase:
   zero!
 using Test: @test, @test_throws
 
-a = SparseArrayDOK{Float64}(2, 2)
+a = SparseArrayDOK{Float64}(undef, 2, 2)
 
 # AbstractArray interface:
 
@@ -118,32 +118,32 @@ b = a[1:2, 2]
 @test b == [12, 0]
 @test storedlength(b) == 1
 
-a = SparseArrayDOK{Float64}(2, 2)
+a = SparseArrayDOK{Float64}(undef, 2, 2)
 a .= 2
 for I in eachindex(a)
   @test a[I] == 2
 end
 @test storedlength(a) == length(a)
 
-a = SparseArrayDOK{Float64}(2, 2)
+a = SparseArrayDOK{Float64}(undef, 2, 2)
 fill!(a, 2)
 for I in eachindex(a)
   @test a[I] == 2
 end
 @test storedlength(a) == length(a)
 
-a = SparseArrayDOK{Float64}(2, 2)
+a = SparseArrayDOK{Float64}(undef, 2, 2)
 fill!(a, 0)
 @test iszero(a)
 @test iszero(storedlength(a))
 
-a = SparseArrayDOK{Float64}(2, 2)
+a = SparseArrayDOK{Float64}(undef, 2, 2)
 a[1, 2] = 12
 zero!(a)
 @test iszero(a)
 @test iszero(storedlength(a))
 
-a = SparseArrayDOK{Float64}(2, 2)
+a = SparseArrayDOK{Float64}(undef, 2, 2)
 a[1, 2] = 12
 b = zero(a)
 @test iszero(b)

src/SparseArraysBase.jl

@@ -8,7 +8,10 @@ export SparseArrayDOK,
   OneElementVector,
   eachstoredindex,
   isstored,
-  oneelementarray,
+  oneelement,
+  sparserand,
+  sparserand!,
+  sparsezeros,
   storedlength,
   storedpairs,
   storedvalues

src/abstractsparsearray.jl

@@ -53,3 +53,66 @@ function getunstoredindex(a::ReplacedUnstoredSparseArray, I::Int...)
 end
 eachstoredindex(a::ReplacedUnstoredSparseArray) = eachstoredindex(parent(a))
 @derive ReplacedUnstoredSparseArray AbstractArrayOps
+
+# Special-purpose constructors
+# ----------------------------
+using Random: Random, AbstractRNG, default_rng
+
+@doc """
+    sparsezeros([T::Type], dims) -> A::SparseArrayDOK{T}
+
+Create an empty size `dims` sparse array.
+The optional `T` argument specifies the element type, which defaults to `Float64`.
+""" sparsezeros
+
+sparsezeros(dims::Dims) = sparsezeros(Float64, dims)
+sparsezeros(::Type{T}, dims::Dims) where {T} = SparseArrayDOK{T}(undef, dims)
+
+@doc """
+    sparserand([rng], [T::Type], dims; density::Real=0.5, randfun::Function=rand) -> A::SparseArrayDOK{T}
+
+Create a random size `dims` sparse array in which the probability of any element being stored is independently given by `density`.
+The optional `rng` argument specifies a random number generator, see also `Random`.
+The optional `T` argument specifies the element type, which defaults to `Float64`.
+The optional `randfun` argument can be used to control the type of random elements, and should support
+the signature `randfun(rng, T, N)` to generate `N` entries of type `T`.
+
+
+See also [`sparserand!`](@ref).
+""" sparserand
+
+function sparserand(::Type{T}, dims::Dims; kwargs...) where {T}
+  return sparserand(default_rng(), T, dims; kwargs...)
+end
+sparserand(dims::Dims; kwargs...) = sparserand(default_rng(), Float64, dims; kwargs...)
+function sparserand(rng::AbstractRNG, dims::Dims; kwargs...)
+  return sparserand(rng, Float64, dims; kwargs...)
+end
+function sparserand(rng::AbstractRNG, ::Type{T}, dims::Dims; kwargs...) where {T}
+  A = SparseArrayDOK{T}(undef, dims)
+  sparserand!(rng, A; kwargs...)
+  return A
+end
+
+@doc """
+    sparserand!([rng], A::AbstractArray; density::Real=0.5, randfun::Function=rand) -> A
+
+Overwrite part of an array with random entries, where the probability of overwriting is independently given by `density`.
+The optional `rng` argument specifies a random number generator, see also `Random`.
+The optional `randfun` argument can be used to control the type of random elements, and should support
+the signature `randfun(rng, T, N)` to generate `N` entries of type `T`.
+
+See also [`sparserand`](@ref).
+""" sparserand!
+
+sparserand!(A::AbstractArray; kwargs...) = sparserand!(default_rng(), A; kwargs...)
+function sparserand!(
+  rng::AbstractRNG, A::AbstractArray; density::Real=0.5, randfun::Function=Random.rand
+)
+  ArrayLayouts.zero!(A)
+  rand_inds = Random.randsubseq(rng, eachindex(A), density)
+  rand_entries = randfun(rng, eltype(A), length(rand_inds))
+  @inbounds for (I, v) in zip(rand_inds, rand_entries)
+    A[I] = v
+  end
+end

src/abstractsparsearrayinterface.jl

@@ -200,7 +200,7 @@ end
   a::AbstractArray, T::Type, size::Tuple{Vararg{Int}}
 )
   # TODO: Define `default_similartype` or something like that?
-  return SparseArrayDOK{T}(size...)
+  return SparseArrayDOK{T}(undef, size)
 end
 
 # map over a specified subset of indices of the inputs.

src/sparsearraydok.jl

@@ -1,39 +1,111 @@
 using Accessors: @set
-using Dictionaries: Dictionary, IndexError, set!
+using Dictionaries: AbstractDictionary, Dictionary, IndexError, set!
 
 function default_getunstoredindex(a::AbstractArray, I::Int...)
   return zero(eltype(a))
 end
 
+const DOKStorage{T,N} = Dictionary{CartesianIndex{N},T}
+
+"""
+    SparseArrayDOK{T,N,F} <: AbstractSparseArray{T,N}
+
+`N`-dimensional sparse Dictionary-of-keys (DOK) array with elements of type `T`,
+optionally with a function of type `F` to instantiate non-stored elements.
+"""
 struct SparseArrayDOK{T,N,F} <: AbstractSparseArray{T,N}
-  storage::Dictionary{CartesianIndex{N},T}
+  storage::DOKStorage{T,N}
   size::NTuple{N,Int}
   getunstoredindex::F
-end
 
-function set_getunstoredindex(a::SparseArrayDOK, f)
-  @set a.getunstoredindex = f
-  return a
+  # bare constructor
+  function SparseArrayDOK{T,N,F}(
+    ::UndefInitializer, size::Dims{N}, getunstoredindex::F
+  ) where {T,N,F}
+    storage = DOKStorage{T,N}()
+    return new{T,N,F}(storage, size, getunstoredindex)
+  end
+
+  # unchecked constructor from data
+  function SparseArrayDOK{T,N,F}(
+    storage::DOKStorage{T,N}, size::Dims{N}, getunstoredindex::F
+  ) where {T,N,F}
+    return new{T,N,F}(storage, size, getunstoredindex)
+  end
 end
 
-using DerivableInterfaces: DerivableInterfaces
-# This defines the destination type of various operations in DerivableInterfaces.jl.
-DerivableInterfaces.arraytype(::AbstractSparseArrayInterface, T::Type) = SparseArrayDOK{T}
+# Constructors
+# ------------
+"""
+    SparseArrayDOK{T}(undef, dims, unstored...)
+    SparseArrayDOK{T}(undef, dims...)
+    SparseArrayDOK{T,N}(undef, dims, unstored...)
+    SparseArrayDOK{T,N}(undef, dims...)
 
-function SparseArrayDOK{T,N}(size::Vararg{Int,N}) where {T,N}
-  getunstoredindex = default_getunstoredindex
+Construct an uninitialized `N`-dimensional [`SparseArrayDOK`](@ref) containing
+elements of type `T`. `N` can either be supplied explicitly, or be determined by
+the length or number of `dims`.
+"""
+SparseArrayDOK{T,N}(::UndefInitializer, dims, unstored...)
+
+function SparseArrayDOK{T,N}(
+  ::UndefInitializer, dims::Dims, getunstoredindex=default_getunstoredindex
+) where {T,N}
+  (length(dims) == N && all(≥(0), dims)) ||
+    throw(ArgumentError("Invalid dimensions: $dims"))
   F = typeof(getunstoredindex)
-  return SparseArrayDOK{T,N,F}(Dictionary{CartesianIndex{N},T}(), size, getunstoredindex)
+  return SparseArrayDOK{T,N,F}(undef, dims, getunstoredindex)
+end
+function SparseArrayDOK{T}(::UndefInitializer, dims::Dims{N}, unstored...) where {T,N}
+  return SparseArrayDOK{T,N}(undef, dims, unstored...)
+end
+function SparseArrayDOK{T}(::UndefInitializer, dims::Vararg{Int,N}) where {T,N}
+  return SparseArrayDOK{T,N}(undef, dims)
 end
 
-function SparseArrayDOK{T}(::UndefInitializer, size::Tuple{Vararg{Int}}) where {T}
-  return SparseArrayDOK{T,length(size)}(size...)
+"""
+    SparseArrayDOK(storage::Union{AbstractDict,AbstractDictionary}, dims, unstored...)
+    SparseArrayDOK{T}(storage::Union{AbstractDict,AbstractDictionary}, dims, unstored...)
+    SparseArrayDOK{T,N}(storage::Union{AbstractDict,AbstractDictionary}, dims, unstored...)
+
+Construct an `N`-dimensional [`SparseArrayDOK`](@ref) containing elements of type `T`. Both
+`T` and `N` can either be supplied explicitly or be determined by the `storage` and the
+length or number of `dims`.
+
+This constructor does not take ownership of the supplied storage, and will result in an
+independent container.
+"""
+SparseArrayDOK{T,N}(::Union{AbstractDict,AbstractDictionary}, dims, unstored...)
+
+const AbstractDictOrDictionary = Union{AbstractDict,AbstractDictionary}
+# checked constructor from data: use `setindex!` to validate/convert input
+function SparseArrayDOK{T,N}(
+  storage::AbstractDictOrDictionary, dims::Dims, unstored...
+) where {T,N}
+  A = SparseArrayDOK{T,N}(undef, dims, unstored...)
+  for (i, v) in pairs(storage)
+    A[i] = v
+  end
+  return A
+end
+function SparseArrayDOK{T}(
+  storage::AbstractDictOrDictionary, dims::Dims, unstored...
+) where {T}
+  return SparseArrayDOK{T,length(dims)}(storage, dims, unstored...)
+end
+function SparseArrayDOK(storage::AbstractDictOrDictionary, dims::Dims, unstored...)
+  return SparseArrayDOK{valtype(storage)}(storage, dims, unstored...)
 end
 
-function SparseArrayDOK{T}(size::Int...) where {T}
-  return SparseArrayDOK{T,length(size)}(size...)
+function set_getunstoredindex(a::SparseArrayDOK, f)
+  @set a.getunstoredindex = f
+  return a
 end
 
+using DerivableInterfaces: DerivableInterfaces
+# This defines the destination type of various operations in DerivableInterfaces.jl.
+DerivableInterfaces.arraytype(::AbstractSparseArrayInterface, T::Type) = SparseArrayDOK{T}
+
 using DerivableInterfaces: @array_aliases
 # Define `SparseMatrixDOK`, `AnySparseArrayDOK`, etc.
 @array_aliases SparseArrayDOK

test/runtests.jl

@@ -24,9 +24,11 @@ isexamplefile(fn) =
   # tests in groups based on folder structure
   for testgroup in filter(isdir, readdir(@__DIR__))
     if GROUP == "ALL" || GROUP == uppercase(testgroup)
-      for file in filter(istestfile, readdir(joinpath(@__DIR__, testgroup); join=true))
+      groupdir = joinpath(@__DIR__, testgroup)
+      for file in filter(istestfile, readdir(groupdir))
+        filename = joinpath(groupdir, file)
         @eval @safetestset $file begin
-          include($file)
+          include($filename)
         end
       end
     end

test/test_aqua.jl

@@ -3,6 +3,5 @@ using Aqua: Aqua
 using Test: @testset
 
 @testset "Code quality (Aqua.jl)" begin
-  # TODO: Fix Aqua issues and add this back.
-  # Aqua.test_all(SparseArraysBase)
+  Aqua.test_all(SparseArraysBase; ambiguities=false)
 end