Merge pull request #62 from termoshtt/new_doc

Document update

Author: termoshtt

src/cholesky.rs

@@ -1,4 +1,6 @@
 //! Cholesky decomposition
+//!
+//! https://en.wikipedia.org/wiki/Cholesky_decomposition
 
 use ndarray::*;
 
@@ -10,15 +12,18 @@ use super::types::*;
 
 pub use lapack_traits::UPLO;
 
+/// Cholesky decomposition of matrix reference
 pub trait Cholesky {
     type Output;
     fn cholesky(&self, UPLO) -> Result<Self::Output>;
 }
 
+/// Cholesky decomposition
 pub trait CholeskyInto: Sized {
     fn cholesky_into(self, UPLO) -> Result<Self>;
 }
 
+/// Cholesky decomposition of mutable reference of matrix
 pub trait CholeskyMut {
     fn cholesky_mut(&mut self, UPLO) -> Result<&mut Self>;
 }

src/eigh.rs

@@ -9,14 +9,14 @@ use super::layout::*;
 use super::operator::*;
 use super::types::*;
 
-/// Eigenvalue decomposition of Hermite matrix
+/// Eigenvalue decomposition of Hermite matrix reference
 pub trait Eigh {
     type EigVal;
     type EigVec;
     fn eigh(&self, UPLO) -> Result<(Self::EigVal, Self::EigVec)>;
 }
 
