Surge/README.md

# Surge

[![Build Status](https://travis-ci.org/mattt/Surge.svg?branch=master)](https://travis-ci.org/mattt/Surge) [![GitHub license](https://img.shields.io/badge/license-MIT-lightgrey.svg)](https://github.com/mattt/Surge/blob/master/LICENSE) [![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage) [![SPM compatible](https://img.shields.io/badge/spm-compatible-brightgreen.svg?style=flat)](https://swift.org/package-manager) [![CocoaPods](https://img.shields.io/cocoapods/v/Surge.svg)](https://cocoapods.org/pods/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](http://en.wikipedia.org/wiki/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](http://en.wikipedia.org/wiki/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](https://developer.apple.com/library/mac/documentation/Accelerate/Reference/AccelerateFWRef/_index.html). The derivative of Accelerate (and second derivative of Velocity) is known as either [jerk, jolt, surge, or lurch](http://en.wikipedia.org/wiki/Jerk_%28physics%29), 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](https://swift.org/package-manager/) add Surge to your `Package.swift` file:

```swift
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](https://cocoapods.org) add Surge to your `Podfile`:

```ruby
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](https://github.com/Carthage/Carthage) add Surge to your `Cartfile`:

```ruby
github "mattt/Surge" ~> 2.0.0
```

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

---

## Usage

### Computing Sum of `[Double]`

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

```swift
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](#general-arithmetic-operations)
  - [Addition](#addition)
  - [Subtraction](#subtraction)
  - [Multiplication](#multiplication)
  - [Element-wise multiplication](#element-wise-multiplication)
  - [Division)](#division)
  - [Element-wise Division)](#element-wise-division)
  - [Modulo](#modulo)
  - [Remainder](#remainder)
  - [Square Root](#square-root)
  - [Summation](#summation)
  - [Dot Product](#dot-product)
  - [Distance](#distance)
  - [Squared Distance](#squared-distance)
  - [Power)](#power)
  - [Exponential](#exponential)
- [Trigonometric Operations](#trigonometric-operations)
  - [Sine/Cosine/Tangent](#sinecosinetangent)
  - [Arc Sine/Cosine/Tangent](#arc-sinecosinetangent)
  - [Hyperbolic Sine/Cosine/Tangent](#hyperbolic-sinecosinetangent)
  - [Inverse Hyperbolic Sine/Cosine/Tangent](#inverse-hyperbolic-sinecosinetangent)
  - [Radians ↔︎ Degrees](#radians-%e2%86%94%ef%b8%8e-degrees)
- [Exponential Function](#exponential-function)
- [Logarithm](#logarithm)
- [Statistical Operations](#statistical-operations)
  - [Summation](#summation-1)
  - [Minimum/Maximum](#minimummaximum)
  - [Mean](#mean)
- [Auxiliary Functions](#auxiliary-functions)
  - [Rounding Functions](#rounding-functions)
  - [Absolute value](#absolute-value)
  - [Signum function](#signum-function)
  - [Multiplicative inverse](#multiplicative-inverse)
- [Matrix-specific Operations](#matrix-specific-operations)
  - [Matrix Inversion](#matrix-inversion)
  - [Matrix Transposition](#matrix-transposition)
  - [Matrix Determinant](#matrix-determinant)
  - [Eigen Decomposition](#eigen-decomposition)
- [DSP-specific Operations](#dsp-specific-operations)
  - [Fast Fourier Transform](#fast-fourier-transform)
  - [Convolution](#convolution)
  - [Cross-Correlation](#cross-correlation)

## General Arithmetic Operations

### [Addition](https://en.wikipedia.org/wiki/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)  | n/a               |
| `(Matrix, Scalar)` | n/a      | `+` (infix)  | 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](https://en.wikipedia.org/wiki/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)  | n/a               |
| `(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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/Multiplication)

<details open>

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

| Arguments          | Function | Operator     | In-Place Operator |
|--------------------|----------|--------------|-------------------|
| `(Matrix, Matrix)` | `elmul`  | n/a          | n/a               |
| `(Vector, Vector)` | `elmul`  | `.*` (infix) | `.*=` (infix)     |

<!--
Internal use only:

| In-Place Function |
|-------------------|
| n/a               |
| `elmulInPlace`    |
-->

<!-- FIXME: The does not seem to be a `.*` implemented for `(Matrix, Matrix)`. -->

</details>

### [Division](https://en.wikipedia.org/wiki/Division_(mathematics))

<details open>

<summary>
Division functions & operators
</summary>

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

<!--
Internal use only:

| In-Place Function |
|-------------------|
| `divInPlace`      |
| `divInPlace`      |
| n/a               |
| n/a               |
| `divInPlace`      |
-->

<!-- FIXME: Func `div` of `(Array, Array)` should be called `eldiv`, no? -->
<!-- FIXME: Missing `div` function for `(Matrix, Scalar)`. -->

</details>

### [Element-wise Division](https://en.wikipedia.org/wiki/Division_(mathematics))

<details open>

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

| Arguments          | Function | Operator     | In-Place Operator |
|--------------------|----------|--------------|-------------------|
| `(Vector, Vector)` | `eldiv`  | `./` (infix) | `./=` (infix)     |

<!--
Internal use only:

| In-Place Function |
|-------------------|
| `eldivInPlace`    |
 -->

</details>

### [Modulo](https://en.wikipedia.org/wiki/Modulo_operation)

<details open>

<summary>
Modulo functions & operators
</summary>

| Arguments         | Function | Operator     | In-Place Operator |
|-------------------|----------|--------------|-------------------|
| `(Array, Array)`  | `mod`    | `.%` (infix) | n/a               |
| `(Array, Scalar)` | `mod`    | `%` (infix)  | n/a               |

<!--
Internal use only:

| In-Place Function |
|-------------------|
| n/a               |
| n/a               |
-->

<!-- FIXME: Do we need `mod` functions/operators for `Matrix`? -->
<!-- FIXME: Do we need `mod` functions/operators for `Vector`? -->

</details>

### [Remainder](https://en.wikipedia.org/wiki/Remainder)

<details open>

<summary>
Remainder functions & operators
</summary>

| Arguments         | Function    | Operator | In-Place Operator |
|-------------------|-------------|----------|-------------------|
| `(Array, Array)`  | `remainder` | n/a      | n/a               |
| `(Array, Scalar)` | `remainder` | n/a      | n/a               |

<!--
Internal use only:

| In-Place Function |
|-------------------|
| n/a               |
| n/a               |
 -->

<!-- FIXME: Do we need `remainder` functions /operators for `Matrix`? -->
<!-- FIXME: Do we need `remainder` functions /operators for `Vector`? -->

</details>

### [Square Root](https://en.wikipedia.org/wiki/Square_root)

<details open>

<summary>
Square root functions & operators
</summary>

| Arguments | Function | Operator | In-Place Operator |
|-----------|----------|----------|-------------------|
| `(Array)` | `sqrt`   | n/a      | n/a               |

<!--
Internal use only:

| In-Place Function |
|-------------------|
| n/a               |
 -->

<!-- FIXME: The seems to be a variant `func sqrt<MI, MO>(_ x: MI, into results: inout MO)` that could be made into a `sqrtInPlace`-->

<!-- FIXME: Do we need `sqrt` functions/operators for `Matrix`? -->
<!-- FIXME: Do we need `sqrt` functions/operators for `Vector`? -->

</details>

### [Summation](https://en.wikipedia.org/wiki/Summation)

<details open>

<summary>
Sum functions & operators
</summary>

| Arguments  | Function | Operator | In-Place Operator |
|------------|----------|----------|-------------------|
| `(Array)`  | `sum`    | n/a      | n/a               |
| `(Matrix)` | `sum`    | n/a      | n/a               |

<!--
Internal use only:

| In-Place Function |
|-------------------|
| n/a               |
| n/a               |
 -->

<!-- FIXME: Do we need `sum` functions/operators for `Vector`? -->

</details>

### [Dot Product](https://en.wikipedia.org/wiki/Dot_product)

<details open>

<summary>
Dot product functions & operators
</summary>

| Arguments          | Function | Operator    | In-Place Operator |
|--------------------|----------|-------------|-------------------|
| `(Array, Array)`   | `dot`    | `•` (infix) | n/a               |
| `(Vector, Vector)` | `dot`    | `•` (infix) | n/a               |

<!--
Internal use only:

| In-Place Function |
|-------------------|
| n/a               |
| n/a               |
 -->

<!-- FIXME: Do we need `dot` functions/operators for `Matrix`? -->

</details>

### [Distance](https://en.wikipedia.org/wiki/Euclidean_distance)

<details open>

<summary>
Distance functions & operators
</summary>

| Arguments          | Function | Operator | In-Place Operator |
|--------------------|----------|----------|-------------------|
| `(Array, Array)`   | `dist`   | n/a      | n/a               |
| `(Vector, Vector)` | `dist`   | n/a      | n/a               |

<!--
Internal use only:

| In-Place Function |
|-------------------|
| n/a               |
| n/a               |
 -->

### [Squared Distance](https://en.wikipedia.org/wiki/Euclidean_distance#Squared_Euclidean_distance)

<details open>

<summary>
Squared distance functions & operators
</summary>

| Arguments          | Function | Operator | In-Place Operator |
|--------------------|----------|----------|-------------------|
| `(Array, Array)`   | `distSq` | n/a      | n/a               |
| `(Vector, Vector)` | `distSq` | n/a      | n/a               |

<!--
Internal use only:

| In-Place Function |
|-------------------|
| n/a               |
| n/a               |
 -->

</details>

### [Power](https://en.wikipedia.org/wiki/Power_(mathematics))

<details open>

<summary>
Power functions & operators
</summary>

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

<!--
Internal use only:

| In-Place Function |
|-------------------|
| n/a               |
| n/a               |
| n/a               |
| n/a               |
 -->

<!-- FIXME: Shouldn't the `pow`/`**` function/operator of `(Array, Array)` be `elpow`/`.**`? -->
<!-- FIXME: Shouldn't the `pow`/`**` function/operator of `(Vector, Vector)` be `elpow`/`.**`? -->
<!-- FIXME: The does not seem to be a corresponding `.**` operator implemented. -->
<!-- FIXME: Do we need `pow` functions/operators for `(Vector, Scalar)`? -->

### [Exponential](https://en.wikipedia.org/wiki/Exponential_function)

<details open>

<summary>
Exponential functions & operators
</summary>

| Arguments  | Function | Operator | In-Place Operator |
|------------|----------|----------|-------------------|
| `(Array)`  | `exp`    | n/a      | n/a               |
| `(Matrix)` | `exp`    | n/a      | n/a               |
| `(Vector)` | `exp`    | n/a      | n/a               |

<!--
Internal use only:

| In-Place Function |
|-------------------|
| n/a               |
| n/a               |
| n/a               |
 -->

</details>

## Trigonometric Operations

<details open>

<summary>
Trigonometric functions & operators
</summary>

### [Sine/Cosine/Tangent](https://en.wikipedia.org/wiki/Trigonometric_functions)

| Arguments | Function | Operation     |
|-----------|----------|---------------|
| `(Array)` | `sin`    | Sine          |
| `(Array)` | `cos`    | Cosine        |
| `(Array)` | `tan`    | Tangent       |
| `(Array)` | `sincos` | Sine & Cosine |

### [Arc Sine/Cosine/Tangent](https://en.wikipedia.org/wiki/Trigonometric_functions)

| Arguments | Function | Operation   |
|-----------|----------|-------------|
| `(Array)` | `asin`   | Arc Sine    |
| `(Array)` | `acos`   | Arc Cosine  |
| `(Array)` | `atan`   | Arc Tangent |

### [Hyperbolic Sine/Cosine/Tangent](https://en.wikipedia.org/wiki/Hyperbolic_function)

| Arguments | Function | Operation          |
|-----------|----------|--------------------|
| `(Array)` | `sinh`   | Hyperbolic Sine    |
| `(Array)` | `cosh`   | Hyperbolic Cosine  |
| `(Array)` | `tanh`   | Hyperbolic Tangent |

### [Inverse Hyperbolic Sine/Cosine/Tangent](https://en.wikipedia.org/wiki/Inverse_hyperbolic_functions)

| Arguments | Function | Operation                  |
|-----------|----------|----------------------------|
| `(Array)` | `asinh`  | Inverse Hyperbolic Sine    |
| `(Array)` | `acosh`  | Inverse Hyperbolic Cosine  |
| `(Array)` | `atanh`  | Inverse Hyperbolic Tangent |

### [Radians ↔︎ Degrees](https://en.wikipedia.org/wiki/Angle#Types_of_angles)

| Arguments | Function  | Operation                                                                                                  |
|-----------|-----------|------------------------------------------------------------------------------------------------------------|
| `(Array)` | `rad2deg` | [Radians](https://en.wikipedia.org/wiki/Radian) to [Degrees](https://en.wikipedia.org/wiki/Degree_(angle)) |
| `(Array)` | `deg2rad` | [Degrees](https://en.wikipedia.org/wiki/Degree_(angle)) to [Radians](https://en.wikipedia.org/wiki/Radian) |

</details>

## [Exponential Function](https://en.wikipedia.org/wiki/Exponential_function)

<details open>

<summary>
Exponential functions & operators
</summary>

| Arguments | Function | Operation                   |
|-----------|----------|-----------------------------|
| `(Array)` | `exp`    | Base-e Exponential Function |
| `(Array)` | `exp2`   | Base-2 Exponential Function |

</details>

## [Logarithm](https://en.wikipedia.org/wiki/Logarithm)

<details open>

<summary>
Exponential functions & operators
</summary>

| Arguments | Function | Operation         |
|-----------|----------|-------------------|
| `(Array)` | `log`    | Base-e Logarithm  |
| `(Array)` | `log2`   | Base-2 Logarithm  |
| `(Array)` | `log10`  | Base-10 Logarithm |
| `(Array)` | `logb`   | Base-b Logarithm  |

</details>

## Statistical Operations

<details open>

<summary>
Statistical functions & operators
</summary>

### [Summation](https://en.wikipedia.org/wiki/Summation)

| Arguments | Function | Operation          |
|-----------|----------|--------------------|
| `(Array)` | `sum`    | Summation          |
| `(Array)` | `asum`   | Absolute Summation |

### [Minimum/Maximum](https://en.wikipedia.org/wiki/Maximal_and_minimal_elements)

| Arguments | Function | Operation |
|-----------|----------|-----------|
| `(Array)` | `min`    | Minimum   |
| `(Array)` | `max`    | Maximum   |

### [Mean](https://en.wikipedia.org/wiki/Mean)

| Arguments | Function | Operation                                                    |
|-----------|----------|--------------------------------------------------------------|
| `(Array)` | `mean`   | [Mean](https://en.wikipedia.org/wiki/Mean)                   |
| `(Array)` | `meamg`  | Mean of Magnitudes                                           |
| `(Array)` | `measq`  | [Mean of squares](https://en.wikipedia.org/wiki/Mean_square) |

</details>

## Auxiliary Functions

<details open>

<summary>
Auxiliary functions & operators
</summary>

### [Rounding Functions](https://en.wikipedia.org/wiki/Rounding)

| Arguments | Function | Operation                                                             |
|-----------|----------|-----------------------------------------------------------------------|
| `(Array)` | `ceil`   | [Ceiling](https://en.wikipedia.org/wiki/Floor_and_ceiling_functions)  |
| `(Array)` | `floor`  | [Flooring](https://en.wikipedia.org/wiki/Floor_and_ceiling_functions) |
| `(Array)` | `round`  | [Rounding](https://en.wikipedia.org/wiki/Rounding)                    |
| `(Array)` | `trunc`  | [Integer truncation](https://en.wikipedia.org/wiki/Truncation)        |

### [Absolute value](https://en.wikipedia.org/wiki/Absolute_value)

| Arguments | Function | In-Place Function | Operator | In-Place Operator |
|-----------|----------|-------------------|----------|-------------------|
| `(Array)` | `abs`    | n/a               | n/a      | n/a               |

### [Signum function](https://en.wikipedia.org/wiki/Sign_function)

| Arguments | Function   | In-Place Function | Operator | In-Place Operator |
|-----------|------------|-------------------|----------|-------------------|
| `(Array)` | `copysign` | n/a               | n/a      | n/a               |

### [Multiplicative inverse](https://en.wikipedia.org/wiki/Multiplicative_inverse)

| Arguments | Function | In-Place Function | Operator | In-Place Operator |
|-----------|----------|-------------------|----------|-------------------|
| `(Array)` | `rec`    | n/a               | n/a      | n/a               |

</details>

## Matrix-specific Operations

<details open>

<summary>
Matrix-specific functions & operators
</summary>

### [Matrix Inversion](https://en.wikipedia.org/wiki/Invertible_matrix)

| Arguments  | Function | In-Place Function | Operator | In-Place Operator |
|------------|----------|-------------------|----------|-------------------|
| `(Matrix)` | `inv`    | n/a               | n/a      | n/a               |

### [Matrix Transposition](https://en.wikipedia.org/wiki/Matrix_transpose)

| Arguments  | Function    | In-Place Function | Operator      | In-Place Operator |
|------------|-------------|-------------------|---------------|-------------------|
| `(Matrix)` | `transpose` | n/a               | `′` (postfix) | n/a               |

### [Matrix Determinant](https://en.wikipedia.org/wiki/Matrix_determinant)

| Arguments  | Function | In-Place Function | Operator | In-Place Operator |
|------------|----------|-------------------|----------|-------------------|
| `(Matrix)` | `det`    | n/a               | n/a      | n/a               |

### [Eigen Decomposition](https://en.wikipedia.org/wiki/Eigen_decomposition)

| Arguments  | Function         | In-Place Function | Operator | In-Place Operator |
|------------|------------------|-------------------|----------|-------------------|
| `(Matrix)` | `eigenDecompose` | n/a               | n/a      | n/a               |

</details>

## DSP-specific Operations

<details open>

<summary>
Fast fourier transform functions & operators
</summary>

### [Fast Fourier Transform](https://en.wikipedia.org/wiki/Convolution)

| Arguments | Function | In-Place Function | Operator | In-Place Operator |
|-----------|----------|-------------------|----------|-------------------|
| `(Array)` | `fft`    | n/a               | n/a      | n/a               |

### [Convolution](https://en.wikipedia.org/wiki/Convolution)

| Arguments        | Function | In-Place Function | Operator | In-Place Operator |
|------------------|----------|-------------------|----------|-------------------|
| `(Array, Array)` | `conv`   | n/a               | n/a      | n/a               |

### [Cross-Correlation](https://en.wikipedia.org/wiki/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               |

</details>
-												Add linter, fix linter warnigns, uncomment tests

											
										
										
											2017-09-25 14:07:45 +08:00
+								# Surge
-												Remove outdated performance benchmarks

											
										
										
											2018-12-24 00:33:36 +08:00
-												Add README badges indicating CocoaPods and SPM compatibility (#99)


											
										
										
											2019-05-06 01:08:14 +08:00
+								[![Build Status](https://travis-ci.org/mattt/Surge.svg?branch=master)](https://travis-ci.org/mattt/Surge) [![GitHub license](https://img.shields.io/badge/license-MIT-lightgrey.svg)](https://github.com/mattt/Surge/blob/master/LICENSE) [![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage) [![SPM compatible](https://img.shields.io/badge/spm-compatible-brightgreen.svg?style=flat)](https://swift.org/package-manager) [![CocoaPods](https://img.shields.io/cocoapods/v/Surge.svg)](https://cocoapods.org/pods/Surge)
-												Update README.md

Added the MIT badge to the README
											
										
										
											2016-02-15 10:42:52 +08:00
-												Update README.md
											
										
										
											2016-02-21 22:31:28 +08:00
+								Surge is a Swift library that uses the Accelerate framework to provide high-performance functions for matrix math, digital signal processing, and image manipulation.
-												Update README.md
											
										
										
											2016-02-17 09:31:31 +08:00
-												Update README.md
											
										
										
											2016-02-21 22:31:10 +08:00
+								Accelerate exposes [SIMD](http://en.wikipedia.org/wiki/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.
-												Initial Commit

											
										
										
											2014-08-24 14:02:33 +08:00
 								**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.**
-												Update README.md

											
										
										
											2014-08-24 14:14:53 +08:00
+								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.
-												Initial Commit

											
										
										
											2014-08-24 14:02:33 +08:00
-												Update README.md

											
										
										
											2014-08-24 14:14:30 +08:00
+								---
 								> Curious about the name _Surge_? Back in the mid 90's, Apple, IBM, and Motorola teamed up to create [AltiVec](http://en.wikipedia.org/wiki/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](https://developer.apple.com/library/mac/documentation/Accelerate/Reference/AccelerateFWRef/_index.html). The derivative of Accelerate (and second derivative of Velocity) is known as either [jerk, jolt, surge, or lurch](http://en.wikipedia.org/wiki/Jerk_%28physics%29), hence the name of this library.
 								---
-												Initial Commit

											
										
										
											2014-08-24 14:02:33 +08:00
+								## Installation
-												Update README.md

											
										
										
											2014-08-24 14:26:46 +08:00
+								_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._
-												Initial Commit

											
										
										
											2014-08-24 14:02:33 +08:00
-												Migrated to Swift 5 (#97)


											
										
										
											2019-04-25 00:04:38 +08:00
+								Surge uses Swift 5. This means that your code has to be written in Swift 5 due to current binary compatibility limitations.
-												Add Swift version to README

											
										
										
											2018-10-25 00:05:12 +08:00
-												Moved ‘License’ further up in README

											
										
										
											2019-08-30 06:46:42 +08:00
+								## License
 								Surge is available under the MIT license. See the LICENSE file for more info.
-												Update README with installation instructions

Add SPM and CocoaPods
											
										
										
											2017-09-23 04:47:28 +08:00
+								### Swift Package Manager
-												Update README w Carthage compatibility

											
										
										
											2017-05-08 15:20:30 +08:00
-												Update README with installation instructions

Add SPM and CocoaPods
											
										
										
											2017-09-23 04:47:28 +08:00
+								To use [Swift Package Manager](https://swift.org/package-manager/) add Surge to your `Package.swift` file:
 								```swift
 								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](https://cocoapods.org) add Surge to your `Podfile`:
-												Update README w Carthage compatibility

											
										
										
											2017-05-08 15:20:30 +08:00
 								```ruby
-												Update README with installation instructions

Add SPM and CocoaPods
											
										
										
											2017-09-23 04:47:28 +08:00
+								source 'https://github.com/CocoaPods/Specs.git'
 								platform :ios, '10.0'
 								use_frameworks!
 								target '<Your Target Name>' do
 								    pod 'Surge', '~> 2.0.0'
 								end
-												Update README w Carthage compatibility

											
										
										
											2017-05-08 15:20:30 +08:00
+								```
-												Update README with installation instructions

Add SPM and CocoaPods
											
										
										
											2017-09-23 04:47:28 +08:00
+								Then run `pod install`.
 								### Carthage
-												Update README w Carthage compatibility

											
										
										
											2017-05-08 15:20:30 +08:00
-												Update README with installation instructions

Add SPM and CocoaPods
											
										
										
											2017-09-23 04:47:28 +08:00
+								To use [Carthage](https://github.com/Carthage/Carthage) add Surge to your `Cartfile`:
 								```ruby
 								github "mattt/Surge" ~> 2.0.0
 								```
-												Update README w Carthage compatibility

											
										
										
											2017-05-08 15:20:30 +08:00
-												Update README with installation instructions

Add SPM and CocoaPods
											
										
										
											2017-09-23 04:47:28 +08:00
+								Then run `carthage update` and use the framework in `Carthage/Build/<platform>`.
-												Update README w Carthage compatibility

											
										
										
											2017-05-08 15:20:30 +08:00
-												Initial Commit

											
										
										
											2014-08-24 14:02:33 +08:00
+								---
 								## Usage
 								### Computing Sum of `[Double]`
 								```swift
 								import Surge
-												[Issue #2] Using floating point literals in examples
											
										
										
											2014-08-27 03:04:01 +08:00
+								let n = [1.0, 2.0, 3.0, 4.0, 5.0]
-												Correct a name collision.
											
										
										
											2014-08-25 00:30:10 +08:00
+								let sum = Surge.sum(n) // 15.0
-												Initial Commit

											
										
										
											2014-08-24 14:02:33 +08:00
+								```
 								### Computing Product of Two `[Double]`s
 								```swift
 								import Surge
-												[Issue #2] Using floating point literals in examples
											
										
										
											2014-08-27 03:04:01 +08:00
+								let a = [1.0, 3.0, 5.0, 7.0]
 								let b = [2.0, 4.0, 6.0, 8.0]
-												Initial Commit

											
										
										
											2014-08-24 14:02:33 +08:00
-												Update README.md
											
										
										
											2014-08-25 08:20:46 +08:00
+								let product = Surge.mul(a, b) // [2.0, 12.0, 30.0, 56.0]
-												Initial Commit

											
										
										
											2014-08-24 14:02:33 +08:00
+								```
-												Moved improved ‘Inventory’ back into README

											
										
										
											2019-08-30 06:47:06 +08:00
+								# Inventory
 								- [General Arithmetic Operations](#general-arithmetic-operations)
 								  - [Addition](#addition)
 								  - [Subtraction](#subtraction)
 								  - [Multiplication](#multiplication)
 								  - [Element-wise multiplication](#element-wise-multiplication)
 								  - [Division)](#division)
 								  - [Element-wise Division)](#element-wise-division)
 								  - [Modulo](#modulo)
 								  - [Remainder](#remainder)
 								  - [Square Root](#square-root)
 								  - [Summation](#summation)
 								  - [Dot Product](#dot-product)
 								  - [Distance](#distance)
 								  - [Squared Distance](#squared-distance)
 								  - [Power)](#power)
 								  - [Exponential](#exponential)
 								- [Trigonometric Operations](#trigonometric-operations)
 								  - [Sine/Cosine/Tangent](#sinecosinetangent)
 								  - [Arc Sine/Cosine/Tangent](#arc-sinecosinetangent)
 								  - [Hyperbolic Sine/Cosine/Tangent](#hyperbolic-sinecosinetangent)
 								  - [Inverse Hyperbolic Sine/Cosine/Tangent](#inverse-hyperbolic-sinecosinetangent)
 								  - [Radians ↔︎ Degrees](#radians-%e2%86%94%ef%b8%8e-degrees)
 								- [Exponential Function](#exponential-function)
 								- [Logarithm](#logarithm)
 								- [Statistical Operations](#statistical-operations)
 								  - [Summation](#summation-1)
 								  - [Minimum/Maximum](#minimummaximum)
 								  - [Mean](#mean)
 								- [Auxiliary Functions](#auxiliary-functions)
 								  - [Rounding Functions](#rounding-functions)
 								  - [Absolute value](#absolute-value)
 								  - [Signum function](#signum-function)
 								  - [Multiplicative inverse](#multiplicative-inverse)
 								- [Matrix-specific Operations](#matrix-specific-operations)
 								  - [Matrix Inversion](#matrix-inversion)
 								  - [Matrix Transposition](#matrix-transposition)
 								  - [Matrix Determinant](#matrix-determinant)
 								  - [Eigen Decomposition](#eigen-decomposition)
 								- [DSP-specific Operations](#dsp-specific-operations)
 								  - [Fast Fourier Transform](#fast-fourier-transform)
 								  - [Convolution](#convolution)
 								  - [Cross-Correlation](#cross-correlation)
 								## General Arithmetic Operations
 								### [Addition](https://en.wikipedia.org/wiki/Addition)
 								<details open>
 								<summary>
 								Addition functions & operators
 								</summary>
-												Removed `func ` from inventory

											
										
										
											2019-08-30 22:55:07 +08:00
+								| 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)      |
-												Moved improved ‘Inventory’ back into README

											
										
										
											2019-08-30 06:47:06 +08:00
 								<!--
 								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](https://en.wikipedia.org/wiki/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)  | n/a               |
 								| `(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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/Multiplication)
 								<details open>
 								<summary>
 								Element-wise multiplication functions & operators
 								</summary>
 								| Arguments          | Function | Operator     | In-Place Operator |
 								|--------------------|----------|--------------|-------------------|
 								| `(Matrix, Matrix)` | `elmul`  | n/a          | n/a               |
 								| `(Vector, Vector)` | `elmul`  | `.*` (infix) | `.*=` (infix)     |
 								<!--
 								Internal use only:
 								| In-Place Function |
 								|-------------------|
 								| n/a               |
 								| `elmulInPlace`    |
 								-->
 								<!-- FIXME: The does not seem to be a `.*` implemented for `(Matrix, Matrix)`. -->
 								</details>
 								### [Division](https://en.wikipedia.org/wiki/Division_(mathematics))
 								<details open>
 								<summary>
 								Division functions & operators
 								</summary>
 								| 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)      |
 								<!--
 								Internal use only:
 								| In-Place Function |
 								|-------------------|
 								| `divInPlace`      |
 								| `divInPlace`      |
 								| n/a               |
 								| n/a               |
 								| `divInPlace`      |
 								-->
 								<!-- FIXME: Func `div` of `(Array, Array)` should be called `eldiv`, no? -->
 								<!-- FIXME: Missing `div` function for `(Matrix, Scalar)`. -->
 								</details>
 								### [Element-wise Division](https://en.wikipedia.org/wiki/Division_(mathematics))
 								<details open>
 								<summary>
 								Element-wise multiplication functions & operators
 								</summary>
 								| Arguments          | Function | Operator     | In-Place Operator |
 								|--------------------|----------|--------------|-------------------|
 								| `(Vector, Vector)` | `eldiv`  | `./` (infix) | `./=` (infix)     |
 								<!--
 								Internal use only:
 								| In-Place Function |
 								|-------------------|
 								| `eldivInPlace`    |
 								 -->
 								</details>
 								### [Modulo](https://en.wikipedia.org/wiki/Modulo_operation)
 								<details open>
 								<summary>
 								Modulo functions & operators
 								</summary>
 								| Arguments         | Function | Operator     | In-Place Operator |
 								|-------------------|----------|--------------|-------------------|
 								| `(Array, Array)`  | `mod`    | `.%` (infix) | n/a               |
 								| `(Array, Scalar)` | `mod`    | `%` (infix)  | n/a               |
 								<!--
 								Internal use only:
 								| In-Place Function |
 								|-------------------|
 								| n/a               |
 								| n/a               |
 								-->
 								<!-- FIXME: Do we need `mod` functions/operators for `Matrix`? -->
 								<!-- FIXME: Do we need `mod` functions/operators for `Vector`? -->
 								</details>
 								### [Remainder](https://en.wikipedia.org/wiki/Remainder)
 								<details open>
 								<summary>
 								Remainder functions & operators
 								</summary>
 								| Arguments         | Function    | Operator | In-Place Operator |
 								|-------------------|-------------|----------|-------------------|
 								| `(Array, Array)`  | `remainder` | n/a      | n/a               |
 								| `(Array, Scalar)` | `remainder` | n/a      | n/a               |
 								<!--
 								Internal use only:
 								| In-Place Function |
 								|-------------------|
 								| n/a               |
 								| n/a               |
 								 -->
 								<!-- FIXME: Do we need `remainder` functions /operators for `Matrix`? -->
 								<!-- FIXME: Do we need `remainder` functions /operators for `Vector`? -->
 								</details>
 								### [Square Root](https://en.wikipedia.org/wiki/Square_root)
 								<details open>
 								<summary>
 								Square root functions & operators
 								</summary>
 								| Arguments | Function | Operator | In-Place Operator |
 								|-----------|----------|----------|-------------------|
 								| `(Array)` | `sqrt`   | n/a      | n/a               |
 								<!--
 								Internal use only:
 								| In-Place Function |
 								|-------------------|
 								| n/a               |
 								 -->
 								<!-- FIXME: The seems to be a variant `func sqrt<MI, MO>(_ x: MI, into results: inout MO)` that could be made into a `sqrtInPlace`-->
 								<!-- FIXME: Do we need `sqrt` functions/operators for `Matrix`? -->
 								<!-- FIXME: Do we need `sqrt` functions/operators for `Vector`? -->
 								</details>
 								### [Summation](https://en.wikipedia.org/wiki/Summation)
 								<details open>
 								<summary>
 								Sum functions & operators
 								</summary>
 								| Arguments  | Function | Operator | In-Place Operator |
 								|------------|----------|----------|-------------------|
 								| `(Array)`  | `sum`    | n/a      | n/a               |
 								| `(Matrix)` | `sum`    | n/a      | n/a               |
 								<!--
 								Internal use only:
 								| In-Place Function |
 								|-------------------|
 								| n/a               |
 								| n/a               |
 								 -->
 								<!-- FIXME: Do we need `sum` functions/operators for `Vector`? -->
 								</details>
 								### [Dot Product](https://en.wikipedia.org/wiki/Dot_product)
 								<details open>
 								<summary>
 								Dot product functions & operators
 								</summary>
 								| Arguments          | Function | Operator    | In-Place Operator |
 								|--------------------|----------|-------------|-------------------|
 								| `(Array, Array)`   | `dot`    | `•` (infix) | n/a               |
 								| `(Vector, Vector)` | `dot`    | `•` (infix) | n/a               |
 								<!--
 								Internal use only:
 								| In-Place Function |
 								|-------------------|
 								| n/a               |
 								| n/a               |
 								 -->
 								<!-- FIXME: Do we need `dot` functions/operators for `Matrix`? -->
 								</details>
 								### [Distance](https://en.wikipedia.org/wiki/Euclidean_distance)
 								<details open>
 								<summary>
 								Distance functions & operators
 								</summary>
 								| Arguments          | Function | Operator | In-Place Operator |
 								|--------------------|----------|----------|-------------------|
 								| `(Array, Array)`   | `dist`   | n/a      | n/a               |
 								| `(Vector, Vector)` | `dist`   | n/a      | n/a               |
 								<!--
 								Internal use only:
 								| In-Place Function |
 								|-------------------|
 								| n/a               |
 								| n/a               |
 								 -->
 								### [Squared Distance](https://en.wikipedia.org/wiki/Euclidean_distance#Squared_Euclidean_distance)
 								<details open>
 								<summary>
 								Squared distance functions & operators
 								</summary>
 								| Arguments          | Function | Operator | In-Place Operator |
 								|--------------------|----------|----------|-------------------|
 								| `(Array, Array)`   | `distSq` | n/a      | n/a               |
 								| `(Vector, Vector)` | `distSq` | n/a      | n/a               |
 								<!--
 								Internal use only:
 								| In-Place Function |
 								|-------------------|
 								| n/a               |
 								| n/a               |
 								 -->
 								</details>
 								### [Power](https://en.wikipedia.org/wiki/Power_(mathematics))
 								<details open>
 								<summary>
 								Power functions & operators
 								</summary>
 								| 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               |
 								<!--
 								Internal use only:
 								| In-Place Function |
 								|-------------------|
 								| n/a               |
 								| n/a               |
 								| n/a               |
 								| n/a               |
 								 -->
 								<!-- FIXME: Shouldn't the `pow`/`**` function/operator of `(Array, Array)` be `elpow`/`.**`? -->
 								<!-- FIXME: Shouldn't the `pow`/`**` function/operator of `(Vector, Vector)` be `elpow`/`.**`? -->
 								<!-- FIXME: The does not seem to be a corresponding `.**` operator implemented. -->
 								<!-- FIXME: Do we need `pow` functions/operators for `(Vector, Scalar)`? -->
 								### [Exponential](https://en.wikipedia.org/wiki/Exponential_function)
 								<details open>
 								<summary>
 								Exponential functions & operators
 								</summary>
 								| Arguments  | Function | Operator | In-Place Operator |
 								|------------|----------|----------|-------------------|
 								| `(Array)`  | `exp`    | n/a      | n/a               |
 								| `(Matrix)` | `exp`    | n/a      | n/a               |
 								| `(Vector)` | `exp`    | n/a      | n/a               |
 								<!--
 								Internal use only:
 								| In-Place Function |
 								|-------------------|
 								| n/a               |
 								| n/a               |
 								| n/a               |
 								 -->
 								</details>
 								## Trigonometric Operations
 								<details open>
 								<summary>
 								Trigonometric functions & operators
 								</summary>
 								### [Sine/Cosine/Tangent](https://en.wikipedia.org/wiki/Trigonometric_functions)
 								| Arguments | Function | Operation     |
 								|-----------|----------|---------------|
 								| `(Array)` | `sin`    | Sine          |
 								| `(Array)` | `cos`    | Cosine        |
 								| `(Array)` | `tan`    | Tangent       |
 								| `(Array)` | `sincos` | Sine & Cosine |
 								### [Arc Sine/Cosine/Tangent](https://en.wikipedia.org/wiki/Trigonometric_functions)
 								| Arguments | Function | Operation   |
 								|-----------|----------|-------------|
 								| `(Array)` | `asin`   | Arc Sine    |
 								| `(Array)` | `acos`   | Arc Cosine  |
 								| `(Array)` | `atan`   | Arc Tangent |
 								### [Hyperbolic Sine/Cosine/Tangent](https://en.wikipedia.org/wiki/Hyperbolic_function)
 								| Arguments | Function | Operation          |
 								|-----------|----------|--------------------|
 								| `(Array)` | `sinh`   | Hyperbolic Sine    |
 								| `(Array)` | `cosh`   | Hyperbolic Cosine  |
 								| `(Array)` | `tanh`   | Hyperbolic Tangent |
 								### [Inverse Hyperbolic Sine/Cosine/Tangent](https://en.wikipedia.org/wiki/Inverse_hyperbolic_functions)
 								| Arguments | Function | Operation                  |
 								|-----------|----------|----------------------------|
 								| `(Array)` | `asinh`  | Inverse Hyperbolic Sine    |
 								| `(Array)` | `acosh`  | Inverse Hyperbolic Cosine  |
 								| `(Array)` | `atanh`  | Inverse Hyperbolic Tangent |
 								### [Radians ↔︎ Degrees](https://en.wikipedia.org/wiki/Angle#Types_of_angles)
 								| Arguments | Function  | Operation                                                                                                  |
 								|-----------|-----------|------------------------------------------------------------------------------------------------------------|
 								| `(Array)` | `rad2deg` | [Radians](https://en.wikipedia.org/wiki/Radian) to [Degrees](https://en.wikipedia.org/wiki/Degree_(angle)) |
 								| `(Array)` | `deg2rad` | [Degrees](https://en.wikipedia.org/wiki/Degree_(angle)) to [Radians](https://en.wikipedia.org/wiki/Radian) |
 								</details>
 								## [Exponential Function](https://en.wikipedia.org/wiki/Exponential_function)
 								<details open>
 								<summary>
 								Exponential functions & operators
 								</summary>
 								| Arguments | Function | Operation                   |
 								|-----------|----------|-----------------------------|
 								| `(Array)` | `exp`    | Base-e Exponential Function |
 								| `(Array)` | `exp2`   | Base-2 Exponential Function |
 								</details>
 								## [Logarithm](https://en.wikipedia.org/wiki/Logarithm)
 								<details open>
 								<summary>
 								Exponential functions & operators
 								</summary>
 								| Arguments | Function | Operation         |
 								|-----------|----------|-------------------|
 								| `(Array)` | `log`    | Base-e Logarithm  |
 								| `(Array)` | `log2`   | Base-2 Logarithm  |
 								| `(Array)` | `log10`  | Base-10 Logarithm |
 								| `(Array)` | `logb`   | Base-b Logarithm  |
 								</details>
 								## Statistical Operations
 								<details open>
 								<summary>
 								Statistical functions & operators
 								</summary>
 								### [Summation](https://en.wikipedia.org/wiki/Summation)
 								| Arguments | Function | Operation          |
 								|-----------|----------|--------------------|
 								| `(Array)` | `sum`    | Summation          |
 								| `(Array)` | `asum`   | Absolute Summation |
 								### [Minimum/Maximum](https://en.wikipedia.org/wiki/Maximal_and_minimal_elements)
 								| Arguments | Function | Operation |
 								|-----------|----------|-----------|
 								| `(Array)` | `min`    | Minimum   |
 								| `(Array)` | `max`    | Maximum   |
 								### [Mean](https://en.wikipedia.org/wiki/Mean)
 								| Arguments | Function | Operation                                                    |
 								|-----------|----------|--------------------------------------------------------------|
 								| `(Array)` | `mean`   | [Mean](https://en.wikipedia.org/wiki/Mean)                   |
 								| `(Array)` | `meamg`  | Mean of Magnitudes                                           |
 								| `(Array)` | `measq`  | [Mean of squares](https://en.wikipedia.org/wiki/Mean_square) |
 								</details>
 								## Auxiliary Functions
 								<details open>
 								<summary>
 								Auxiliary functions & operators
 								</summary>
 								### [Rounding Functions](https://en.wikipedia.org/wiki/Rounding)
 								| Arguments | Function | Operation                                                             |
 								|-----------|----------|-----------------------------------------------------------------------|
 								| `(Array)` | `ceil`   | [Ceiling](https://en.wikipedia.org/wiki/Floor_and_ceiling_functions)  |
 								| `(Array)` | `floor`  | [Flooring](https://en.wikipedia.org/wiki/Floor_and_ceiling_functions) |
 								| `(Array)` | `round`  | [Rounding](https://en.wikipedia.org/wiki/Rounding)                    |
 								| `(Array)` | `trunc`  | [Integer truncation](https://en.wikipedia.org/wiki/Truncation)        |
 								### [Absolute value](https://en.wikipedia.org/wiki/Absolute_value)
 								| Arguments | Function | In-Place Function | Operator | In-Place Operator |
 								|-----------|----------|-------------------|----------|-------------------|
 								| `(Array)` | `abs`    | n/a               | n/a      | n/a               |
 								### [Signum function](https://en.wikipedia.org/wiki/Sign_function)
 								| Arguments | Function   | In-Place Function | Operator | In-Place Operator |
 								|-----------|------------|-------------------|----------|-------------------|
 								| `(Array)` | `copysign` | n/a               | n/a      | n/a               |
 								### [Multiplicative inverse](https://en.wikipedia.org/wiki/Multiplicative_inverse)
 								| Arguments | Function | In-Place Function | Operator | In-Place Operator |
 								|-----------|----------|-------------------|----------|-------------------|
 								| `(Array)` | `rec`    | n/a               | n/a      | n/a               |
 								</details>
 								## Matrix-specific Operations
 								<details open>
 								<summary>
 								Matrix-specific functions & operators
 								</summary>
 								### [Matrix Inversion](https://en.wikipedia.org/wiki/Invertible_matrix)
 								| Arguments  | Function | In-Place Function | Operator | In-Place Operator |
 								|------------|----------|-------------------|----------|-------------------|
 								| `(Matrix)` | `inv`    | n/a               | n/a      | n/a               |
 								### [Matrix Transposition](https://en.wikipedia.org/wiki/Matrix_transpose)
 								| Arguments  | Function    | In-Place Function | Operator      | In-Place Operator |
 								|------------|-------------|-------------------|---------------|-------------------|
 								| `(Matrix)` | `transpose` | n/a               | `′` (postfix) | n/a               |
 								### [Matrix Determinant](https://en.wikipedia.org/wiki/Matrix_determinant)
 								| Arguments  | Function | In-Place Function | Operator | In-Place Operator |
 								|------------|----------|-------------------|----------|-------------------|
 								| `(Matrix)` | `det`    | n/a               | n/a      | n/a               |
 								### [Eigen Decomposition](https://en.wikipedia.org/wiki/Eigen_decomposition)
 								| Arguments  | Function         | In-Place Function | Operator | In-Place Operator |
 								|------------|------------------|-------------------|----------|-------------------|
 								| `(Matrix)` | `eigenDecompose` | n/a               | n/a      | n/a               |
 								</details>
 								## DSP-specific Operations
 								<details open>
 								<summary>
 								Fast fourier transform functions & operators
 								</summary>
 								### [Fast Fourier Transform](https://en.wikipedia.org/wiki/Convolution)
 								| Arguments | Function | In-Place Function | Operator | In-Place Operator |
 								|-----------|----------|-------------------|----------|-------------------|
 								| `(Array)` | `fft`    | n/a               | n/a      | n/a               |
 								### [Convolution](https://en.wikipedia.org/wiki/Convolution)
 								| Arguments        | Function | In-Place Function | Operator | In-Place Operator |
 								|------------------|----------|-------------------|----------|-------------------|
 								| `(Array, Array)` | `conv`   | n/a               | n/a      | n/a               |
 								### [Cross-Correlation](https://en.wikipedia.org/wiki/Cross-correlation)
-												Initial Commit

											
										
										
											2014-08-24 14:02:33 +08:00
-												Moved improved ‘Inventory’ back into README

											
										
										
											2019-08-30 06:47:06 +08:00
+								| 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               |
-												Initial Commit

											
										
										
											2014-08-24 14:02:33 +08:00
-												Moved improved ‘Inventory’ back into README

											
										
										
											2019-08-30 06:47:06 +08:00
+								</details>