Surge

A Swift library that uses the Accelerate framework to provide high-performance functions for matrix math, digital signal processing, and image manipulation.

Jounce
5275
484
Swift

Surge

Build Status
License
CocoaPods platforms
CocoaPods compatible
Carthage compatible
Swift Package Manager compatible

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.2")),
    ],
    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.2'
end

Then run pod install.

Carthage

To use Carthage add Surge to your Cartfile:

github "Jounce/Surge" ~> 2.3.2

Then run carthage update and use the framework in Carthage/Build/<platform>.

Usage

Computing Sum of [Double]

import Surge

let n = [1.0, 2.0, 3.0, 4.0, 5.0]
let sum = Surge.sum(n) // 15.0

Computing Product of Two [Double]s

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.elmul(a, b) // [2.0, 12.0, 30.0, 56.0]

Inventory

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) += (infix)
(Matrix, Scalar) n/a n/a 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) -= (infix)
(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) .**= (infix)
(Array, Scalar) pow ** (infix) **= (infix)
(Matrix, Scalar) pow n/a n/a
(Vector, Vector) pow n/a n/a

(Serial exponentiation: a ** b ** c == a ** (b ** c))

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