StructArrays.jl

A StructArray is an AbstractArray where elements are treated as structs (like NamedTuples, ComplexF64, or custom user-defined structs), but the underlying data is stored using a Structure-Of-Arrays (SOA) layout.

Instead of storing individual structs in a single array (Array-Of-Structs or AOS), StructArray maintains separate arrays for each field of the struct. The struct entries are constructed on-the-fly when accessed. This allows for efficient field-wise operations while providing a high-level interface where you can access fields using dot syntax or getproperty.

It is highly recommended to use immutable structs with StructArray whenever possible.

• Safety: With immutable structs, attempting to modify a field of a materialized element (e.g., soa[i].field = val) will result in a compile-time error rather than silent, transient behavior.
• Performance: The performance of immutable struct creation is generally much better than for mutable structs.

To iterate over the rows of a StructArray without materializing a full array of structures in memory, use the lazy iteration tools:

• LazyRow: Represents a single row as a lazy object.
• LazyRows: An iterator that yields LazyRow objects, allowing for efficient row-wise processing.

Because StructArray (in SOA mode) materializes struct elements on-the-fly, modifying a field of a retrieved element (e.g., soa[i].field = val) only modifies a temporary object that is immediately discarded.

To persist a change to a field in a mutable struct, you must retrieve the element, modify it, and then assign it back to the StructArray index.

# INCORRECT: This change is lost
soa[4].b = 9

# CORRECT: Retrieve, modify, and re-assign
x = soa[4]
x.b = 10
soa[4] = x

You can use StructArrays directly within CUDA kernels by moving the storage to the GPU. To do this, use replace_storage(CuArray, d) where d is your StructArray.

Workflow:

1. Create your StructArray on the CPU.
2. Use replace_storage(CuArray, d) to create a GPU-resident version (dd).
3. Create a destination array on the GPU using similar(dd).
4. Launch a standard CUDA kernel that operates on these arrays.

using CUDA, StructArrays

d = StructArray(a = rand(100), b = rand(100))

# move to GPU
dd = replace_storage(CuArray, d)
de = similar(dd)

# A simple kernel to copy content
function kernel!(dest, src)
    i = (blockIdx().x-1)*blockDim().x + threadIdx().x
    if i <= length(dest)
        dest[i] = src[i]
    end
    return nothing
end

threads = 1024
blocks = cld(length(dd), threads)

@cuda threads=threads blocks=blocks kernel!(de, dd)

Using broadcasted in-place assignment (e.g., x[i] .= val) on a StructArray entry may not work as expected. This is because the broadcast operation creates a new materialized struct first, and the in-place modification applies to that temporary object rather than the underlying storage of the StructArray.

To ensure the change is saved, assign the result of the broadcast back to the index: x[i] = x[i] .= val.

# This might fail to update the StructArray storage:
x[1] .= 1

# This works:
x[1] = x[1] .= 1

You can use StructArray to decompose complex numbers into their real (re) and imaginary (im) components. This can be done by specifying the target type ComplexF64 and providing a tuple of arrays representing the components, or by passing a standard array of complex numbers directly to the StructArray constructor.

Use StructArrays.components(s) to obtain all field arrays as a named tuple.

using StructArrays, Random

# Method 1: Decomposing components manually
Random.seed!(4);
s = StructArray{ComplexF64}((rand(2,2), rand(2,2)))
s.re # Access real part
s.im # Access imaginary part
StructArrays.components(s) # Returns (re = ..., im = ...)

# Method 2: Converting an existing array of complex numbers
StructArray([1+im, 3-2im])

StructArray is compatible with StaticArrays.jl types like SVector, SMatrix, and SArray. This allows you to create arrays of small, fixed-size structures that benefit from the performance of static dispatch while maintaining the StructArray interface.

using StructArrays, StaticArrays

# Array of SVector
x = StructArray([SVector{2}(1,2) for i = 1:5])

# Array of SMatrix
A = StructArray([SMatrix{2,2}([1 2;3 4]) for i = 1:5])

# Array of higher-dimensional SArray
B = StructArray([SArray{Tuple{2,2,2}}(reshape(1:8,2,2,2)) for i = 1:5])
B[1]

A StructArray can act as a data table by taking a collection of named tuples or a tuple of arrays with matching names. Each element in the StructArray represents a row (a named tuple), and you can access entire columns using dot notation (e.g., t.a).

You can grow the table using push! with new named tuples.

# Create a table from named fields
t = StructArray((a = [1, 2], b = ["x", "y"]))

# Access a row
t[1] # (a = 1, b = "x")

# Access a column
t.a # [1, 2]

# Add a new row
push!(t, (a = 3, b = "z"))