Documentation for modules arith, blas, data, device & image

Author: 9prady9

src/arith/mod.rs

@@ -94,6 +94,7 @@ extern {
     fn af_isnan(out: MutAfArray, arr: AfArray) -> c_int;
 }
 
+/// Enables use of `!` on objects of type [Array](./struct.Array.html)
 impl<'f> Not for &'f Array {
     type Output = Array;
 

src/blas/mod.rs

@@ -21,6 +21,18 @@ extern {
     fn af_transpose_inplace(arr: AfArray, conjugate: c_int) -> c_int;
 }
 
+/// Matrix multiple of two Arrays
+///
+/// # Parameters
+///
+/// - `lhs` is the Array on left hand side
+/// - `rhs` is the Array on right hand side
+/// - `optlhs` - Transpose left hand side before the function is performed, uses one of the values of [MatProp](./enum.MatProp.html)
+/// - `optrhs` - Transpose right hand side before the function is performed, uses one of the values of [MatProp](./enum.MatProp.html)
+///
+/// # Return Values
+///
+/// The result Array of matrix multiplication
 #[allow(unused_mut)]
 pub fn matmul(lhs: &Array, rhs: &Array,
               optlhs: MatProp, optrhs: MatProp) -> Result<Array, AfError> {
@@ -36,6 +48,20 @@ pub fn matmul(lhs: &Array, rhs: &Array,
     }
 }
 
+/// Calculate the dot product of vectors.
+///
+/// Scalar dot product between two vectors. Also referred to as the inner product. This function returns the scalar product of two equal sized vectors or between a matrix and a vector. The second operand needs to be a vector in either case.
+///
+/// # Parameters
+///
+/// - `lhs` - Left hand side of dot operation
+/// - `rhs` - Right hand side of dot operation
+/// - `optlhs` - Options for lhs. Currently only NONE value from [MatProp](./enum.MatProp.html) is supported.
+/// - `optrhs` - Options for rhs. Currently only NONE value from [MatProp](./enum.MatProp.html) is supported.
+///
+/// # Return Values
+///
+/// The result of dot product.
 #[allow(unused_mut)]
 pub fn dot(lhs: &Array, rhs: &Array,
            optlhs: MatProp, optrhs: MatProp) -> Result<Array, AfError> {
@@ -51,6 +77,17 @@ pub fn dot(lhs: &Array, rhs: &Array,
     }
 }
 
+/// Transpose of a matrix.
+///
+/// # Parameters
+///
+/// - `arr` is the input Array
+/// - `conjugate` is a boolean that indicates if the transpose operation needs to be a conjugate
+/// transpose
+///
+/// # Return Values
+///
+/// Transposed Array.
 #[allow(unused_mut)]
 pub fn transpose(arr: &Array, conjugate: bool) -> Result<Array, AfError> {
     unsafe {
@@ -64,6 +101,13 @@ pub fn transpose(arr: &Array, conjugate: bool) -> Result<Array, AfError> {
     }
 }
 
+/// Inplace transpose of a matrix.
+///
+/// # Parameters
+///
+/// - `arr` is the input Array that has to be transposed
+/// - `conjugate` is a boolean that indicates if the transpose operation needs to be a conjugate
+/// transpose
 #[allow(unused_mut)]
 pub fn transpose_inplace(arr: &mut Array, conjugate: bool) -> Result<(), AfError> {
     unsafe {

src/data/mod.rs

@@ -174,10 +174,33 @@ cnst!(u32 , 6);
 cnst!(u8  , 7);
 
 
+/// Create an Array with constant value
+///
+/// # Parameters
+///
+/// - `cnst` is the constant value to be filled in the Array
+/// - `dims` is the size of the constant Array
+///
+/// # Return Values
+///
+/// An Array of given dimensions with constant value
 pub fn constant<T : ConstGenerator>(cnst: T, dims: Dim4) -> Result<Array, AfError> {
     cnst.generate(dims)
 }
 
+/// Create a Range of values
+///
+/// Creates an array with [0, n] values along the `seq_dim` which is tiled across other dimensions.
+///
+/// # Parameters
+///
+/// - `dims` is the size of Array
+/// - `seq_dim` is the dimension along which range values are populated, all values along other
+/// dimensions are just repeated
+/// - `aftype` is the type of the Array.
+///
+/// # Return Values
+/// Array
 #[allow(unused_mut)]
 pub fn range(dims: Dim4, seq_dim: i32, aftype: Aftype) -> Result<Array, AfError> {
     unsafe {
@@ -192,6 +215,19 @@ pub fn range(dims: Dim4, seq_dim: i32, aftype: Aftype) -> Result<Array, AfError>
     }
 }
 
+/// Create a range of values
+///
+/// Create an sequence [0, dims.elements() - 1] and modify to specified dimensions dims and then tile it according to tile_dims.
+///
+/// # Parameters
+///
+/// - `dims` is the dimensions of the sequence to be generated
+/// - `tdims` is the number of repitions of the unit dimensions
+/// - `aftype` is the type of Array to generate
+///
+/// # Return Values
+///
+/// Array
 #[allow(unused_mut)]
 pub fn iota(dims: Dim4, tdims: Dim4, aftype: Aftype) -> Result<Array, AfError> {
     unsafe {
@@ -207,6 +243,7 @@ pub fn iota(dims: Dim4, tdims: Dim4, aftype: Aftype) -> Result<Array, AfError> {
     }
 }
 
+/// Set seed for random number generation
 pub fn set_seed(seed: u64) -> Result<(), AfError> {
     unsafe {
         let err_val = af_set_seed(seed as Uintl);
@@ -217,6 +254,7 @@ pub fn set_seed(seed: u64) -> Result<(), AfError> {
     }
 }
 
+/// Get the seed of random number generator
 #[allow(unused_mut)]
 pub fn get_seed() -> Result<u64, AfError> {
     unsafe {
@@ -251,6 +289,17 @@ data_gen_def!(randu, af_randu);
 data_gen_def!(randn, af_randn);
 data_gen_def!(identity, af_identity);
 
+/// Create a diagonal matrix
+///
+/// # Parameters
+///
+/// - `input` is the input Array
+/// - `dim` is the diagonal index relative to principal diagonal where values from input Array are
+/// to be placed
+///
+/// # Return Values
+///
+/// An Array with values as a diagonal Matrix
 #[allow(unused_mut)]
 pub fn diag_create(input: &Array, dim: i32) -> Result<Array, AfError> {
     unsafe {
@@ -263,6 +312,16 @@ pub fn diag_create(input: &Array, dim: i32) -> Result<Array, AfError> {
     }
 }
 
+/// Extract diagonal from a given Matrix
+///
+/// # Parameters
+///
+/// - `input` is the input Matrix
+/// - `dim` is the index of the diagonal that has to be extracted from the input Matrix
+///
+/// # Return Values
+///
+/// An Array with values of the diagonal from input Array
 #[allow(unused_mut)]
 pub fn diag_extract(input: &Array, dim: i32) -> Result<Array, AfError> {
     unsafe {
@@ -276,6 +335,17 @@ pub fn diag_extract(input: &Array, dim: i32) -> Result<Array, AfError> {
     }
 }
 
+/// Join two arrays
+///
+/// # Parameters
+///
+/// - `dim` is the dimension along which the concatenation has to be done
+/// - `first` is the Array that comes first in the concatenation
+/// - `second` is the Array that comes last in the concatenation
+///
+/// # Return Values
+///
+/// Concatenated Array
 #[allow(unused_mut)]
 pub fn join(dim: i32, first: &Array, second: &Array) -> Result<Array, AfError> {
     unsafe {
@@ -289,6 +359,16 @@ pub fn join(dim: i32, first: &Array, second: &Array) -> Result<Array, AfError> {
     }
 }
 
+/// Join multiple arrays
+///
+/// # Parameters
+///
+/// - `dim` is the dimension along which the concatenation has to be done
+/// - `inputs` is the vector of Arrays that has to be concatenated
+///
+/// # Return Values
+///
+/// Concatenated Array
 #[allow(unused_mut)]
 pub fn join_many(dim: i32, inputs: Vec<&Array>) -> Result<Array, AfError> {
     unsafe {
@@ -302,6 +382,25 @@ pub fn join_many(dim: i32, inputs: Vec<&Array>) -> Result<Array, AfError> {
     }
 }
 
+/// Join multiple Arrays along a given dimension
+///
+/// # Examples
+///
+/// ```
+/// # #[macro_use] extern crate arrayfire;
+/// # fn main() {
+/// let a = randu(Dim4::new(&[5, 3, 1, 1]), Aftype::F32).unwrap();
+/// let b = randu(Dim4::new(&[5, 3, 1, 1]), Aftype::F32).unwrap();
+/// let c = randu(Dim4::new(&[5, 3, 1, 1]), Aftype::F32).unwrap();
+/// let d = join_many![2, a, b, c];
+/// # }
+/// ```
+///
+/// # Panics
+///
+/// Using this macro to create an Array from multiple Arrays doesn't implicitly check for errors
+/// during FFI calls. Therefore, make sure your inputs are correct. In case, you do need proper
+/// error checking, use the [function version](./fn.join_many.html) of this macro.
 // Using macro to implement join many wrapper
 #[macro_export]
 macro_rules! join_many {
@@ -344,6 +443,15 @@ data_func_def!(tile, af_tile);
 data_func_def!(reorder, af_reorder);
 data_func_def!(shift, af_shift);
 
+/// Change the shape of the Array
+///
+/// # Parameters
+///
+/// - `input` is the input Array
+/// - `dims` is the new dimensions to which the input Array is reshaped to
+///
+/// # Return Values
+/// Reshaped Array
 #[allow(unused_mut)]
 pub fn moddims(input: &Array, dims: Dim4) -> Result<Array, AfError> {
     unsafe {
@@ -357,6 +465,7 @@ pub fn moddims(input: &Array, dims: Dim4) -> Result<Array, AfError> {
     }
 }
 
+/// Flatten the multidimensional Array to an 1D Array
 #[allow(unused_mut)]
 pub fn flat(input: &Array) -> Result<Array, AfError> {
     unsafe {
@@ -369,6 +478,16 @@ pub fn flat(input: &Array) -> Result<Array, AfError> {
     }
 }
 
+/// Flip the Array
+///
+/// # Parameters
+///
+/// - `input` is the Array to be flipped
+/// - `dim` is the dimension along which the flip has to happen
+///
+/// # Return Values
+///
+/// Flipped Array
 #[allow(unused_mut)]
 pub fn flip(input: &Array, dim: u32) -> Result<Array, AfError> {
     unsafe {
@@ -381,6 +500,15 @@ pub fn flip(input: &Array, dim: u32) -> Result<Array, AfError> {
     }
 }
 
+/// Create lower triangular matrix
+///
+/// # Parameters
+///
+/// - `input` is the input Array
+/// - `is_unit_diag` dictates if the output Array should have 1's along diagonal
+///
+/// # Return Values
+/// Array
 #[allow(unused_mut)]
 pub fn lower(input: &Array, is_unit_diag: bool) -> Result<Array, AfError> {
     unsafe {
@@ -394,6 +522,15 @@ pub fn lower(input: &Array, is_unit_diag: bool) -> Result<Array, AfError> {
     }
 }
 
+/// Create upper triangular matrix
+///
+/// # Parameters
+///
+/// - `input` is the input Array
+/// - `is_unit_diag` dictates if the output Array should have 1's along diagonal
+///
+/// # Return Values
+/// Array
 #[allow(unused_mut)]
 pub fn upper(input: &Array, is_unit_diag: bool) -> Result<Array, AfError> {
     unsafe {

src/device/mod.rs

@@ -11,6 +11,10 @@ extern {
     fn af_set_device(device: c_int) -> c_int;
 }
 
+/// Get ArrayFire Version Number
+///
+/// # Return Values
+/// A triplet of integers indicating major, minor & fix release version numbers.
 pub fn get_version() -> Result<(i32, i32, i32), AfError> {
     unsafe {
         let mut maj: i32 = 0;
@@ -25,6 +29,7 @@ pub fn get_version() -> Result<(i32, i32, i32), AfError> {
     }
 }
 
+/// Print library meta-info
 pub fn info() -> Result<(), AfError> {
     unsafe {
         let err_val = af_info();
@@ -35,6 +40,11 @@ pub fn info() -> Result<(), AfError> {
     }
 }
 
+/// Set active device
+///
+/// # Parameters
+///
+/// - `device` is the value of the device identifier which has to be set as active
 pub fn set_device(device: i32) -> Result<(), AfError> {
     unsafe {
         let err_val = af_set_device(device as c_int);