Merge pull request #159 from arrayfire/devel

v3.5.0 devel to master
arrayfire · Jun 28, 2017 · 289e9dc · 289e9dc
2 parents 2609c90 + 8db332e
commit 289e9dc
Show file tree

Hide file tree

Showing 23 changed files with 1,432 additions and 190 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name          = "arrayfire"
 description   = "ArrayFire is a high performance software library for parallel computing with an easy-to-use API. Its array based function set makes parallel programming simple. ArrayFire's multiple backends (CUDA, OpenCL and native CPU) make it platform independent and highly portable. A few lines of code in ArrayFire can replace dozens of lines of parallel computing code, saving you valuable time and lowering development costs. This crate provides Rust bindings for ArrayFire library."
-version       = "3.4.3"
+version       = "3.5.0"
 documentation = "http://arrayfire.github.io/arrayfire-rust/arrayfire/index.html"
 homepage      = "https://github.com/arrayfire/arrayfire"
 repository    = "https://github.com/arrayfire/arrayfire-rust"
@@ -14,13 +14,33 @@ exclude = [
     "arrayfire/*",
 ]
 
+[features]
+algorithm = []
+arithmetic = []
+blas = []
+data = []
+indexing = []
+graphics = []
+image = []
+lapack = []
+macros = []
+random = []
+signal = []
+sparse = []
+statistics = []
+vision = []
+default = ["algorithm", "arithmetic", "blas", "data", "indexing", "graphics", "image", "lapack",
+"macros", "random", "signal", "sparse", "statistics", "vision"]
+
 [dependencies]
 libc = "0.2.11"
 num  = "0.1.32"
 lazy_static = "0.2.1"
 
 [build-dependencies]
-rustc-serialize = "0.3.19"
+serde_json = "1.0.0"
+serde_derive = "1.0.1"
+serde = "1.0.1"
 rustc_version = "0.1.7"
 
 [lib]

