From d6b3ece448c6a506856628e6cbb001432a5fb21c Mon Sep 17 00:00:00 2001 From: ChrisRackauckas-Claude Date: Wed, 1 Apr 2026 12:22:53 -0400 Subject: [PATCH 1/2] Add docs page for subpackages Document all three subpackages (ShorthandConstructors, ArrayPartitionAnyAll, RaggedArrays) on a single page with usage examples, motivation for the split, and installation instructions. Co-Authored-By: Chris Rackauckas Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/pages.jl | 1 + docs/src/subpackages.md | 102 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 103 insertions(+) create mode 100644 docs/src/subpackages.md diff --git a/docs/pages.jl b/docs/pages.jl index 173dd28d..7e59360f 100644 --- a/docs/pages.jl +++ b/docs/pages.jl @@ -6,6 +6,7 @@ pages = [ "AbstractVectorOfArrayInterface.md", "array_types.md", "ragged_arrays.md", + "subpackages.md", "plotting.md", "recursive_array_functions.md", ] diff --git a/docs/src/subpackages.md b/docs/src/subpackages.md new file mode 100644 index 00000000..b23c5569 --- /dev/null +++ b/docs/src/subpackages.md @@ -0,0 +1,102 @@ +# Subpackages + +RecursiveArrayTools.jl ships several optional subpackages under `lib/`. Each is a +separate Julia package that adds functionality which was split out of the main +package to avoid method invalidations that would increase load times for users who +don't need that functionality. + +## RecursiveArrayToolsRaggedArrays + +True ragged (non-rectangular) array types that preserve exact structure without +zero-padding. See the [Ragged Arrays](@ref) page for full documentation. + +```julia +using RecursiveArrayToolsRaggedArrays +``` + +## RecursiveArrayToolsShorthandConstructors + +Shorthand `VA[...]` and `AP[...]` constructor syntax for `VectorOfArray` and +`ArrayPartition`. + +This is separated from the main package because the `getindex(::Type, ...)` method +definitions invalidate compiled specializations of `Base.getindex(::Type{T}, vals...)` +from Base, increasing load times for downstream packages that don't need the syntax. + +```julia +using RecursiveArrayToolsShorthandConstructors +``` + +### Usage + +```julia +using RecursiveArrayTools +using RecursiveArrayToolsShorthandConstructors + +# VectorOfArray shorthand (equivalent to VectorOfArray([[1,2,3], [4,5,6]])) +u = VA[[1, 2, 3], [4, 5, 6], [7, 8, 9]] + +# ArrayPartition shorthand (equivalent to ArrayPartition(x0, v0, a0)) +x0, v0, a0 = rand(3, 3), rand(3, 3), rand(3, 3) +u0 = AP[x0, v0, a0] +u0.x[1] === x0 # true + +# Nesting works +nested = VA[fill(1, 2, 3), VA[3ones(3), zeros(3)]] +``` + +Without this package, use the equivalent explicit constructors: + +```julia +u = VectorOfArray([[1, 2, 3], [4, 5, 6], [7, 8, 9]]) +u0 = ArrayPartition(x0, v0, a0) +``` + +## RecursiveArrayToolsArrayPartitionAnyAll + +Optimized `any` and `all` for `ArrayPartition` that iterate partition-by-partition +instead of element-by-element, giving ~1.5-1.8x speedup on full scans. + +This is separated from the main package because `any(f::Function, ::ArrayPartition)` +invalidates ~780 compiled specializations of `any(f::Function, ::AbstractArray)`. + +```julia +using RecursiveArrayToolsArrayPartitionAnyAll +``` + +### Usage + +```julia +using RecursiveArrayTools +using RecursiveArrayToolsArrayPartitionAnyAll + +ap = ArrayPartition(rand(1000), rand(1000), rand(1000)) + +# These now use the optimized partition-by-partition iteration +any(isnan, ap) # ~1.5x faster than default +all(x -> x > 0, ap) # ~1.8x faster than default +``` + +Without this package, `any`/`all` use the default `AbstractArray` implementation +which is correct but slower due to per-element partition indexing overhead. + +### Why is it faster? + +`ArrayPartition` stores data as a tuple of arrays. The default `AbstractArray` +`any`/`all` iterates element-by-element, which requires computing which partition +each linear index falls into. The optimized methods iterate over each partition +array directly, avoiding that lookup overhead entirely. + +## Installation + +All subpackages can be installed from the monorepo: + +```julia +using Pkg +Pkg.add(url = "https://github.com/SciML/RecursiveArrayTools.jl", + subdir = "lib/RecursiveArrayToolsRaggedArrays") +Pkg.add(url = "https://github.com/SciML/RecursiveArrayTools.jl", + subdir = "lib/RecursiveArrayToolsShorthandConstructors") +Pkg.add(url = "https://github.com/SciML/RecursiveArrayTools.jl", + subdir = "lib/RecursiveArrayToolsArrayPartitionAnyAll") +``` From b375b850f872501092c042df8ae15f763f2f3fc5 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Wed, 1 Apr 2026 16:26:01 +0000 Subject: [PATCH 2/2] Apply suggestion from @ChrisRackauckas --- docs/src/subpackages.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/docs/src/subpackages.md b/docs/src/subpackages.md index b23c5569..33d18068 100644 --- a/docs/src/subpackages.md +++ b/docs/src/subpackages.md @@ -86,17 +86,3 @@ which is correct but slower due to per-element partition indexing overhead. `any`/`all` iterates element-by-element, which requires computing which partition each linear index falls into. The optimized methods iterate over each partition array directly, avoiding that lookup overhead entirely. - -## Installation - -All subpackages can be installed from the monorepo: - -```julia -using Pkg -Pkg.add(url = "https://github.com/SciML/RecursiveArrayTools.jl", - subdir = "lib/RecursiveArrayToolsRaggedArrays") -Pkg.add(url = "https://github.com/SciML/RecursiveArrayTools.jl", - subdir = "lib/RecursiveArrayToolsShorthandConstructors") -Pkg.add(url = "https://github.com/SciML/RecursiveArrayTools.jl", - subdir = "lib/RecursiveArrayToolsArrayPartitionAnyAll") -```