Deprecate assemble!(A, ij, a) in favor of assemble!(A, i, j, a). (#6)

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Deprecated
+ - The method `HYPRE.assemble!(A::HYPREMatrixAssembler, ij::Vector, a::Matrix)` have been
+   deprecated in favor of `HYPRE.assemble!(A::HYPREMatrixAssembler, i::Vector, j::Vector,
+   a::Matrix)`, i.e. it is now required to explicitly pass rows and column indices
+   individually. The motivation behind this is to support assembling of rectangular
+   matrices. Note that `HYPRE.assemble!(A::HYPREAssembler, ij::Vector, a::Matrix,
+   b::Vector)` is still supported, where `ij` are used as row and column indices for `a`, as
+   well as row indices for `b`. ([#6][github-6])
 
 ## [1.2.0] - 2022-10-12
 ### Added
@@ -23,8 +31,9 @@ Initial release of HYPRE.jl.
 
 [github-2]: https://github.com/fredrikekre/HYPRE.jl/pull/2
 [github-5]: https://github.com/fredrikekre/HYPRE.jl/pull/5
+[github-6]: https://github.com/fredrikekre/HYPRE.jl/pull/6
 
-[1.0.0]: ttps://github.com/fredrikekre/HYPRE.jl/releases/tag/v1.0.0
+[1.0.0]: https://github.com/fredrikekre/HYPRE.jl/releases/tag/v1.0.0
 [1.1.0]: https://github.com/fredrikekre/HYPRE.jl/compare/v1.0.0...v1.1.0
 [1.2.0]: https://github.com/fredrikekre/HYPRE.jl/compare/v1.1.0...v1.2.0
 [Unreleased]: https://github.com/fredrikekre/HYPRE.jl/compare/v1.2.0...HEAD

src/HYPRE.jl

@@ -592,31 +592,32 @@ function start_assemble!(A::HYPREMatrix, b::HYPREVector)
 end
 
 """
-    HYPRE.assemble!(A::HYPREMatrixAssembler, ij, a::Matrix)
-    HYPRE.assemble!(A::HYPREVectorAssembler, ij, b::Vector)
-    HYPRE.assemble!(A::HYPREAssembler,       ij, a::Matrix, b::Vector)
+    HYPRE.assemble!(A::HYPREMatrixAssembler, i, j, a::Matrix)
+    HYPRE.assemble!(A::HYPREVectorAssembler, i,    b::Vector)
+    HYPRE.assemble!(A::HYPREAssembler,       ij,   a::Matrix, b::Vector)
 
 Assemble (by adding) matrix contribution `a`, vector contribution `b`, into the underlying
-array(s) of the assembler at global row and column indices `ij`.
+array(s) of the assembler at global row indices `i` and column indices `j`.
 
 This is roughly equivalent to:
 ```julia
 # A.A::HYPREMatrix
-A.A[ij, ij] += a
+A.A[i, j] += a
 
 # A.b::HYPREVector
-A.b[ij] += b
+A.b[i] += b
 ```
 
 See also: [`HYPRE.start_assemble!`](@ref), [`HYPRE.finish_assemble!`](@ref).
 """
 assemble!
 
-function assemble!(A::HYPREMatrixAssembler, ij::Vector, a::Matrix)
-    nrows, ncols, rows, cols, values = Internals.to_hypre_data(A, a, ij, ij)
+function assemble!(A::HYPREMatrixAssembler, i::Vector, j::Vector, a::Matrix)
+    nrows, ncols, rows, cols, values = Internals.to_hypre_data(A, a, i, j)
     @check HYPRE_IJMatrixAddToValues(A.A.ijmatrix, nrows, ncols, rows, cols, values)
     return A
 end
+@deprecate assemble!(A::HYPREMatrixAssembler, ij::Vector, a::Matrix) assemble!(A, ij, ij, a) false
 
 function assemble!(A::HYPREVectorAssembler, ij::Vector, a::Vector)
     nvalues, indices, values = Internals.to_hypre_data(A, a, ij)
@@ -625,7 +626,7 @@ function assemble!(A::HYPREVectorAssembler, ij::Vector, a::Vector)
 end
 
 function assemble!(A::HYPREAssembler, ij::Vector, a::Matrix, b::Vector)
-    assemble!(A.A, ij, a)
+    assemble!(A.A, ij, ij, a)
     assemble!(A.b, ij, b)
     return A
 end

test/runtests.jl

@@ -308,7 +308,7 @@ end
         fill!(AM, 0)
         for idx in ([1, 2], [3, 1])
             a = rand(2, 2)
-            HYPRE.assemble!(assembler, idx, a)
+            HYPRE.assemble!(assembler, idx, idx, a)
             AM[idx, idx] += a
         end
         f = HYPRE.finish_assemble!(assembler)

test/test_assembler.jl

@@ -51,7 +51,7 @@ for i in 1:2
     fill!(AM, 0)
     for n in N
         idx, a, _ = values_and_indices(n)
-        HYPRE.assemble!(assembler, idx, a)
+        HYPRE.assemble!(assembler, idx, idx, a)
         AM[idx, idx] += a
     end
     f = HYPRE.finish_assemble!(assembler)