[vchuravy]

Supersedes #210, which added StaticSizeArray as a separate sibling type. Here the two are one type.

Design

FixedSizeArray{T,N,Mem} is now an alias for FixedSizeArrayDims{T,N,NTuple{N,Int},Mem}. The new struct FixedSizeArrayDims{T,N,D,Mem<:DenseVector{T}} (public, not exported) holds the memory backend and a tuple dims::D of dimensions. Each dimension can be dynamic, an Int stored in the array, or static, a compile-time constant which is part of the type and takes no space in the array: a Val from Base, or a StaticInt from Static.jl. E.g. (Val(5), Val(4), n) or (static(5), static(4), n).

Julia has no default type parameters, so the struct needs a name of its own for the three-parameter FixedSizeArray{T,N,Mem} to stay a concrete type. It has the same layout as before, so struct fields and Vector element types declared with it are unaffected.

julia> using FixedSizeArrays; using FixedSizeArrays: FixedSizeArrayDims

julia> nelements = 3;

julia> u = FixedSizeArrayDims{Float64}(undef, (Val(5), Val(4), nelements));

julia> size(u, 1)  # a compile-time constant
5

julia> a = FixedSizeArrayDims{Float64, 2, Tuple{Val{2}, Int}}([1 2 3; 4 5 6]);  # copy from a matrix

julia> v = collect(1.0:12.0);

julia> c = FixedSizeArrays.wrap(FixedSizeArrayDims, v, (Val(2), Val(3), :));  # `:` computed from the length of `v`

When the type of the array fixes the dimensions type, the dimensions given to a constructor are converted to it: FixedSizeArray{Float64}(undef, (Val(2), 3)) has two Int dimensions, while FixedSizeArrayDims{Float64}(undef, (Val(2), 3)) keeps the static one.

Val and StaticInt dimensions behave the same and can be mixed, e.g. (Val(2), static(3), n). They are kept as given, so Tuple{Val{2}, Int} and Tuple{StaticInt{2}, Int} are different dimensions types. A Val of another Integer type is converted to a Val of an Int, and a Val of anything else, e.g. Val(:a), throws an ArgumentError.

What is included

• Construction: undef constructors, converting constructors and collect_as with an explicit dimensions type, and FixedSizeArrays.wrap(FixedSizeArrayDims, parent, dims).
• Indexing: Cartesian indexing computes the linear index as a sum of strided terms; a stride is a constant as long as the dimensions before it are static. size(a, d), strides and length fold to constants for static dimensions, and out-of-bounds accesses throw LightBoundsErrors.
• Which operations keep the static dimensions:
  • kept: similar(a), similar(a, T), similar(typeof(a), size), copy, and in-place operations (copyto!, fill!, .=, rand!);
  • dropped: similar(a, T, size), out-of-place broadcasting, map, reductions, reshape, vec and indexing with ranges or colons return FixedSizeArrays with all dimensions dynamic, so that the result type does not depend on the value of the shape.
• Extensions:
  • Static.jl: enables StaticInt dimensions. It is a weak dependency, so loading FixedSizeArrays.jl stays fast; Val dimensions need no extension;
  • StaticArrayInterface.jl: static sizes and strides for StrideArraysCore/LoopVectorization/Polyester, with Val dimensions reported as StaticInts, and device of the memory backend, also for plain FixedSizeArrays;
  • Adapt.jl: arrays with static dimensions have their memory backend adapted and are wrapped again, e.g. adapt(CuArray, a) is a FixedSizeArrayDims backed by a CuVector; FixedSizeArrays are converted as a whole, as before;
  • MPI.jl and Random: now apply to arrays with static dimensions too.
• Docs: the README and the manual now present the two kinds of arrays:
  • a "Which one should I use?" section;
  • a comparison section covering both FixedSizeArray and FixedSizeArrayDims against Array, MArray/SArray, HybridArrays and StrideArraysCore;
  • a usage section on static dimensions: construction, and which operations keep them. The examples use Vals, with one example showing the same array with StaticInts;
  • a section on wrap.

Changes for FixedSizeArray

