README.md

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.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

• Installation
• License
  • Swift Package Manager
  • CocoaPods
  • Carthage
• Usage
  • Computing Sum of [Double]
  • Computing Product of Two [Double]s
• General Arithmetic Operations
  • Addition
  • Subtraction
  • Multiplication
  • Element-wise multiplication
  • Division)
  • Element-wise Division)
  • Modulo
  • Remainder
  • Square Root
  • Summation
  • Dot Product
  • Distance
  • Squared Distance
  • Power
  • Exponential
• Trigonometric Operations
  • Sine/Cosine/Tangent
  • Arc Sine/Cosine/Tangent
  • Hyperbolic Sine/Cosine/Tangent
  • Inverse Hyperbolic Sine/Cosine/Tangent
  • Radians ↔︎ Degrees
• Exponential Function
• Logarithm
• Statistical Operations
  • Summation
  • Minimum/Maximum
  • Mean/Variance
• Auxiliary Functions
  • Rounding Functions
  • Absolute value
  • Signum function
  • Multiplicative inverse
• Matrix-specific Operations
  • Matrix Inversion
  • Matrix Transposition
  • Matrix Determinant
  • Eigen Decomposition
• DSP-specific Operations
  • Fast Fourier Transform
  • Convolution
  • Cross-Correlation

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