Surge
Surge is a Swift library that uses the Accelerate framework to provide high-performance functions for matrix math, digital signal processing, and image manipulation.
Accelerate exposes SIMD instructions available in modern CPUs to significantly improve performance of certain calculations. Because of its relative obscurity and inconvenient APIs, Accelerate is not commonly used by developers, which is a shame, since many applications could benefit from these performance optimizations.
Surge aims to bring Accelerate to the mainstream, making it as easy (and nearly as fast, in most cases) to perform computation over a set of numbers as for a single member.
Though, keep in mind: Accelerate is not a silver bullet. Under certain conditions, such as performing simple calculations over a small data set, Accelerate can be out-performed by conventional algorithms. Always benchmark to determine the performance characteristics of each potential approach.
Curious about the name Surge? (And Jounce?) Back in the mid 90's, Apple, IBM, and Motorola teamed up to create AltiVec (a.k.a the Velocity Engine), which provided a SIMD instruction set for the PowerPC architecture. When Apple made the switch to Intel CPUs, AltiVec was ported to the x86 architecture and rechristened Accelerate. The derivative of Accelerate (and second derivative of Velocity) is known as either jerk, jolt, surge, or lurch; if you take the derivative of surge, you get the jounce --- hence the name of this library and its parent organization.
Installation
The infrastructure and best practices for distributing Swift libraries are currently in flux during this beta period of Swift & Xcode. In the meantime, you can add Surge as a git submodule, drag the Surge.xcodeproj
file into your Xcode project, and add Surge.framework
as a dependency for your target.
Surge uses Swift 5. This means that your code has to be written in Swift 5 due to current binary compatibility limitations.
License
Surge is available under the MIT license. See the LICENSE file for more info.
Swift Package Manager
To use Swift Package Manager add Surge to your Package.swift
file:
let package = Package(
name: "myproject",
dependencies: [
.package(url: "https://github.com/Jounce/Surge.git", .upToNextMajor(from: "2.3.0")),
],
targets: [
.target(
name: "myproject",
dependencies: ["Surge"]),
]
)
Then run swift build
.
CocoaPods
To use CocoaPods add Surge to your Podfile
:
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10.0'
use_frameworks!
target '<Your Target Name>' do
pod 'Surge', '~> 2.3.0'
end
Then run pod install
.
Carthage
To use Carthage add Surge to your Cartfile
:
github "Jounce/Surge" ~> 2.3.0
Then run carthage update
and use the framework in Carthage/Build/<platform>
.
Usage
[Double]
Computing Sum of import Surge
let n = [1.0, 2.0, 3.0, 4.0, 5.0]
let sum = Surge.sum(n) // 15.0
[Double]
s
Computing Product of Two import Surge
let a = [1.0, 3.0, 5.0, 7.0]
let b = [2.0, 4.0, 6.0, 8.0]
let product = Surge.mul(a, b) // [2.0, 12.0, 30.0, 56.0]
Inventory
- General Arithmetic Operations
- Trigonometric Operations
- Exponential Function
- Logarithm
- Statistical Operations
- Auxiliary Functions
- Matrix-specific Operations
- DSP-specific Operations
General Arithmetic Operations
Addition
Addition functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Array, Array) |
add |
.+ (infix) |
.+= (infix) |
(Array, Scalar) |
add |
+ (infix) |
+= (infix) |
(Matrix, Matrix) |
add |
+ (infix) |
n/a |
(Matrix, Scalar) |
n/a | + (infix) |
n/a |
(Vector, Vector) |
add |
+ (infix) |
+= (infix) |
(Vector, Scalar) |
add |
+ (infix) |
+= (infix) |
Subtraction
Subtraction functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Array, Array) |
sub |
.- (infix) |
.-= (infix) |
(Array, Scalar) |
sub |
- (infix) |
-= (infix) |
(Matrix, Matrix) |
sub |
- (infix) |
n/a |
(Matrix, Scalar) |
n/a | n/a | n/a |
(Vector, Vector) |
sub |
- (infix) |
-= (infix) |
(Vector, Scalar) |
sub |
- (infix) |
-= (infix) |
Multiplication
Multiplication functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Array, Array) |
mul |
.* (infix) |
.*= (infix) |
(Array, Scalar) |
mul |
* (infix) |
*= (infix) |
(Matrix, Matrix) |
mul |
* (infix) |
n/a |
(Matrix, Vector) |
mul |
* (infix) |
n/a |
(Matrix, Scalar) |
mul |
* (infix) |
n/a |
(Vector, Matrix) |
mul |
* (infix) |
n/a |
(Vector, Scalar) |
mul |
* (infix) |
*= (infix) |
(Scalar, Array) |
mul |
* (infix) |
n/a |
(Scalar, Matrix) |
mul |
* (infix) |
n/a |
(Scalar, Vector) |
mul |
* (infix) |
n/a |
Element-wise multiplication
Element-wise multiplication functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Matrix, Matrix) |
elmul |
n/a | n/a |
(Vector, Vector) |
elmul |
.* (infix) |
.*= (infix) |
Division
Division functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Array, Array) |
div |
./ (infix) |
./= (infix) |
(Array, Scalar) |
div |
/ (infix) |
/= (infix) |
(Matrix, Matrix) |
div |
/ (infix) |
n/a |
(Matrix, Scalar) |
n/a | / (infix) |
n/a |
(Vector, Scalar) |
div |
/ (infix) |
/= (infix) |
Element-wise Division
Element-wise multiplication functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Vector, Vector) |
eldiv |
./ (infix) |
./= (infix) |
Modulo
Modulo functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Array, Array) |
mod |
.% (infix) |
n/a |
(Array, Scalar) |
mod |
% (infix) |
n/a |
Remainder
Remainder functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Array, Array) |
remainder |
n/a | n/a |
(Array, Scalar) |
remainder |
n/a | n/a |
Square Root
Square root functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Array) |
sqrt |
n/a | n/a |
Summation
Sum functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Array) |
sum |
n/a | n/a |
(Matrix) |
sum |
n/a | n/a |
Dot Product
Dot product functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Array, Array) |
dot |
• (infix) |
n/a |
(Vector, Vector) |
dot |
• (infix) |
n/a |
Distance
Distance functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Array, Array) |
dist |
n/a | n/a |
(Vector, Vector) |
dist |
n/a | n/a |
Squared Distance
Squared distance functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Array, Array) |
distSq |
n/a | n/a |
(Vector, Vector) |
distSq |
n/a | n/a |
Power
Power functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Array, Array) |
pow |
** (infix) |
n/a |
(Array, Scalar) |
pow |
** (infix) |
n/a |
(Matrix, Scalar) |
pow |
** (infix) |
n/a |
(Vector, Vector) |
pow |
n/a | n/a |
Exponential
Exponential functions & operators
Arguments | Function | Operator | In-Place Operator |
---|---|---|---|
(Array) |
exp |
n/a | n/a |
(Matrix) |
exp |
n/a | n/a |
(Vector) |
exp |
n/a | n/a |
Trigonometric Operations
Trigonometric functions & operators
Sine/Cosine/Tangent
Arguments | Function | Operation |
---|---|---|
(Array) |
sin |
Sine |
(Array) |
cos |
Cosine |
(Array) |
tan |
Tangent |
(Array) |
sincos |
Sine & Cosine |
Arc Sine/Cosine/Tangent
Arguments | Function | Operation |
---|---|---|
(Array) |
asin |
Arc Sine |
(Array) |
acos |
Arc Cosine |
(Array) |
atan |
Arc Tangent |
Hyperbolic Sine/Cosine/Tangent
Arguments | Function | Operation |
---|---|---|
(Array) |
sinh |
Hyperbolic Sine |
(Array) |
cosh |
Hyperbolic Cosine |
(Array) |
tanh |
Hyperbolic Tangent |
Inverse Hyperbolic Sine/Cosine/Tangent
Arguments | Function | Operation |
---|---|---|
(Array) |
asinh |
Inverse Hyperbolic Sine |
(Array) |
acosh |
Inverse Hyperbolic Cosine |
(Array) |
atanh |
Inverse Hyperbolic Tangent |
Radians ↔︎ Degrees
Arguments | Function | Operation |
---|---|---|
(Array) |
rad2deg |
Radians to Degrees |
(Array) |
deg2rad |
Degrees to Radians |
Exponential Function
Exponential functions & operators
Arguments | Function | Operation |
---|---|---|
(Array) |
exp |
Base-e Exponential Function |
(Array) |
exp2 |
Base-2 Exponential Function |
Logarithm
Exponential functions & operators
Arguments | Function | Operation |
---|---|---|
(Array) |
log |
Base-e Logarithm |
(Array) |
log2 |
Base-2 Logarithm |
(Array) |
log10 |
Base-10 Logarithm |
(Array) |
logb |
Base-b Logarithm |
Statistical Operations
Statistical functions & operators
Summation
Arguments | Function | Operation |
---|---|---|
(Array) |
sum |
Summation |
(Array) |
asum |
Absolute Summation |
Minimum/Maximum
Arguments | Function | Operation |
---|---|---|
(Array) |
min |
Minimum |
(Array) |
max |
Maximum |
Mean/Variance
Arguments | Function | Operation |
---|---|---|
(Array) |
mean |
Mean |
(Array) |
meamg |
Mean of Magnitudes |
(Array) |
measq |
Mean of Squares |
(Array) |
variance |
Variance |
(Array) |
std |
Standard Deviation |
Auxiliary Functions
Auxiliary functions & operators
Rounding Functions
Arguments | Function | Operation |
---|---|---|
(Array) |
ceil |
Ceiling |
(Array) |
floor |
Flooring |
(Array) |
round |
Rounding |
(Array) |
trunc |
Integer truncation |
Absolute value
Arguments | Function | In-Place Function | Operator | In-Place Operator |
---|---|---|---|---|
(Array) |
abs |
n/a | n/a | n/a |
Signum function
Arguments | Function | In-Place Function | Operator | In-Place Operator |
---|---|---|---|---|
(Array) |
copysign |
n/a | n/a | n/a |
Multiplicative inverse
Arguments | Function | In-Place Function | Operator | In-Place Operator |
---|---|---|---|---|
(Array) |
rec |
n/a | n/a | n/a |
Matrix-specific Operations
Matrix-specific functions & operators
Matrix Inversion
Arguments | Function | In-Place Function | Operator | In-Place Operator |
---|---|---|---|---|
(Matrix) |
inv |
n/a | n/a | n/a |
Matrix Transposition
Arguments | Function | In-Place Function | Operator | In-Place Operator |
---|---|---|---|---|
(Matrix) |
transpose |
n/a | ′ (postfix) |
n/a |
Matrix Determinant
Arguments | Function | In-Place Function | Operator | In-Place Operator |
---|---|---|---|---|
(Matrix) |
det |
n/a | n/a | n/a |
Eigen Decomposition
Arguments | Function | In-Place Function | Operator | In-Place Operator |
---|---|---|---|---|
(Matrix) |
eigenDecompose |
n/a | n/a | n/a |
DSP-specific Operations
Fast fourier transform functions & operators
Fast Fourier Transform
Arguments | Function | In-Place Function | Operator | In-Place Operator |
---|---|---|---|---|
(Array) |
fft |
n/a | n/a | n/a |
Convolution
Arguments | Function | In-Place Function | Operator | In-Place Operator |
---|---|---|---|---|
(Array, Array) |
conv |
n/a | n/a | n/a |
Cross-Correlation
Arguments | Function | In-Place Function | Operator | In-Place Operator |
---|---|---|---|---|
(Array, Array) |
xcorr |
n/a | n/a | n/a |
(Array) |
xcorr |
n/a | n/a | n/a |