[Toon-members] TooN Doxyfile configure configure.ac doc/docume...

[Edward Rosten]

CVSROOT:        /cvsroot/toon
Module name:    TooN
Changes by:     Edward Rosten <edrosten>        09/12/11 14:27:01

Modified files:
        .              : Doxyfile configure configure.ac 
        doc            : documentation.h 
        internal       : config.hh 
Added files:
        doc            : cramer.gnuplot cramer.h cramer.png 

Log message:
        Doc and version punt. 

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/TooN/Doxyfile?cvsroot=toon&r1=1.13&r2=1.14
http://cvs.savannah.gnu.org/viewcvs/TooN/configure?cvsroot=toon&r1=1.7&r2=1.8
http://cvs.savannah.gnu.org/viewcvs/TooN/configure.ac?cvsroot=toon&r1=1.8&r2=1.9
http://cvs.savannah.gnu.org/viewcvs/TooN/doc/documentation.h?cvsroot=toon&r1=1.40&r2=1.41
http://cvs.savannah.gnu.org/viewcvs/TooN/doc/cramer.gnuplot?cvsroot=toon&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/TooN/doc/cramer.h?cvsroot=toon&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/TooN/doc/cramer.png?cvsroot=toon&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/TooN/internal/config.hh?cvsroot=toon&r1=1.18&r2=1.19

Patches:
Index: Doxyfile
===================================================================
RCS file: /cvsroot/toon/TooN/Doxyfile,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -b -r1.13 -r1.14
--- Doxyfile    27 Oct 2009 16:05:39 -0000      1.13
+++ Doxyfile    11 Dec 2009 14:27:01 -0000      1.14
@@ -23,7 +23,7 @@
 # This could be handy for archiving the generated documentation or 
 # if some version control system is used.
 
-PROJECT_NUMBER         = 2.0.0-beta6
+PROJECT_NUMBER         = 2.0.0-beta7
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
 # base path where the generated documentation will be put. 
@@ -391,7 +391,7 @@
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = . doc/documentation.h optimization internal 
functions/derivatives.h
+INPUT                  = . doc/documentation.h optimization internal 
functions/derivatives.h doc/cramer.h
 
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
@@ -449,7 +449,7 @@
 # directories that contain image that are included in the documentation (see 
 # the \image command).
 
-IMAGE_PATH             = 
+IMAGE_PATH             =  doc/
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should 
 # invoke to filter for each input file. Doxygen will invoke the filter program 

Index: configure
===================================================================
RCS file: /cvsroot/toon/TooN/configure,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -b -r1.7 -r1.8
--- configure   27 Jun 2009 12:27:14 -0000      1.7
+++ configure   11 Dec 2009 14:27:01 -0000      1.8
@@ -1,6 +1,6 @@
 #! /bin/sh
 # Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.63 for TooN version-2.0.0-beta2.
+# Generated by GNU Autoconf 2.63 for TooN version-2.0.0-beta7.
 #
 # Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001,
 # 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@@ -596,8 +596,8 @@
 # Identity of this package.
 PACKAGE_NAME='TooN'
 PACKAGE_TARNAME='toon'
-PACKAGE_VERSION='version-2.0.0-beta2'
-PACKAGE_STRING='TooN version-2.0.0-beta2'
+PACKAGE_VERSION='version-2.0.0-beta7'
+PACKAGE_STRING='TooN version-2.0.0-beta7'
 PACKAGE_BUGREPORT=''
 
 ac_subst_vars='LTLIBOBJS
@@ -1213,7 +1213,7 @@
   # Omit some internal or obsolete options to make the list less imposing.
   # This message is too long to be a string in the A/UX 3.1 sh.
   cat <<_ACEOF
