Swiftpack.co - Package - mattt/Surge

Surge

Build Status GitHub license Carthage compatible SPM compatible CocoaPods

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? 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, hence the name of this library.


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/mattt/Surge.git", .upToNextMajor(from: "2.0.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.0.0'
end

Then run pod install.

Carthage

To use Carthage add Surge to your Cartfile:

github "mattt/Surge" ~> 2.0.0

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.mul(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) | 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

| Arguments | Function | Operation | |-----------|----------|--------------------------------------------------------------| | (Array) | mean | Mean | | (Array) | meamg | Mean of Magnitudes | | (Array) | measq | Mean of squares |

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 |

Github

link
Stars: 4518
Help us keep the lights on

Dependencies

Releases

2.1.0 - Jun 30, 2018

The plus + operator is used by Swift for array concatenation. This caused some confusion with Surge's + element-wise addition. For this version all element-wise operators are preceded by a dot: .+.

This version also updates to Swift 4.0 and adds a few extra functions.

2.0.0 - Sep 19, 2017

It took a while but it's finally here. This version support Swift 3.2 and Xcode 9.

Other changes include:

  • Fix Matrix initialization bug
  • Add Swift Package Manager support
  • Fix Carthage support.
  • Make rows and columns properties public
  • Add sum of square values.
  • Add some helper methods for matrix
  • Add subscript support to return specific row or column
  • Add support for scaling matrix by row or by column
  • Make pow support applying to every element
  • Add subtract method and operator

0.4.0 - Dec 11, 2015

This release is the last version to support Swift 1.0. Surge 2.x releases will support Swift 2.0.