• FixedSizeArray is no longer the name of a struct: Base.typename(FixedSizeArray) is FixedSizeArrayDims.
• FixedSizeArray{Int, -1} now errors when the type is formed, because it would build NTuple{-1,Int}. One collect_as test was adjusted.
• Cartesian getindex/setindex! with several Int indices use the new strided linear index computation for all arrays, not only those with static dimensions.
• similar(a, T, size) now creates the memory backend with similar(parent(a), T, (n,)) instead of rebuilding the type from Mem.
• FixedSizeArrays.wrap now accepts at most one : dimension, also for FixedSizeArrays.
• fill! loops over the memory backend (fill! (also on views) 3–6x slower than for Array on Julia v1.13+: bounds check not elided #200), so it vectorizes on Julia v1.13 and later.

Testing

• test/static_dims.jl covers construction, indexing, similar/copy/fill!/copyto!/reshape, broadcasting and StaticArrayInterface for every memory backend, for both Val and StaticInt dimensions, and for mixes of the two.
• New FileCheck tests check that, with both Val and StaticInt dimensions:
  • size in a static dimension is constant-folded;
  • Cartesian indexing has exactly one bounds check, none under @inbounds, and uses the static sizes;
  • in-place broadcasting and fill! have no bounds checks and vectorize.
• MPI and Adapt tests cover arrays with static dimensions.
• CI passes on Julia 1.10, 1.11, 1, pre and nightly, with and without --check-bounds=yes, and the docs build with doctests is clean.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 97.64706% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.51%. Comparing base (4d87563) to head (47795c8).

Files with missing lines	Patch %	Lines
src/FixedSizeArray.jl	98.51%	2 Missing ⚠️
ext/FixedSizeArraysAdaptExt.jl	83.33%	1 Missing ⚠️
ext/FixedSizeArraysRandomExt.jl	66.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #213      +/-   ##
==========================================
+ Coverage   93.50%   94.51%   +1.00%     
==========================================
  Files           6        8       +2     
  Lines         231      310      +79     
==========================================
+ Hits          216      293      +77     
- Misses         15       17       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[giordano]

More comments from the bot:

No converting constructor for static types. S(matrix), FixedSizeArrayDims{Float64}(matrix), convert(S, matrix) and collect_as(FixedSizeArrayDims{Int}, iter) all throw MethodError. The only way to copy data into a static-dimension array is similar plus copyto!, or wrap around vec(copy(x)). Either add the constructor or state the limitation in the docs.

Smaller nits.

• FixedSizeArray{Float64}(undef, (2, :)) now fails with MethodError: no method matching dim_value(::Colon), an internal name. A Colon check in the undef path would give a clearer error, especially since wrap accepts :.
• adapt(FixedSizeArrayDims, x) is a no-op while adapt(FixedSizeArray, x) converts. Probably fine, but worth a line in the Adapt docs.
• FixedSizeArray{Int, -1} now errors at type formation with "Vararg length is negative". This and Base.typename are the only user-visible breakages I found. I agree with listing them under "Changed" rather than bumping the major version.
• Project.toml compat lists StaticArrayInterface = "1.5"; the test env resolved 1.10.0, so that is fine.

Verified behaviours worth knowing. size(a, d), length, and strides are compile-time constants for static dimensions, @inbounds a[1, j, k] compiles to zero integer loads with the multiplication by the static stride inlined, the static dimensions take no space, sum does not allocate, and extension loading works in either order. Views that drop a dimension fall back to DefaultArrayStyle and broadcast to Array, but that is pre-existing on main.

[giordano]

@vchuravy in 1a3f495 I removed the method Base.size(a::FixedSizeArrayDims{<:Any, N, D}, d::Integer) which caused the remaining invalidations, but in 442c299 I had added a FileCheck test to make sure that size(A, 2) * 3 is a compile-time constant. The only feature really lost is the Val propagation during inference. As a workaround the bot suggests

the constant is no longer visible to type inference. Base.return_types(a -> Val(size(a, 2)), …) gives Val instead of Val{4}. That only matters for code that turns size(a, d) into a type parameter, like Val(size(a, 2)). Such code can use known_dims or StaticArrayInterface’s known_size instead. stride(a, d) and strides(a) are still inferred as constants.

How important was the Val inference?

[vchuravy]

How important was the Val inference?

I don't think it was, and I think it is totally okay to say "use the extension to actually work with static dims"

[giordano]

I've been thinking about reasons for going to v2.0 instead of v1.5, but I can't find any. The bot found three:

• Base.typename(FixedSizeArray) changes,
• FixedSizeArray{Int,-1} now errors at type formation
• printing changes

The bot is somehow obsessed by the printing changes, I'm ignoring that. FixedSizeArray{Int,-1} erroring sounds like an improvement, and I don't particularly care about Base.typename(FixedSizeArray).

It may also be worth mentioning that we ran downstream tests on this PR, and not found any test failure.

[vchuravy]

I think going to 2.0 would allow us not to have to rename the type and instead keep the name the same.

[giordano]

@fredrikekre any idea of why in this code block there's no automatic link to the docstring of FixedSizeArrayDims?

[giordano]

Seems to be due to FixedSizeArrayDims not being exported?

[giordano]

I'm sick of reviewing this PR, so I'll approve it by exhaustion.

I think going to 2.0 would allow us not to have to rename the type and instead keep the name the same.

I think it'd still be valuable to have an alias for the fully dynamic version though. I'll leave it to you the choice of whether to rename this or not, as long as we have a convenient way to refer to the current FixedSizeArray (and FixedSizeArrayDefault)