Merge pull request #52 from termoshtt/docs

Update document

Author: termoshtt

README.md

@@ -8,30 +8,16 @@ Linear algebra package for [rust-ndarray](https://github.com/bluss/rust-ndarray)
 
 Examples
 ---------
+See [examples](https://github.com/termoshtt/ndarray-linalg/tree/master/examples) directory.
 
-```rust
-extern crate ndarray;
-extern crate ndarray_linalg;
-
-use ndarray::prelude::*;
-use ndarray_linalg::prelude::*;
-
-fn main() {
-    let a = arr2(&[[3.0, 1.0, 1.0], [1.0, 3.0, 1.0], [1.0, 1.0, 3.0]]);
-    let (e, vecs) = a.clone().eigh().unwrap();
-    println!("eigenvalues = \n{:?}", e);
-    println!("V = \n{:?}", vecs);
-    let av = a.dot(&vecs);
-    println!("AV = \n{:?}", av);
-}
-```
+Versions
+---------
 
-See complete example at [src/bin/main.rs](src/bin/main.rs).
+- v0.5.0 (not released)
+    - **Breaking Change** Rewrite all algorithms to support complex numbers and general `ArrayBase`
 
-Progress
----------
-Some algorithms have not been implemented yet. See [#6](https://github.com/termoshtt/ndarray-linalg/issues/6).
+- v0.4.1
+    - ADD: assertion [#31](https://github.com/termoshtt/ndarray-linalg/pull/31)
 
-Similar Projects
------------------
-- [linxal](https://github.com/masonium/linxal)
+- v0.4.0
+    - MOD: use ndarray v0.9

src/assert.rs

@@ -5,6 +5,7 @@ use ndarray::*;
 use super::types::*;
 use super::norm::*;
 
+/// check two values are close in terms of the relative torrence
 pub fn rclose<A, Tol>(test: A, truth: A, rtol: Tol) -> Result<Tol, Tol>
     where A: Field + Absolute<Output = Tol>,
           Tol: RealField
@@ -13,6 +14,7 @@ pub fn rclose<A, Tol>(test: A, truth: A, rtol: Tol) -> Result<Tol, Tol>
     if dev < rtol { Ok(dev) } else { Err(dev) }
 }
 
+/// check two values are close in terms of the absolute torrence
 pub fn aclose<A, Tol>(test: A, truth: A, atol: Tol) -> Result<Tol, Tol>
     where A: Field + Absolute<Output = Tol>,
           Tol: RealField

src/cholesky.rs

@@ -1,3 +1,4 @@
+//! Cholesky decomposition
 
 use ndarray::*;
 use num_traits::Zero;
@@ -6,8 +7,8 @@ use super::error::*;
 use super::layout::*;
 use super::triangular::IntoTriangular;
 
-use impl2::LapackScalar;
-pub use impl2::UPLO;
+use lapack_traits::LapackScalar;
+pub use lapack_traits::UPLO;
 
 pub trait Cholesky<K> {
     fn cholesky(self, UPLO) -> Result<K>;

src/eigh.rs

@@ -1,11 +1,12 @@
+//! Eigenvalue decomposition for Hermite matrices
 
 use ndarray::*;
 
 use super::error::*;
 use super::layout::*;
 
-use impl2::LapackScalar;
-pub use impl2::UPLO;
+use lapack_traits::LapackScalar;
+pub use lapack_traits::UPLO;
 
 pub trait Eigh<EigVal, EigVec> {
     fn eigh(self, UPLO) -> Result<(EigVal, EigVec)>;

src/error.rs

@@ -6,6 +6,7 @@ use ndarray::{Ixs, ShapeError};
 
 pub type Result<T> = ::std::result::Result<T, LinalgError>;
 
+/// Master Error type of this crate
 #[derive(Debug, EnumError)]
 pub enum LinalgError {
     NotSquare(NotSquareError),
@@ -15,6 +16,7 @@ pub enum LinalgError {
     Shape(ShapeError),
 }
 
+/// Error from LAPACK
 #[derive(Debug, new)]
 pub struct LapackError {
     pub return_code: i32,
@@ -38,6 +40,7 @@ impl From<i32> for LapackError {
     }
 }
 
+/// Error that matrix is not square
 #[derive(Debug, new)]
 pub struct NotSquareError {
     pub rows: i32,
@@ -56,6 +59,7 @@ impl error::Error for NotSquareError {
     }
 }
 
+/// Error that strides of the array is not supported
 #[derive(Debug, new)]
 pub struct StrideError {
     pub s0: Ixs,
@@ -74,6 +78,7 @@ impl error::Error for StrideError {
     }
 }
 
+/// Error that the memory is not aligned continously
 #[derive(Debug, new)]
 pub struct MemoryContError {}
 

src/generate.rs

@@ -1,3 +1,4 @@
+//! Generator functions for matrices
 
 use ndarray::*;
 use std::ops::*;
@@ -7,6 +8,7 @@ use super::layout::*;
 use super::types::*;
 use super::error::*;
 
+/// Hermite conjugate matrix
 pub fn conjugate<A, Si, So>(a: &ArrayBase<Si, Ix2>) -> ArrayBase<So, Ix2>
     where A: Conjugate,
           Si: Data<Elem = A>,
@@ -19,6 +21,7 @@ pub fn conjugate<A, Si, So>(a: &ArrayBase<Si, Ix2>) -> ArrayBase<So, Ix2>
     a
 }
 
+/// Generate random array
 pub fn random<A, S, Sh, D>(sh: Sh) -> ArrayBase<S, D>
     where A: RandNormal,
           S: DataOwned<Elem = A>,

src/impl2/cholesky.rs renamed to src/lapack_traits/cholesky.rs

@@ -1,4 +1,4 @@
-//! implement Cholesky decomposition
+//! Cholesky decomposition
 
 use lapack::c;
 

src/impl2/eigh.rs renamed to src/lapack_traits/eigh.rs

@@ -1,3 +1,4 @@
+//! Eigenvalue decomposition for Hermite matrices
 
 use lapack::c;
 use num_traits::Zero;
@@ -8,6 +9,7 @@ use layout::Layout;
 
 use super::{into_result, UPLO};
 
+/// Wraps `*syev` for real and `*heev` for complex
 pub trait Eigh_: AssociatedReal {
     fn eigh(calc_eigenvec: bool, Layout, UPLO, a: &mut [Self]) -> Result<Vec<Self::Real>>;
 }

src/impl2/mod.rs renamed to src/lapack_traits/mod.rs

@@ -1,3 +1,4 @@
+//! Define traits wrapping LAPACK routines
 
 pub mod opnorm;
 pub mod qr;
@@ -33,6 +34,7 @@ pub fn into_result<T>(info: i32, val: T) -> Result<T> {
     }
 }
 
+/// Upper/Lower specification for seveal usages
 #[derive(Debug, Clone, Copy)]
 #[repr(u8)]
 pub enum UPLO {

src/impl2/opnorm.rs renamed to src/lapack_traits/opnorm.rs

@@ -1,4 +1,4 @@
-//! Implement Operator norms for matrices
+//! Operator norms of matrices
 
 use lapack::c;
 use lapack::c::Layout::ColumnMajor as cm;