Documentation: Correct + improve linear systems

Author: Mark Wellons

src/ports/postgres/modules/linear_systems/dense_linear_systems.sql_in

@@ -15,10 +15,24 @@ m4_include(`SQLCommon.m4')
 /**
 @addtogroup grp_dense_linear_solver
 
+
+<div class ="toc"><b>Contents</b>
+<ul>
+<li class="level1"><a href="#dls_about">About</a></li>
+<li class="level1"><a href="#dls_online_help">Online Help</a></li>
+<li class="level1"><a href="#dls_function">Function Syntax</a></li>
+<li class="level1"><a href="#dls_args">Arguments</a></li>
+<li class="level1"><a href="#dls_opt_params">Optimizer Parameters</a></li>
+<li class="level1"><a href="#dls_output">Output Tables</a></li>
+<li class="level1"><a href="#dls_examples">Examples</a></li>
+</ul>
+</div>
+
+@anchor dls_about
 @about
 
-The linear systems module implements solution methods for systems of a consistent
-linear equations.
+The linear systems module implements solution methods for systems of consistent
+linear equations.  Systems of linear equations take the form: 
 \f[
   Ax = b
 \f]
@@ -27,9 +41,10 @@ where \f$x \in \mathbb{R}^{n}\f$, \f$A \in \mathbb{R}^{m \times n} \f$ and \f$b
 We assume that there are no rows of \f$A\f$ where all elements are zero. 
 The algorithms implemented in this module can handle large dense
 linear systems. Currently, the algorithms implemented in this module
-solve the lienar system by a direct decomposition. Hence, these methods are 
+solve the linear system by a direct decomposition. Hence, these methods are 
 known as <em>direct method</em>. 
 
+@anchor dls_online_help
 @par Online Help
 
 View short help messages using the following statements:
@@ -44,21 +59,21 @@ SELECT madlib.linear_solver_dense('usage');
 SELECT madlib.linear_solver_dense('direct');
 @endverbatim
 
-@usage
+@anchor dls_function
+@par Function Syntax
 
 <pre>
-SELECT {schema_madlib}.linear_solve_dense (
-    'tbl_source',      -- Data table
-    'tbl_result',      -- Result table
-    'row_id',          -- Name of column containing row_id
-    'left_hand_side',  -- Left Hand Side of the equations
-    'right_hand_side', -- Right Hand side of the equations
-    'grouping_cols',   -- Grouping columns (Default: NULL)
-    'optimizer',       -- Name of optimizer. Default: 'direct'
-    'optimizer_params' -- Text array of optimizer parameters
-);
+SELECT linear_solver_dense(tbl_source, tbl_result, row_id, LHS, 
+                RHS, grouping_col := NULL, optimizer := 'direct', 
+                optimizer_params := 'algorithm = householderqr');
 </pre>
 
+@anchor dls_args
+@par Arguments
+
+<DL class="arglist">
+<DT>tbl_source</DT>
+<DD>Text value. The name of the table containing the training data.
 The input data is expected to be of the following form:
 <pre>{TABLE|VIEW} <em>sourceName</em> (
     ...
@@ -68,30 +83,12 @@ The input data is expected to be of the following form:
     ...
 )</pre>
 
-Here, each row represents a single equation using. The <em> rhs </em> refers
-to the right hand side of the equations while the <em> lhs_array </em>
+Here, each row represents a single equation using. The <em> right_hand_side 
+</em> refers
+to the right hand side of the equations while the <em> left_hand_side </em>
 refers to the multipliers on the variables on the left hand side of the same
 equations. 
-
-Output is stored in the <em>tbl_result</em>
-@verbatim
-    tbl_result      |   Data Types
---------------------|---------------------
-solution            | DOUBLE PRECISION[]
-residual_norm       | DOUBLE PRECISIOn
-iters               | INTEGER
-@endverbatim
-
-@par Syntax
-
-<pre>
-SELECT dense_linear_sytems('tbl_source', 'tbl_result', 'row_id', 'LHS', 
-                'RHS', NULL, 'direct', 'algorithm = householderqr');
-</pre>
-
-<DL>
-<DT>tbl_source</DT>
-<DD>Text value. The name of the table containing the training data.</DD>
+</DD>
 
 <DT>tbl_result</DT>
 <DD>Text value. The name of the table where the output is saved.</DD>
@@ -102,12 +99,12 @@ SELECT dense_linear_sytems('tbl_source', 'tbl_result', 'row_id', 'LHS',
 \note For a system with N equations, the row_id's must be a continuous
 range of integers from \f$ 0 \ldots n-1 \f$.
 
-<DT>left_hand_size</DT>
-<DD>Text value. The name of the column storing the 'left hand size' of the 
+<DT>LHS</DT>
+<DD>Text value. The name of the column storing the 'left hand side' of the 
 equations stored as an array.</DD>
 
-<DT>right_hand_size</DT>
-<DD>Text value. The name of the column storing the 'right hand size' of the 
+<DT>RHS</DT>
+<DD>Text value. The name of the column storing the 'right hand side' of the 
 equations.</DD>
 
 <DT>grouping_col (optional) </DT>
@@ -121,13 +118,13 @@ equations.</DD>
 <DD>Text value. Optimizer specific parameters. Default: NULL.</DD>
 </DL>
 
-
+@anchor dls_opt_params
 @par Optimizer Parameters
 
 For each optimizer, there are specific parameters that can be tuned
 for better performance.
-
-<DL>
+\par
+<DL class="arglist">
 <DT>algorithm (default: householderqr)</dT>
 <DD>
 
@@ -148,16 +145,19 @@ for better performance.
        llt                  | Pos. Definite    |  +++  |  +
        ldlt                 | Pos. or Neg Def  |  +++  |  ++
 
+    For speed '++' is faster than '+', which is faster than '-'.
+    For accuracy '+++' is better than '++'.
+
     More details about the individual algorithms can be found on the  <a href="http://eigen.tuxfamily.org/dox-devel/group__TutorialLinearAlgebra.html"> Eigen documentation</a>.  Eigen is an open source library for linear algebra.
 
 
 </DD>
 </DL>
 
-
+@anchor dls_output
 @par Output statistics 
-
-<DL>
+Output is stored in the <em>tbl_result</em> table.  
+<DL class="arglist">
 <DT>solution</dT>
 <DD>
 The solution is an array (of double precision) with the variables in the same
@@ -167,8 +167,8 @@ order as that provided as input in the 'left_hand_side' column name of the
 
 <DT>residual_norm</dT>
 <DD>
-Computes the scaled residual norm, defined as \f$ \frac{|Ax - b|}{|b|} \f$
-gives the user an indication of the accuracy of the solution.
+Computes the scaled residual norm, defined as \f$ \frac{|Ax - b|}{|b|} \f$. 
+This value is an indication of the accuracy of the solution.
 </DD>
 
 <DT>iters</dT>
@@ -184,27 +184,27 @@ The number of iterations required by the algorithm (only applicable for
 
 
 
-
+@anchor dls_examples
 @examp
 
 -#  Create the sample data set:
 \verbatim
-sql>  CREATE TABLE source_table (id INTEGER NOT NULL, 
+sql>  CREATE TABLE linear_systems_test_data (id INTEGER NOT NULL, 
                                  lhs DOUBLE PRECISION[],
                                  rhs DOUBLE PRECISION);
-sql> INSERT INTO linear_systems_test_data(id, a, b) VaLUES
+sql> INSERT INTO linear_systems_test_data(id, lhs, rhs) VaLUES
         (0, ARRAY[1,0,0], 20),
         (1, ARRAY[0,1,0], 15),
         (2, ARRAY[0,0,1], 20);
 \endverbatim
 
 -# Solve the linear systems with default parameters
 \verbatim
-sql> SELECT madlib.linregr_train('source_table', 
-                                 'output_table', 
-                                 'id',
-                                 'lhs',
-                                 'rhs');
+sql> SELECT madlib.linear_solver_dense('linear_systems_test_data', 
+                                       'output_table', 
+                                       'id',
+                                       'lhs',
+                                       'rhs');
 \endverbatim
 
 -# Obtain the output from the output table
@@ -224,17 +224,14 @@ select madlib.linear_solver_dense(
        'linear_systems_test_data',
        'result_table',
        'id',
-       'a',
-       'b',
+       'lhs',
+       'rhs',
         NULL,
        'direct',
        'algorithm=llt'
        );
 \endverbatim
 
-\anchor Background
-@background
-
 
 @sa File dense_linear_sytems.sql_in documenting the SQL functions.