Add document for Matrix format

Author: termoshtt

src/layout.rs

@@ -1,4 +1,41 @@
-//! Memory layout of matrices
+//! Convert ndarray into LAPACK-compatible matrix format
+//!
+//! Different from ndarray format which consists of shape and strides,
+//! matrix format in LAPACK consists of row or column size and leading dimension.
+//!
+//! ndarray format and stride
+//! --------------------------
+//!
+//! Let us consider 3-dimensional array for explaining ndarray structure.
+//! The address of `(x,y,z)`-element in ndarray satisfies following relation:
+//!
+//! ```
+//! shape = [Nx, Ny, Nz]
+//!     where Nx > 0, Ny > 0, Nz > 0
+//! stride = [Sx, Sy, Sz]
+//!
+//! &data[(x, y, z)] = &data[(0, 0, 0)] + Sx*x + Sy*y + Sz*z
+//!     for x < Nx, y < Ny, z < Nz
+//! ```
+//!
+//! The array is called
+//!
+//! - C-continuous if `[Sx, Sy, Sz] = [Nz*Ny, Nz, 1]`
+//! - F(Fortran)-continuous if `[Sx, Sy, Sz] = [1, Nx, Nx*Ny]`
+//!
+//! Strides of ndarray `[Sx, Sy, Sz]` take arbitrary value,
+//! e.g. it can be non-ordered `Sy > Sx > Sz`, or can be negative `Sx < 0`.
+//! If the minimum of `[Sx, Sy, Sz]` equals to `1`,
+//! the value of elements fills `data` memory region and called "continuous".
+//! Non-continuous ndarray is useful to get sub-array without copying data.
+//!
+//! Matrix layout for LAPACK
+//! -------------------------
+//!
+//! LAPACK interface focuses on the linear algebra operations for F-continuous 2-dimensional array.
+//! Under this restriction, stride becomes far simpler; we only have to consider the case `[1, S]`
+//! This `S` for a matrix `A` is called "leading dimension of the array A" in LAPACK document, and denoted by `lda`.
+//!
 
 use ndarray::*;