-\`configure' configures TooN version-2.0.0-beta2 to adapt to many kinds of 
systems.
+\`configure' configures TooN version-2.0.0-beta7 to adapt to many kinds of 
systems.
 
 Usage: $0 [OPTION]... [VAR=VALUE]...
 
@@ -1274,7 +1274,7 @@
 
 if test -n "$ac_init_help"; then
   case $ac_init_help in
-     short | recursive ) echo "Configuration of TooN version-2.0.0-beta2:";;
+     short | recursive ) echo "Configuration of TooN version-2.0.0-beta7:";;
    esac
   cat <<\_ACEOF
 
@@ -1360,7 +1360,7 @@
 test -n "$ac_init_help" && exit $ac_status
 if $ac_init_version; then
   cat <<\_ACEOF
-TooN configure version-2.0.0-beta2
+TooN configure version-2.0.0-beta7
 generated by GNU Autoconf 2.63
 
 Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001,
@@ -1376,7 +1376,7 @@
 This file contains any messages produced by compilers while
 running configure, to aid debugging if configure makes a mistake.
 
-It was created by TooN $as_me version-2.0.0-beta2, which was
+It was created by TooN $as_me version-2.0.0-beta7, which was
 generated by GNU Autoconf 2.63.  Invocation command line was
 
   $ $0 $@
@@ -3173,7 +3173,7 @@
 # report actual input values of CONFIG_FILES etc. instead of their
 # values after options handling.
 ac_log="
-This file was extended by TooN $as_me version-2.0.0-beta2, which was
+This file was extended by TooN $as_me version-2.0.0-beta7, which was
 generated by GNU Autoconf 2.63.  Invocation command line was
 
   CONFIG_FILES    = $CONFIG_FILES
@@ -3232,7 +3232,7 @@
 _ACEOF
 cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
 ac_cs_version="\\
-TooN config.status version-2.0.0-beta2
+TooN config.status version-2.0.0-beta7
 configured by $0, generated by GNU Autoconf 2.63,
   with options \\"`$as_echo "$ac_configure_args" | sed 's/^ //; 
