Skip to content

Commit

Permalink
Documentation: Correct + improve linear systems
Browse files Browse the repository at this point in the history
  • Loading branch information
Mark Wellons authored and Rahul Iyer committed Aug 9, 2013
1 parent 01f256e commit e9cc661
Show file tree
Hide file tree
Showing 4 changed files with 154 additions and 125 deletions.
119 changes: 58 additions & 61 deletions src/ports/postgres/modules/linear_systems/dense_linear_systems.sql_in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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:
Expand All @@ -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> (
...
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>

Expand All @@ -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
Expand All @@ -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>
Expand All @@ -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
Expand All @@ -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.

Expand Down
Loading

0 comments on commit e9cc661

Please sign in to comment.