# 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? (AndJounce?) 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 thejounce--- 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

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

# Inventory

- Installation
- License
- Usage
- 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) |
`+=` (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 |