Skip to content

Commit 1e84dc2

Browse files
Add README for RecursiveArrayToolsRaggedArrays subpackage
Follows the same structure as the other subpackage READMEs. Covers RaggedVectorOfArray/RaggedDiffEqArray construction, indexing, RaggedEnd usage, and comparison table with VectorOfArray. Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent dea54ac commit 1e84dc2

File tree

1 file changed

+74
-0
lines changed

1 file changed

+74
-0
lines changed
Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# RecursiveArrayToolsRaggedArrays.jl
2+
3+
True ragged (non-rectangular) array types for
4+
[RecursiveArrayTools.jl](https://github.com/SciML/RecursiveArrayTools.jl).
5+
6+
This subpackage provides `RaggedVectorOfArray` and `RaggedDiffEqArray`, which
7+
preserve the exact ragged structure of collections of differently-sized arrays
8+
without zero-padding. Unlike the main package's `VectorOfArray` (which presents
9+
ragged data as a zero-padded rectangular `AbstractArray`), these types do **not**
10+
subtype `AbstractArray` — indexing returns only actual stored data.
11+
12+
It is separated from the main package because the ragged indexing methods
13+
(including `end` support via `RaggedEnd`/`RaggedRange`) would cause method
14+
invalidations on the hot path for rectangular `VectorOfArray` operations.
15+
16+
## Installation
17+
18+
```julia
19+
using Pkg
20+
Pkg.add(url = "https://github.com/SciML/RecursiveArrayTools.jl",
21+
subdir = "lib/RecursiveArrayToolsRaggedArrays")
22+
```
23+
24+
## Usage
25+
26+
```julia
27+
using RecursiveArrayToolsRaggedArrays
28+
29+
# Inner arrays can have different sizes
30+
A = RaggedVectorOfArray([[1, 2, 3], [4, 5, 6, 7], [8, 9]])
31+
32+
A.u[1] # [1, 2, 3] — first inner array
33+
A.u[2] # [4, 5, 6, 7] — second inner array
34+
A[:, 2] # [4, 5, 6, 7] — same as A.u[2]
35+
A[2, 2] # 5 — second element of second array
36+
37+
# end resolves per-column via RaggedEnd
38+
A[end, 1] # 3 — last of first array (length 3)
39+
A[end, 2] # 7 — last of second array (length 4)
40+
A[end, 3] # 9 — last of third array (length 2)
41+
A[end-1:end, 2] # [6, 7] — last two elements of second array
42+
43+
# Convert to dense (when inner arrays have the same size)
44+
B = RaggedVectorOfArray([[1, 2], [3, 4]])
45+
Array(B) # [1 3; 2 4]
46+
```
47+
48+
### `RaggedDiffEqArray`
49+
50+
`RaggedDiffEqArray` adds time, parameter, and symbolic system fields for
51+
differential equation solutions where the state dimension varies over time:
52+
53+
```julia
54+
t = 0.0:0.1:1.0
55+
vals = [[sin(ti), cos(ti)] for ti in t]
56+
A = RaggedDiffEqArray(vals, collect(t))
57+
58+
A.t # time vector
59+
A.u # vector of solution arrays
60+
A[1, :] # first component across all times
61+
```
62+
63+
## Comparison with `VectorOfArray`
64+
65+
| | `VectorOfArray` (main package) | `RaggedVectorOfArray` (this package) |
66+
|-|-------------------------------|--------------------------------------|
67+
| Subtypes `AbstractArray` | Yes | No |
68+
| Ragged handling | Zero-padded rectangular view | True ragged structure |
69+
| `end` on ragged dim | Resolves to max size | Resolves per-column (`RaggedEnd`) |
70+
| Linear algebra | Yes | No |
71+
| Broadcasting with plain arrays | Yes | No |
72+
73+
Use `VectorOfArray` when you need `AbstractArray` interop. Use
74+
`RaggedVectorOfArray` when you need exact ragged structure without implicit zeros.

0 commit comments

Comments
 (0)