Repository files navigation

Statically sized arrays for Julia

StaticArrays provides a framework for implementing statically sized arraysin Julia, using the abstract typeStaticArray{Size,T,N} <: AbstractArray{T,N}.Subtypes ofStaticArray will provide fast implementations of common array andlinear algebra operations. Note that here "statically sized" means that thesize can be determined from thetype, and "static" doesnot necessarilyimplyimmutable.

The package also provides some concrete static array types:SVector,SMatrixandSArray, which may be used as-is (or else embedded in your own type).Mutable versionsMVector,MMatrix andMArray are also exported, as wellasSizedArray for annotating standardArrays with static size information.Further, the abstractFieldVector can be used to make fastStaticVectorsout of any uniform Julia "struct".Full documentation can be foundhere.

Most of the primary array types exported by StaticArrays.jl are defined in the small interfacepackageStaticArraysCore.jl. This includese.g., the definitions of the abstract typeStaticArray and the concrete typesSArray,MArray, andSizedArray (as well as their dimension-specific aliases).This enables downstream packages to implement new methods for these types without dependingon (and hence loading) the entirety of StaticArrays.jl, and thereby to avoid incurring the fullload-time of StaticArrays.jl (which is on the order of 0.6 s for StaticArrays.jl v1.4 on Juliav1.7).

The speed ofsmallSVectors,SMatrixs andSArrays is often > 10 × fasterthanBase.Array. For example, here's amicrobenchmark showing some common operations.

============================================    Benchmarks for 3×3 Float64 matrices============================================Matrix multiplication               -> 5.9x speedupMatrix multiplication (mutating)    -> 1.8x speedupMatrix addition                     -> 33.1x speedupMatrix addition (mutating)          -> 2.5x speedupMatrix determinant                  -> 112.9x speedupMatrix inverse                      -> 67.8x speedupMatrix symmetric eigendecomposition -> 25.0x speedupMatrix Cholesky decomposition       -> 8.8x speedupMatrix LU decomposition             -> 6.1x speedupMatrix QR decomposition             -> 65.0x speedup

These numbers were generated on an Intel i7-7700HQ using Julia-1.2. As with allsynthetic benchmarks, the speedups you see here should only be taken as veryroughly indicative of the speedup you may see in real code. When in doubt,benchmark your real application!

Note that in the current implementation, working with largeStaticArrays puts alot of stress on the compiler, and becomes slower thanBase.Array as the sizeincreases. A very rough rule of thumb is that you should consider using anormalArray for arrays larger than 100 elements.

AddStaticArrays from thePkg REPL, i.e.,pkg> add StaticArrays. Then:

using LinearAlgebrausing StaticArrays# Use the convenience constructor type `SA` to create vectors and matricesSA[1,2,3]isa SVector{3,Int}SA_F64[1,2,3]isa SVector{3,Float64}SA_F32[1,2,3]isa SVector{3,Float32}SA[12;34]isa SMatrix{2,2,Int}SA_F64[12;34]isa SMatrix{2,2,Float64}# Create an SVector using various forms, using constructors, functions or macrosv1=SVector(1,2,3)v1.data=== (1,2,3)# SVector uses a tuple for internal storagev2=SVector{3,Float64}(1,2,3)# length 3, eltype Float64v3=@SVector [1,2,3]v4=@SVector [i^2for i=1:10]# arbitrary comprehensions (range is evaluated at global scope)v5=zeros(SVector{3})# defaults to Float64v6=@SVectorzeros(3)v7=SVector{3}([1,2,3])# Array conversions must specify size# Can get size() from instance or typesize(v1)== (3,)size(typeof(v1))== (3,)# Similar constructor syntax for matricesm1=SMatrix{2,2}(1,2,3,4)# flat, column-major storage, equal to m2:m2=@SMatrix [13 ;24 ]m3=SMatrix{3,3}(1I)m4=@SMatrixrandn(4,4)m5=SMatrix{2,2}([13 ;24])# Array conversions must specify size# Higher-dimensional supporta=@SArrayrandn(2,2,2,2,2,2)# Supports all the common operations of AbstractArrayv7= v1+ v2v8=sin.(v3)v3== m3* v3# recall that m3 = SMatrix{3,3}(1I)# map, reduce, broadcast, map!, broadcast!, etc...# Indexing can also be done using static arrays of integersv1[1]===1v1[SVector(3,2,1)]===@SVector [3,2,1]v1[:]=== v1typeof(v1[[1,2,3]])<:Vector# Can't determine size from the type of [1,2,3]# Is (partially) hooked into BLAS, LAPACK, etc:rand(MMatrix{20,20})*rand(MMatrix{20,20})# large matrices can use BLASeigen(m3)# eigen(), etc uses specialized algorithms up to 3×3, or else LAPACK# Static arrays stay statically sized, even when used by Base functions, etc:typeof(eigen(m3).vectors)== SMatrix{3,3,Float64,9}typeof(eigen(m3).values)== SVector{3,Float64}# similar() returns a mutable container, while similar_type() returns a constructor:typeof(similar(m3))== MArray{Tuple{3,3},Int64,2,9}# (final parameter is length = 9)similar_type(m3)== SArray{Tuple{3,3},Int64,2,9}# The Size trait is a compile-time constant representing the sizeSize(m3)===Size(3,3)# A standard Array can be wrapped into a SizedArraym4=SizedMatrix{3,3}(rand(3,3))inv(m4)# Take advantage of specialized fast methods# reshape() uses Size() or types to specify size:reshape([1,2,3,4],Size(2,2))==@SMatrix [13 ;24 ]typeof(reshape([1,2,3,4],Size(2,2)))=== SizedArray{Tuple{2,2},Int64,2,1}

The package provides a range of different useful built-inStaticArray types,which include mutable and immutable arrays based upon tuples, arrays based uponstructs, and wrappers ofArray. There is a relatively simple interface forcreating your own, customStaticArray types, too.

This package also provides methods for a wide range ofAbstractArray functions,specialized for (potentially immutable)StaticArrays. Many of Julia'sbuilt-in method definitions inherently assume mutability, and furtherperformance optimizations may be made when the size of the array is known to thecompiler. One example of this is by loop unrolling, which has a substantialeffect on small arrays and tends to automatically trigger LLVM's SIMDoptimizations. Another way performance is boosted is by providing specializedmethods fordet,inv,eigen andcholesky where the algorithm depends on theprecise dimensions of the input. In combination with intelligent fallbacks tothe methods in Base, we seek to provide a comprehensive support for staticallysized arrays, large or small, that hopefully "just works".