s/[\\""\`\$]/\\\\&/g'`\\"
 

Index: configure.ac
===================================================================
RCS file: /cvsroot/toon/TooN/configure.ac,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -b -r1.8 -r1.9
--- configure.ac        27 Oct 2009 16:05:39 -0000      1.8
+++ configure.ac        11 Dec 2009 14:27:01 -0000      1.9
@@ -1,4 +1,4 @@
-AC_INIT(TooN, version-2.0.0-beta6)
+AC_INIT(TooN, version-2.0.0-beta7)
 AC_COPYRIGHT([Copyright T. Drummond, E. Rosten, G. Reitmayr 2006, 2007, 2008, 
2009])
 AC_LANG(C++)
 AC_PROG_CXX

Index: doc/documentation.h
===================================================================
RCS file: /cvsroot/toon/TooN/doc/documentation.h,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -b -r1.40 -r1.41
--- doc/documentation.h 27 Oct 2009 16:05:39 -0000      1.40
+++ doc/documentation.h 11 Dec 2009 14:27:01 -0000      1.41
@@ -32,9 +32,9 @@
        - @link gFunctions Functions (eg numerical derivatives) @endlink
 
 It provides classes for statically- (known at compile time) and dynamically-
-(unknown at compile time) sized vectors and matrices and it delegates advanced
-functions (like SVD or multiplication of large matrices) to LAPACK and BLAS
-(this means you will need libblas and liblapack).
+(unknown at compile time) sized vectors and matrices and it can delegate
+advanced functions (like large SVD or multiplication of large matrices) to
+LAPACK and BLAS (this means you will need libblas and liblapack).
 
 The library makes substantial internal use of templates to achieve run-time
 speed efficiency whilst retaining a clear programming syntax.
@@ -45,6 +45,7 @@
  - Because it supports transposition, subscripting and slicing of matrices (to 
obtain a vector) very efficiently.
  - Because it interfaces well to other libraries.
  - Because it exploits LAPACK and BLAS (for which optimised versions exist on 
many platforms).
+ - Because it is fast, \link sCramerIsBad but not at the expense of numerical 
stability. \endlink
 
 \section sUsage How to use TooN
 This section is arranged as a FAQ. Most answers include code fragments. Assume
@@ -231,23 +232,6 @@
                Vector.slice<Dynamic, 2>(3, 2);   //Slice starting at index 3, 
of length 2.
                @endcode
 
-               Slicing can also be perferformed relative to the end of a 
vector.
-
-               WARNING:
-                - NOT YET IMPLEMENTED FOR MATRIX
-                - EXPERIMANTAL: MAY BE SUBJECT TO CHANGE
-                - STATIC SLICES ONLY GO UP TO <code>End<-99></code>
-
-               @code
-               Vector<6> v;
-               v.slice<1, End<0> >();    //Equivalent to v.slice<1, 5>
-               v.slice<2, End<-1> >();   //Equivalent to v.slice<2, 3>
-
-               v.slice(1, End);          //Equivalent to v.slice(1, 5);
-               v.slice(3, End(-2));      //Equivalent to v.slice(3, 2);
-               @endcode
-
-
                See also \ref sSlices
 
        \subsection sInitialize How I initialize a vector/matrix?
@@ -362,6 +346,7 @@
        The debugging checks can be disabled by defining either of the 
following macros:
        - \c TOON_NDEBUG
        - \c NDEBUG 
+
        Additionally, individual checks can be disabled with the following 
macros:
        - Static/Dynamic mismatch
                - Statically determined functions accept and ignore dynamically 
specified

Index: internal/config.hh
===================================================================
RCS file: /cvsroot/toon/TooN/internal/config.hh,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -b -r1.18 -r1.19
--- internal/config.hh  3 Dec 2009 20:14:49 -0000       1.18
+++ internal/config.hh  11 Dec 2009 14:27:01 -0000      1.19
@@ -1,13 +1,14 @@
-#undef TOON_TYPEOF_DECLTYPE
+/* internal/config.hh.  Generated from config.hh.in by configure.  */
+/* #undef TOON_TYPEOF_DECLTYPE */
 
-#undef TOON_TYPEOF_TYPEOF
+/* #undef TOON_TYPEOF_TYPEOF */
 
-#undef TOON_TYPEOF___TYPEOF__
+#define TOON_TYPEOF___TYPEOF__ 1
 
-#undef TOON_TYPEOF_BOOST
+/* #undef TOON_TYPEOF_BOOST */
 
-#undef TOON_TYPEOF_BUILTIN
+/* #undef TOON_TYPEOF_BUILTIN */
 
-#undef TOON_DEPRECATED_GCC
+#define TOON_DEPRECATED_GCC 1
 
-#undef TOON_USE_LAPACK
+#define TOON_USE_LAPACK 1

Index: doc/cramer.gnuplot
===================================================================
RCS file: doc/cramer.gnuplot
diff -N doc/cramer.gnuplot
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ doc/cramer.gnuplot  11 Dec 2009 14:27:01 -0000      1.1
@@ -0,0 +1 @@
+; set xlabel "{/Symbol e}"; set ylabel "Error"; set logscale x 10; set 
logscale y 10; set terminal postscript eps color enhanced solid ; plot 
[1e-20:1] [*:*]  "out.txt" using 1:2  with line title "LAPACK LU", "out.txt" 
using 1:3  with line title "Gauss-Jordan", "out.txt" using 1:4  with line title 
"GR-SVD pesudoinverse", "out.txt" using 1:5  with line title "Gaussian 
elimination", "out.txt" using 1:6  with line title "Cramers's rule"

Index: doc/cramer.h
===================================================================
RCS file: doc/cramer.h
diff -N doc/cramer.h
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ doc/cramer.h        11 Dec 2009 14:27:01 -0000      1.1
@@ -0,0 +1,128 @@
+/**
+\page sCramerIsBad Speed, but not at the expense of accuracy.
+
+TooN aims to be a fast library, and may choose between one of several 
algorithms
+depending on the size of the arguments. However TooN will never substitute a
+fast but numerically inferior algorithm.  For example LU decomposition, 
Gaussian
+elimination and Gauss-Jordan reduction all have similar numerical properties 
for
+computing a matrix inverse. Direct inversino using Cramer's rule is
+significantly less stable, even for 3x3 matrices.
+
+The following code computes a matrix inverse of the ill conditioned matrix:
+\f[
+\begin{bmatrix}
+1  & 2 & 3 \\
+1  & 2 + \epsilon & 3 \\
+1  & 2  & 3 + \epsilon
+\end{bmatrix},
+\f]
+using LU decomposition, Gauss-Jordan, pseudo-inverse with singular value
+decomposition and with Cramer's rule. The error is computed as:
+\f[
+       \|A^{-1} A - I\|_{\text{fro}}
+\f]
+The code is:
+
address@hidden
+#include <TooN/TooN.h>
+#include <TooN/helpers.h>
+#include <TooN/LU.h>
+#include <TooN/GR_SVD.h>
+#include <TooN/gauss_jordan.h>
+#include <TooN/gaussian_elimination.h>
+#include <iomanip>
+using namespace TooN;
+using namespace std;
+Matrix<3> invert_cramer(const Matrix<3>& A)
+{
+       Matrix<3> i;
+       double t0 = 
A[0][0]*A[1][1]*A[2][2]-A[0][0]*A[1][2]*A[2][1]-A[1][0]*A[0][1]*A[2][2]+A[1][0]*A[0][2]*A[2][1]+A[2][0]*A[0][1]*A[1][2]-A[2][0]*A[0][2]*A[1][1];
+       double idet = 1/t0;
+       t0 = A[1][1]*A[2][2]-A[1][2]*A[2][1];
+       i[0][0] = t0*idet;
+       t0 = -A[0][1]*A[2][2]+A[0][2]*A[2][1];
+       i[0][1] = t0*idet;
+       t0 = A[0][1]*A[1][2]-A[0][2]*A[1][1];
+       i[0][2] = t0*idet;
+       t0 = -A[1][0]*A[2][2]+A[1][2]*A[2][0];
+       i[1][0] = t0*idet;
+       t0 = A[0][0]*A[2][2]-A[0][2]*A[2][0];
+       i[1][1] = t0*idet;
+       t0 = -A[0][0]*A[1][2]+A[0][2]*A[1][0];
+       i[1][2] = t0*idet;
+       t0 = A[1][0]*A[2][1]-A[1][1]*A[2][0];
+       i[2][0] = t0*idet;
+       t0 = -A[0][0]*A[2][1]+A[0][1]*A[2][0];
+       i[2][1] = t0*idet;
+       t0 = A[0][0]*A[1][1]-A[0][1]*A[1][0];
+       i[2][2] = t0*idet;
+
+       return i;
+}
+
+
+int main()
+{
+       Matrix<3> singular = Data(1, 2, 3,
+                                                         1, 2, 3,
+                                                         1, 2, 3);
+       
+       
+       for(double i=0; i < 1000; i++)
+       {
+               double delta = pow(0.9, i);     
+               
+               //Make a poorly conditioned matrix
+               Matrix<3> bad = singular;
+               bad[2][2] += delta;
+               bad[1][1] += delta;
+
+               
+               //Compute the inverse with LU decomposition
+               Matrix<3> linv;
+               LU<3> blu(bad);
+               linv = blu.get_inverse();
+
+               //Compute the inverse with Gauss-Jordan reduction
+               Matrix<3, 6> gj;
+               Matrix<3> ginv;
+               gj.slice<0,0,3,3>() = bad;
+               gj.slice<0,3,3,3>() = Identity;
+               gauss_jordan(gj);
+               ginv = gj.slice<0,3,3,3>();
+
+
+               //Compute the pseudo-inverse with singular value decomposition
+               GR_SVD<3,3> bsvd(bad);
+               Matrix<3> sinv = bsvd.get_pinv();
+
+
+               Matrix<3> I = Identity;
+               Matrix<3> einv = gaussian_elimination(bad, I);
+
+               Matrix<3> cinv = invert_cramer(bad);
+               
+               
+               double lerr = norm_fro(linv * bad + -1 * Identity);
+               double gerr = norm_fro(ginv * bad + -1 * Identity);
+               double serr = norm_fro(sinv * bad + -1 * Identity);
+               double cerr = norm_fro(cinv * bad + -1 * Identity);
+               double eerr = norm_fro(einv * bad + -1 * Identity);
+
+               cout << setprecision(15) << scientific << delta << " " << lerr 
<< " " << gerr << " " << serr << " " << eerr << " " << cerr << endl;
+
+
+
+       }
+
+
+}
address@hidden
+
+The direct inverse with Cramer's rule is about three times faster than the
+builtin routines. However, the numerical stability is considerably worse,
+giving errors 1e6 times higher in extreme cases:
+
+\image html cramer.png "Comparison of errors in matrix inverse"
+
+*/

Index: doc/cramer.png
===================================================================
RCS file: doc/cramer.png
diff -N doc/cramer.png
Binary files /dev/null and /tmp/cvsZgSz3b differ