# Upsurge

Upsurge implements multi-dimensional data structures and operations. It brings numpy-like operations to Swift.

Upsurge no longer supports DSP and other linear operations, please use [Surge](https://github.com/mattt/Surge) for that. Surge and Upsurge play nice together. 

## Features

- [x] Tensor and tensor slicing: `tensor.asMatrix(1, 1, 0...4, 0...4)`
- [x] Matrix and matrix operations: `let result = A * B′`
- [x] ValueArrays with explicit copying and numeric operators: `let result = A • B`


## Installation

Upsurge supports both CocoaPods (`pod 'Upsurge'`) and Carthage (`github "aleph7/Upsurge"`).  For macOS apps you can use the Swift Package Manager to install Upsurge by adding the proper description to your Package.swift file:

```swift
import PackageDescription

let package = Package(
    name: "YOUR_PROJECT_NAME",
    targets: [],
    dependencies: [
        .Package(url: "https://github.com/aleph7/Upsurge.git", Version(0,8,.max)),
    ]
)
```

## Usage

### Arrays and vector operations

All of Upsurge's linear (1-dimensional) operations can be performed on anything that conforms to `LinearType`. Swift's built-in arrays and array slices conform to `LinearType`, of course. But Upsurge also defines the `ValueArray` class to store a one-dimensional collection of values. `ValueArray` is very similar to Swift's `Array` but it is optimized to reduce unnecessary memory allocation. These are the most important differences:
* Its instances have a fixed size defined on creation. When you create a `ValueArray` you can define a capacity `var a = ValueArray<Double>(capacity: 100)` and then append elements up to that capacity. **Or** you can create it with specific elements `var a: ValueArray = [1.0, 2.0, 3.0]` but then you can't add any more elements after.
* It is a class. That means that creating a new variable will only create a reference and modifying the reference will also modify the original. For instance doing `var a: ValueArray = [1, 2, 3]; var b = a` and then `b[0] = 5` will result in `a` being `[5, 2, 3]`. If you want to create a copy you need to do `var b = ValueArray(a)` or `var b = a.copy()`.
* You **can** create an uninitialized `ValueArray` by doing `var a = ValueArray<Double>(capacity: n)` or `var a = ValueArray<Doube>(count: n)`. This is good for when you are going to fill up the array yourself. But you can also use `var a = ValueArray(count: n, repeatedValue: 0.0)` if you do want to initialize all the values.

#### Creating arrays

Create a `ValueArray` with specific literal elements when you know ahead of time what the contents are, and you don't need to add more elements at a later time:
```swift
let a: ValueArray = [1.0, 3.0, 5.0, 7.0]
```

Create a `ValueArray` with a capacity and then fill it in when you are loading the contents from an external source or have a very large array:
```swift
let a = ValueArray<Double>(capacity: 100)
for v in intputSource {
    a.append(v)
}
```

Finally there is a way of initializing both the capacity and the count of a `ValueArray`. You should rarely need this but it's there for when you are doing operations on existing arrays using low-level APIs that take pointers:
```swift
func operation(a: ValueArray<Double>) {
    let N = a.count
    let b = ValueArray<Double>(count: N)
    // ...
}
```

#### Vector arithmetic

You can perform operations on `ValueArray` in an intuitive manner:
```swift
let a: ValueArray = [1.0, 3.0, 5.0, 7.0]
let b: ValueArray = [2.0, 4.0, 6.0, 8.0]
let addition = a + b // [3.0, 7.0, 11.0, 15.0]
let product  = a • b // 100.0

```


### Matrix operations

```swift
import Upsurge

let A = Matrix<Double>([
    [1,  1],
    [1, -1]
])
let C = Matrix<Double>([
    [3],
    [1]
])

// find B such that A*B=C
let B = inv(A) * C // [2.0, 1.0]′

// Verify result
let r = A*B - C    // zero   
```

### Tiling
A block  `Matrix`  can be formed by repeating a 1-D `ValueArray` or 2-D `Matrix`  **mxn** times.

```swift
import Upsurge

let a = ValueArray = [1.0, 2.0]
// Tile source array 2 times in each directon,
// returning a 2X4 block matrix
let A = a.tile(2, 2)

let B = Matrix<Double>([
    [1.0,  2.0],
    [3.0,  4.0]
)]
// Tile source matrix 2 times in each directon,
// returning a 4x4 block matrix
let r = B.tile(2, 2)
```

### Tensors

The `Tensor` class makes it easy to manipulate multi-dimensional data. You can easily slice or flatten a tensor to get matrices and vectors that you can operate on.


---

## License

Upsurge is available under the MIT license. See the LICENSE file for more info.