Surge

[![Build Status][build status badge]][build status] [![License][license badge]][license] ![CocoaPods platforms][cocoapods platforms badge] [![CocoaPods compatible][cocoapods badge]][cocoapods] [![Carthage compatible][carthage badge]][carthage] [![Swift Package Manager compatible][swift package manager badge]][swift package manager]

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

<details open> <summary> Addition functions & operators </summary>

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

<!-- Internal use only: | In-Place Function | |-------------------| | `addInPlace` | | `addInPlace` | | n/a | | n/a | | `addInPlace` | | `addInPlace` | --> <!-- FIXME: `add` for `(Array, Array)` should be called `eladd`/`.+`, no? --> <!-- FIXME: Missing `add` function for `(Matrix, Scalar)`. --> <!-- FIXME: Missing `add` functions/operators for `(Matrix, Vector)`. --> <!-- FIXME: Missing `addInPlace` function for `(Matrix, Scalar)` & `(Matrix, Matrix)`. --> </details>

Subtraction

<details open> <summary> Subtraction functions & operators </summary>

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

<!-- Internal use only: | In-Place Function | |-------------------| | `subInPlace` | | `subInPlace` | | n/a | | n/a | | `subInPlace` | | `subInPlace` | --> <!-- FIXME: `sub` for `(Array, Array)` should be called `elsub`/`.-`, no? --> <!-- FIXME: Missing `sub` function/operator for `(Matrix, Scalar)`. --> <!-- FIXME: Missing `sub` functions/operators for `(Matrix, Vector)`. --> <!-- FIXME: Missing `subInPlace` function for `(Matrix, Scalar)` & `(Matrix, Matrix)`. --> </details>

Multiplication

<details open> <summary> Multiplication functions & operators </summary>

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

<!-- Internal use only: | In-Place Function | |-------------------| | `mulInPlace` | | `mulInPlace` | | n/a | | n/a | | n/a | | n/a | | `mulInPlace` | | n/a | | n/a | | n/a | --> </details>

Element-wise multiplication

<details open> <summary> Element-wise multiplication functions & operators </summary>