diff --git a/Project.toml b/Project.toml index d8895906..190c9c31 100644 --- a/Project.toml +++ b/Project.toml @@ -11,6 +11,7 @@ GPUArraysCore = "46192b85-c4d5-4398-a991-12ede77f4527" LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e" PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a" RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01" +SciMLPublic = "431bcebd-1456-4ced-9d72-93c2757fff0b" StaticArraysCore = "1e83bf80-4336-4d27-bf5d-d5a4f845583c" SymbolicIndexingInterface = "2efcf032-c050-4f8e-a9bb-153293bab1f5" @@ -69,6 +70,7 @@ RecipesBase = "1.3.4" RecursiveArrayToolsShorthandConstructors = "1" ReverseDiff = "1.15" SafeTestsets = "0.1" +SciMLPublic = "1" SciMLTesting = "2.1" SparseArrays = "1.10" StaticArrays = "1.6" @@ -98,6 +100,7 @@ SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf" StaticArrays = "90137ffa-7385-5640-81b9-e52037218182" Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2" StructArrays = "09ab397b-f2b6-538f-b94a-2f83cf4a842a" +Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c" Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d" diff --git a/src/RecursiveArrayTools.jl b/src/RecursiveArrayTools.jl index a86797c2..a3436cac 100644 --- a/src/RecursiveArrayTools.jl +++ b/src/RecursiveArrayTools.jl @@ -8,6 +8,7 @@ module RecursiveArrayTools using RecipesBase, StaticArraysCore, ArrayInterface, LinearAlgebra using SymbolicIndexingInterface + using SciMLPublic: @public import Adapt @@ -152,8 +153,18 @@ module RecursiveArrayTools returns actual stored data and `A[:, i]` gives the `i`-th inner array with its original size. - Concrete subtypes live in the `RecursiveArrayToolsRaggedArrays` subpackage - to avoid method invalidations on the hot path. + # Developer Interface + + Concrete subtypes must expose an indexable `u` collection containing the + stored inner arrays. They preserve each inner array's true shape and should + implement the ragged indexing, iteration, copying, and broadcasting behavior + documented by `RecursiveArrayToolsRaggedArrays`. They must not introduce + zero-padding or claim the rectangular `AbstractArray` interface. + + This is a developer API for packages implementing ragged array containers. + Concrete implementations belong in `RecursiveArrayToolsRaggedArrays` to + avoid method invalidations on the root package's hot path. Application code + should construct `RaggedVectorOfArray` rather than subtype this interface. """ abstract type AbstractRaggedVectorOfArray{T, N, A} end @@ -162,6 +173,14 @@ module RecursiveArrayTools Abstract supertype for ragged diff-eq arrays that carry a time vector `t`, parameters `p`, and symbolic system `sys` alongside ragged solution data. + + # Developer Interface + + Subtypes must satisfy the `AbstractRaggedVectorOfArray` contract and expose + `t`, `p`, and `sys` metadata compatible with `DiffEqArray`. The metadata must + remain aligned with the entries of `u` whenever the container is mutated. + Application code should construct `RaggedDiffEqArray` instead of subtyping + this interface. """ abstract type AbstractRaggedDiffEqArray{T, N, A} <: AbstractRaggedVectorOfArray{T, N, A} end @@ -196,6 +215,8 @@ module RecursiveArrayTools export ArrayPartition, AP, NamedArrayPartition + @public AbstractRaggedVectorOfArray, AbstractRaggedDiffEqArray + include("precompilation.jl") end # module diff --git a/test/Core/interface_tests.jl b/test/Core/interface_tests.jl index 694334fc..86ed840b 100644 --- a/test/Core/interface_tests.jl +++ b/test/Core/interface_tests.jl @@ -4,6 +4,15 @@ using FastBroadcast using Polyester using SymbolicIndexingInterface: SymbolCache +if isdefined(Base, :ispublic) + @testset "Ragged developer API declarations" begin + for name in (:AbstractRaggedVectorOfArray, :AbstractRaggedDiffEqArray) + @test Base.ispublic(RecursiveArrayTools, name) + @test Base.Docs.hasdoc(RecursiveArrayTools, name) + end + end +end + t = 1:3 testva = VA[[1, 2, 3], [4, 5, 6], [7, 8, 9]] testda = DiffEqArray([[1, 2, 3], [4, 5, 6], [7, 8, 9]], t)