diff --git a/README.md b/README.md
@@ -18,13 +18,7 @@ You can find the most recent updated documentation [here](http://arrayfire.githu
 
 ## Supported platforms
 
-- Linux and OSX: The bindings have been tested with Rust 1.x.
-- Windows: Rust 1.5 (MSVC ABI) is the first version that works with our bindings and ArrayFire library(built using MSVC compiler).
-
-We recommend using Rust 1.5 and higher.
-
-Rust 1.8 stabilized the traits for compound assignment operations. These are automatically enabled
-based on the rust version you are using.
+Linux, Windows and OSX. Rust 1.15.1 or higher is required.
 
 ## Use from Crates.io [![](http://meritbadge.herokuapp.com/arrayfire)](https://crates.io/crates/arrayfire)
 
@@ -37,7 +31,7 @@ first.
 3. Make sure you add the path to library files to your path environment variables.
     - On Linux & OSX: do `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$AF_PATH/lib`
     - On Windows: Add `%AF_PATH%\lib` to your PATH environment variable.
-4. Add `arrayfire = "3.4.3"` to the dependencies section of your project's Cargo.toml file - 3.4.3
+4. Add `arrayfire = "3.5.0"` to the dependencies section of your project's Cargo.toml file - 3.5.0
    is the lastest version of crate.
 
 Once step (4) is over, you should be able to use ArrayFire in your Rust project. If you find any bugs, please report them [here](https://github.com/arrayfire/arrayfire-rust/issues).
@@ -75,7 +69,6 @@ af_print!("Create a 5-by-3 matrix of random floats on the GPU", a);
 ```bash
 ~/p/arrayfire_rust> cargo run --example helloworld
 ...
-     running 1 test
 Create a 5-by-3 matrix of random floats on the GPU
 [5 3 1 1]
     0.7402     0.4464     0.7762

diff --git a/arrayfire b/arrayfire
diff --git a/build.rs b/build.rs
@@ -1,10 +1,13 @@
 /* -- Lots of reuse from: https://github.com/alexcrichton/git2-rs/blob/master/libgit2-sys/build.rs */
-extern crate rustc_serialize;
+#[macro_use]
+extern crate serde_derive;
+
+extern crate serde;
+extern crate serde_json;
 extern crate rustc_version;
 
 use std::env;
 use std::fs;
-use rustc_serialize::json;
 use std::fs::OpenOptions;
 use std::io::{ErrorKind, Read};
 use std::path::PathBuf;
@@ -21,7 +24,7 @@ static UNIX_OCL_LIB_NAME: &'static str = "libafopencl";
 static UNIX_UNI_LIB_NAME: &'static str = "libaf";
 
 #[allow(dead_code)]
-#[derive(RustcDecodable)]
+#[derive(Deserialize, Debug)]
 struct Config {
     // Use the existing lib if it exists
     use_lib: bool,
@@ -55,13 +58,6 @@ struct Config {
     opencl_sdk: String,
 }
 
-macro_rules! t {
-    ($e:expr) => (match $e {
-            Ok(n) => n,
-            Err(e) => fail(&format!("\n{} failed with {}\n", stringify!($e), e)),
-        })
-}
-
 fn fail(s: &str) -> ! {
     panic!("\n{}\n\nbuild script failed, must exit now", s)
 }
@@ -116,7 +112,7 @@ fn read_file(file_name: &std::path::PathBuf) -> String {
 
 fn read_conf(conf_file: &std::path::PathBuf) -> Config {
     let raw_conf = read_file(conf_file);
-    let decoded: Config = json::decode(&raw_conf).unwrap();
+    let decoded: Config = serde_json::from_str(&raw_conf).unwrap();
     decoded
 }
 

diff --git a/doc/array_and_matrix_manipulation.md b/doc/array_and_matrix_manipulation.md
@@ -0,0 +1,271 @@
+% Array and Matrix Manipulation
+
+ArrayFire provides several different methods for manipulating arrays and matrices.
+The functionality includes:
+
+* [moddims()](#moddims) - change the dimensions of an array without changing the data
+* [flat()](#flat) - flatten an array to one dimension
+* [flip()](#flip) - flip an array along a dimension
+* [join()](#join) - join up to 4 arrays
+* [reorder()](#reorder) - changes the dimension order within the array
+* [shift()](#shift) - shifts data along a dimension
+* [tile()](#tile) - repeats an array along a dimension
+* [transpose()](#transpose) - performs a matrix transpose
+
+Below we provide several examples of these functions and their use.
+
+### moddims()
+
+The [moddims](./fn.moddims.html) function changes the dimensions of an array without
+changing its data or order. Note that this function modifies only the _metadata_
+associated with the array. It does not modify the content of the array.
+Here is an example of moddims() converting an 8x1 array into a 2x4 and then
+back to a 8x1:
+
+```rust
+a [8 1 1 1]
+    1.0000
+    2.0000
+    1.0000
+    2.0000
+    1.0000
+    2.0000
+    1.0000
+    2.0000
+
+let new_dims = Dim4::new(&[2, 4, 1, 1]);
+moddims(&a, new_dims)
+[2 4 1 1]
+    1.0000     1.0000     1.0000     1.0000
+    2.0000     2.0000     2.0000     2.0000
+
+let out = moddims(&a, a.elements(), 1, 1, 1);
+[8 1 1 1]
+    1.0000
+    2.0000
+    1.0000
+    2.0000
+    1.0000
+    2.0000
+    1.0000
+    2.0000
+```
+
+### flat()
+
+The [flat](./fn.flat.html) function flattens an array to one dimension:
+
+```
+a [3 3 1 1]
+    1.0000     4.0000     7.0000
+    2.0000     5.0000     8.0000
+    3.0000     6.0000     9.0000
+
+flat(&a)
+[9 1 1 1]
+    1.0000
+    2.0000
+    3.0000
+    4.0000
+    5.0000
+    6.0000
+    7.0000
+    8.0000
+    9.0000
+```
+
+### flip()
+
+The [flip](./fn.flip.html) function flips the contents of an array along a
+chosen dimension. In the example below, we show the 5x2 array flipped
+along the zeroth (i.e. within a column) and first (e.g. across rows) axes:
+
+```rust
+a [5 2 1 1]
+    1.0000     6.0000
+    2.0000     7.0000
+    3.0000     8.0000
+    4.0000     9.0000
+    5.0000    10.0000
+
+flip(a, 0) [5 2 1 1]
+    5.0000    10.0000
+    4.0000     9.0000
+    3.0000     8.0000
+    2.0000     7.0000
+    1.0000     6.0000
+
+flip(a, 1) [5 2 1 1]
+    6.0000     1.0000
+    7.0000     2.0000
+    8.0000     3.0000
+    9.0000     4.0000
+   10.0000     5.0000
+```
+
+### join()
+
+The [join](./fn.join.html), [join_many](./fn.join_many.html) functions can be
+used to join arrays along a specific dimension.
+
+Here is an example of how to use join an array to itself:
+
+```rust
+a [5 1 1 1]
+    1.0000
+    2.0000
+    3.0000
+    4.0000
+    5.0000
+
+join(0, a, a) [10 1 1 1]
+    1.0000
+    2.0000
+    3.0000
+    4.0000
+    5.0000
+    1.0000
+    2.0000
+    3.0000
+    4.0000
+    5.0000
+
+join(1, a, a) [5 2 1 1]
+    1.0000     1.0000
+    2.0000     2.0000
+    3.0000     3.0000
+    4.0000     4.0000
+    5.0000     5.0000
+```
+
+### reorder()
+
+The [reorder](./fn.reorder.html) function modifies the order of data within an array by
+exchanging data according to the change in dimensionality. The linear ordering
+of data within the array is preserved.
+
+```rust
+a [2 2 3 1]
+    1.0000     3.0000
+    2.0000     4.0000
+
+    1.0000     3.0000
+    2.0000     4.0000
+
+    1.0000     3.0000
+    2.0000     4.0000
+
+
+reorder(&a, 1, 0, 2)
+[2 2 3 1]  //equivalent to a transpose
+    1.0000     2.0000
+    3.0000     4.0000
+
+    1.0000     2.0000
+    3.0000     4.0000
+
+    1.0000     2.0000
+    3.0000     4.0000
+
+
+reorder(&a, 2, 0, 1)
+[3 2 2 1]
+    1.0000     2.0000
+    1.0000     2.0000
+    1.0000     2.0000
+
+    3.0000     4.0000
+    3.0000     4.0000
+    3.0000     4.0000
+```
+
+### shift()
+
+The [shift](./fn.shift.html) function shifts data in a circular buffer fashion along a
+chosen dimension. Consider the following example:
+
+```rust
+a [3 5 1 1]
+    0.0000     0.0000     0.0000     0.0000     0.0000
+    3.0000     4.0000     5.0000     1.0000     2.0000
+    3.0000     4.0000     5.0000     1.0000     2.0000
+
+shift(&a, 0, 2 )
+[3 5 1 1]
+    0.0000     0.0000     0.0000     0.0000     0.0000
+    1.0000     2.0000     3.0000     4.0000     5.0000
+    1.0000     2.0000     3.0000     4.0000     5.0000
+
+shift(&a, -1, 2 )
+[3 5 1 1]
+    1.0000     2.0000     3.0000     4.0000     5.0000
+    1.0000     2.0000     3.0000     4.0000     5.0000
+    0.0000     0.0000     0.0000     0.0000     0.0000
+```
+
+### tile()
+
+The [tile](./fn.tile.html) function repeats an array along the specified dimension.
+For example below we show how to tile an array along the zeroth and first
+dimensions of an array:
+
+```rust
+a [3 1 1 1]
+    1.0000
+    2.0000
+    3.0000
+
+// Repeat array a twice in the zeroth dimension
+tile(&a, 2)
+[6 1 1 1]
+    1.0000
+    2.0000
+    3.0000
+    1.0000
+    2.0000
+    3.0000
+
+// Repeat array a twice along both the zeroth and first dimensions
+tile(&a, 2, 2)
+[6 2 1 1]
+    1.0000     1.0000
+    2.0000     2.0000
+    3.0000     3.0000
+    1.0000     1.0000
+    2.0000     2.0000
+    3.0000     3.0000
+
+// Repeat array a twice along the first and three times along the second
+// dimension.
+let tile_dims = Dim4::new(&[1, 2, 3, 1]);
+tile(a, tile_dims) [3 2 3 1]
+    1.0000     1.0000
+    2.0000     2.0000
+    3.0000     3.0000
+
+    1.0000     1.0000
+    2.0000     2.0000
+    3.0000     3.0000
+
+    1.0000     1.0000
+    2.0000     2.0000
+    3.0000     3.0000
+```
+
+### transpose()
+
+The [transpose](./fn.transpose.html) function performs a standard matrix transpose. The input
+array must have the dimensions of a 2D-matrix.
+
+```rust
+a [3 3 1 1]
+    1.0000     3.0000     3.0000
+    2.0000     1.0000     3.0000
+    2.0000     2.0000     1.0000
+
+transpose(&a, False) //Second parameter to be used for conjugate transpose
+[3 3 1 1]
+    1.0000     2.0000     2.0000
+    3.0000     1.0000     2.0000
+    3.0000     3.0000     1.0000
+```