|
| 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