-/// Eigenvalue decomposition of Hermite matrix
+/// Eigenvalue decomposition of mutable reference of Hermite matrix
 pub trait EighMut {
     type EigVal;
     fn eigh_mut(&mut self, UPLO) -> Result<(Self::EigVal, &mut Self)>;

src/lib.rs

@@ -16,30 +16,6 @@
 //!  - [assertions for array](index.html#macros)
 //!  - [generator functions](generate/index.html)
 //!  - [Scalar trait](types/trait.Scalar.html)
-//!
-//!  Usage
-//!  ------
-//!  Most functions in this crate is defined as [self-consuming trait technique][sct] like [serde]
-//!  does.
-//!
-//!  For example, we can execute [eigh][eigh] using three types of interfaces:
-//!
-//!  ```rust,ignore
-//!  let a = random((3, 3));
-//!  let (eval, evec) = a.eigh(UPLO::Upper)?;
-//!  let (eval, evec) = (&a).eigh(UPLO::Upper)?;
-//!  let (eval, evec) = (&mut a).eigh(UPLO::Upper)?;
-//!  ```
-//!
-//!  The first type `a.eigh()` consumes `a`, and the memory of `a` is used for `evec`.
-//!  The second type `(&a).eigh()` consumes the reference (not `a` itself),
-//!  and the memory for `evec` is newly allocated.
-//!  The last one `(&mut a).eigh()` is similar to the first one;
-//!  It borrows `a` mutably, and rewrite it to contains `evec`.
-//!  In all cases, the array `eval` is newly allocated.
-//!
-//!  [sct]:https://github.com/serde-rs/serde/releases/tag/v0.9.0
-//!  [serde]:https://github.com/serde-rs/serde
 
 extern crate blas;
 extern crate lapack;

src/opnorm.rs

@@ -6,31 +6,41 @@ use super::error::*;
 use super::layout::*;
 use super::types::*;
 
-use lapack_traits::LapackScalar;
 pub use lapack_traits::NormType;
 
+/// Operator norm using `*lange` LAPACK routines
+///
+/// https://en.wikipedia.org/wiki/Operator_norm
 pub trait OperationNorm {
-    type Output;
-    fn opnorm(&self, t: NormType) -> Self::Output;
-    fn opnorm_one(&self) -> Self::Output {
+    /// the value of norm
+    type Output: RealScalar;
+
+    fn opnorm(&self, t: NormType) -> Result<Self::Output>;
+
+    /// the one norm of a matrix (maximum column sum)
+    fn opnorm_one(&self) -> Result<Self::Output> {
         self.opnorm(NormType::One)
     }
-    fn opnorm_inf(&self) -> Self::Output {
+
+    /// the infinity norm of a matrix (maximum row sum)
+    fn opnorm_inf(&self) -> Result<Self::Output> {
         self.opnorm(NormType::Infinity)
     }
-    fn opnorm_fro(&self) -> Self::Output {
+
+    /// the Frobenius norm of a matrix (square root of sum of squares)
+    fn opnorm_fro(&self) -> Result<Self::Output> {
         self.opnorm(NormType::Frobenius)
     }
 }
 
 impl<A, S> OperationNorm for ArrayBase<S, Ix2>
 where
-    A: LapackScalar + AssociatedReal,
+    A: Scalar,
     S: Data<Elem = A>,
 {
-    type Output = Result<A::Real>;
+    type Output = A::Real;
 
-    fn opnorm(&self, t: NormType) -> Self::Output {
+    fn opnorm(&self, t: NormType) -> Result<Self::Output> {
         let l = self.layout()?;
         let a = self.as_allocated()?;
         Ok(A::opnorm(t, l, a))

src/qr.rs

@@ -1,4 +1,6 @@
 //! QR decomposition
+//!
+//! https://en.wikipedia.org/wiki/QR_decomposition
 
 use ndarray::*;
 use num_traits::Zero;
@@ -7,50 +9,80 @@ use super::convert::*;
 use super::error::*;
 use super::layout::*;
 use super::triangular::*;
+use super::types::*;
 
-use lapack_traits::{LapackScalar, UPLO};
+pub use lapack_traits::UPLO;
 
+/// QR decomposition for matrix reference
+///
+/// This creates copy due for reshaping array.
+/// To avoid copy and the matrix is square, please use `QRSquare*` traits.
 pub trait QR {
     type Q;
     type R;
     fn qr(&self) -> Result<(Self::Q, Self::R)>;
 }
 
+/// QR decomposition
+///
+/// This creates copy due for reshaping array.
+/// To avoid copy and the matrix is square, please use `QRSquare*` traits.
 pub trait QRInto: Sized {
     type Q;
     type R;
     fn qr_into(self) -> Result<(Self::Q, Self::R)>;
 }
 
+/// QR decomposition for square matrix reference
 pub trait QRSquare: Sized {
     type Q;
     type R;
     fn qr_square(&self) -> Result<(Self::Q, Self::R)>;
 }
 
+/// QR decomposition for square matrix
 pub trait QRSquareInto: Sized {
     type R;
     fn qr_square_into(self) -> Result<(Self, Self::R)>;
 }
 
-impl<A, S> QRSquareInto for ArrayBase<S, Ix2>
+/// QR decomposition for mutable reference of square matrix
+pub trait QRSquareMut: Sized {
+    type R;
+    fn qr_square_mut<'a>(&'a mut self) -> Result<(&'a mut Self, Self::R)>;
+}
+
+impl<A, S> QRSquareMut for ArrayBase<S, Ix2>
 where
-    A: LapackScalar + Copy + Zero,
+    A: Scalar,
     S: DataMut<Elem = A>,
 {
     type R = Array2<A>;
 
-    fn qr_square_into(mut self) -> Result<(Self, Self::R)> {
+    fn qr_square_mut<'a>(&'a mut self) -> Result<(&'a mut Self, Self::R)> {
         let l = self.square_layout()?;
         let r = A::qr(l, self.as_allocated_mut()?)?;
         let r: Array2<_> = into_matrix(l, r)?;
         Ok((self, r.into_triangular(UPLO::Upper)))
     }
 }
 
+impl<A, S> QRSquareInto for ArrayBase<S, Ix2>
+where
+    A: Scalar,
+    S: DataMut<Elem = A>,
+{
+    type R = Array2<A>;
+
+    fn qr_square_into(mut self) -> Result<(Self, Self::R)> {
+        let (_, r) = self.qr_square_mut()?;
+        Ok((self, r))
+    }
+}
+
 impl<A, S> QRSquare for ArrayBase<S, Ix2>
 where
-    A: LapackScalar + Copy + Zero,
+    A: Scalar,
     S: Data<Elem = A>,
 {
     type Q = Array2<A>;
@@ -65,7 +97,7 @@ where
 
 impl<A, S> QRInto for ArrayBase<S, Ix2>
 where
-    A: LapackScalar + Copy + Zero,
+    A: Scalar,
     S: DataMut<Elem = A>,
 {
     type Q = Array2<A>;
@@ -85,7 +117,7 @@ where
 
 impl<A, S> QR for ArrayBase<S, Ix2>
 where
-    A: LapackScalar + Copy + Zero,
+    A: Scalar,
     S: Data<Elem = A>,
 {
     type Q = Array2<A>;

src/solve.rs

@@ -1,11 +1,9 @@
 //! Solve linear problems
 
-
 use ndarray::*;
 
 use super::convert::*;
 use super::error::*;
-use super::lapack_traits::*;
 use super::layout::*;
 use super::types::*;
 
@@ -18,7 +16,7 @@ pub struct Factorized<S: Data> {
 
 impl<A, S> Factorized<S>
 where
-    A: LapackScalar,
+    A: Scalar,
     S: Data<Elem = A>,
 {
     pub fn solve<Sb>(&self, t: Transpose, mut rhs: ArrayBase<Sb, Ix1>) -> Result<ArrayBase<Sb, Ix1>>
@@ -38,7 +36,7 @@ where
 
 impl<A, S> Factorized<S>
 where
-    A: LapackScalar,
+    A: Scalar,
     S: DataMut<Elem = A>,
 {
     pub fn into_inverse(mut self) -> Result<ArrayBase<S, Ix2>> {

src/svd.rs

@@ -1,4 +1,6 @@
 //! singular-value decomposition
+//!
+//! https://en.wikipedia.org/wiki/Singular_value_decomposition
 
 use ndarray::*;
 
@@ -7,20 +9,23 @@ use super::error::*;
 use super::layout::*;
 use super::types::*;
 
+/// singular-value decomposition of matrix reference
 pub trait SVD {
     type U;
     type VT;
     type Sigma;
     fn svd(&self, calc_u: bool, calc_vt: bool) -> Result<(Option<Self::U>, Self::Sigma, Option<Self::VT>)>;
 }
 
+/// singular-value decomposition
 pub trait SVDInto {
     type U;
     type VT;
     type Sigma;
     fn svd_into(self, calc_u: bool, calc_vt: bool) -> Result<(Option<Self::U>, Self::Sigma, Option<Self::VT>)>;
 }
 
+/// singular-value decomposition for mutable reference of matrix
 pub trait SVDMut {
     type U;
     type VT;