TooN 2.0.0-beta8
TooN.h
00001 //-*- c++ -*-
00002 
00003 // Copyright (C) 2005,2009 Tom Drummond (twd20@cam.ac.uk),
00004 // Ed Rosten (er258@cam.ac.uk), Gerhard Reitmayr (gr281@cam.ac.uk)
00005 //
00006 // This file is part of the TooN Library.  This library is free
00007 // software; you can redistribute it and/or modify it under the
00008 // terms of the GNU General Public License as published by the
00009 // Free Software Foundation; either version 2, or (at your option)
00010 // any later version.
00011 
00012 // This library is distributed in the hope that it will be useful,
00013 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00014 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015 // GNU General Public License for more details.
00016 
00017 // You should have received a copy of the GNU General Public License along
00018 // with this library; see the file COPYING.  If not, write to the Free
00019 // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
00020 // USA.
00021 
00022 // As a special exception, you may use this file as part of a free software
00023 // library without restriction.  Specifically, if other files instantiate
00024 // templates or use macros or inline functions from this file, or you compile
00025 // this file and link it with other files to produce an executable, this
00026 // file does not by itself cause the resulting executable to be covered by
00027 // the GNU General Public License.  This exception does not however
00028 // invalidate any other reasons why the executable file might be covered by
00029 // the GNU General Public License.
00030 
00031 
00032 #ifndef TOON_INCLUDE_TOON_H
00033 #define TOON_INCLUDE_TOON_H
00034 #include <iostream>
00035 #include <cstdlib>
00036 #include <limits>
00037 #include <new>
00038 #include <utility>
00039 #include <vector>
00040 #include <complex>
00041 #include <TooN/internal/config.hh>
00042 #include <TooN/internal/typeof.hh>
00043 #include <TooN/internal/deprecated.hh>
00044 
00045 #if defined TOON_NDEBUG || defined NDEBUG
00046     #define TOON_NDEBUG_MISMATCH
00047     #define TOON_NDEBUG_SLICE
00048     #define TOON_NDEBUG_SIZE
00049     #define TOON_NDEBUG_FILL
00050 #endif
00051 
00052 #ifdef TOON_INITIALIZE_RANDOM
00053 #include <ctime>
00054 #endif
00055 
00056 #ifdef TOON_USE_LAPACK
00057     #ifndef TOON_DETERMINANT_LAPACK
00058         #define TOON_DETERMINANT_LAPACK 35
00059     #endif
00060 #endif
00061 
00062 ///Everything lives inside this namespace
00063 namespace TooN {
00064 
00065 #ifdef TOON_TEST_INTERNALS
00066     namespace Internal
00067     {
00068         struct BadIndex{};
00069         struct SliceError{};
00070         struct StaticSliceError{};
00071         struct SizeMismatch{};
00072         struct StaticSizeMismatch{};
00073         struct VectorOverfill{};
00074         struct StaticVectorOverfill{};
00075         struct MatrixOverfill{};
00076         struct StaticMatrixOverfill{};
00077         struct Underfill{};
00078     }
00079 #endif
00080     
00081     using std::numeric_limits;
00082     ///Is a number a field? ie, +, -, *, / defined.
00083     ///Specialize this to make TooN work properly with new types.
00084     ///The primary reason for this is to allow SFINAE to work properly.
00085     ///This is required if there are the following two functions:
00086     ///@code 
00087     ///   Vector<> * X  //Generic type X
00088     ///   Vector<> * DiagonalMatrix<>
00089     ///@endcode
00090     ///If one of the functions is a substitution failure, then it will be
00091     ///ignored, allowing the functions to coexist happily. However, not all
00092     ///types of failure are substitution failures. TooN's type deduction happens
00093     ///when determining the return type of the function. This is too early, so
00094     ///the wrong kind of error in the return type deduction causes an error, rather
00095     ///than a substitution failure. The IsField mechanism makes it the right kind of
00096     ///error, thereby allowing a substitution failuer to occur.
00097     ///
00098     ///@internal
00099     ///Internal::Field determines if two classes are in the same field.
00100     ///@ingroup gLinAlg
00101     template<class C> struct IsField
00102     {
00103         static const int value = numeric_limits<C>::is_specialized; ///<Is C a field?
00104     };
00105 
00106     template<class C> struct IsField<std::complex<C> >
00107     {
00108         static const int value = numeric_limits<C>::is_specialized; ///<Is C a field?
00109     };
00110     
00111     ///Specialized for const types
00112     ///@internal
00113     ///Internal::Field determines if two classes are in the same field.
00114     ///@ingroup gLinAlg
00115     template<class C> struct IsField<const C>
00116     {
00117         static const int value = IsField<C>::value; ///<Is C a field?
00118     };
00119 
00120     template<class C, class D> struct These_Types_Do_Not_Form_A_Field;
00121     
00122     ///@internal
00123     ///@brief The namaespace holding all the internal code.
00124     namespace Internal
00125     {
00126         ///@internal
00127         ///@brief Maximum number of bytes to be allocated on the stack.
00128         ///new is used above this number.
00129         static const unsigned int max_bytes_on_stack=1000;
00130         ///@internal
00131         ///@brief A tag used to indicate that a slice is being constructed.
00132         ///@ingroup gInternal
00133         struct Slicing{};
00134         template<int RowStride, int ColStride> struct Slice;
00135         template<int Size, typename Precision, int Stride, typename Mem> struct GenericVBase;
00136     }
00137 
00138     template<int Size, class Precision, class Base> struct Vector;
00139     template<int Rows, int Cols, class Precision, class Base> struct Matrix;
00140     template<int Size, class Precision, class Base> struct DiagonalMatrix;
00141 
00142 
00143     #ifdef DOXYGEN_INCLUDE_ONLY_FOR_DOCS
00144         ///@internal
00145         ///@brief This is a struct used heavily in TooN internals.
00146         ///
00147         ///They have two main uses. The first use is in construction and is completely hidden.
00148         ///For an expression such as a+b, the return value of operator+ will be constructed in
00149         ///place in the return statement, to prevent excessive copying and calls to new/delete.
00150         ///
00151         ///The other use is much more visible and is for objects such as TooN::Zeros and TooN::Idendity .
00152         ///
00153         ///The features allowed (construction, addition, etc) depend on the members present. 
00154         ///For simplicity, general arguments are given below. If members are non-general, then the 
00155         ///operators will simply not be applicable to all vectors or matrices.
00156         ///
00157         ///Operators belong to any of a number of categories depending on the members they provide.
00158         ///The categories are:
00159         ///
00160         /// - Sized operators
00161         ///   - These know their own size and provide. 
00162         ///     The sizes are used only in construction of dynamic vectors or
00163         ///     matrices.
00164         /// - Sizeable operators
00165         ///   - Sizeable operators are able to generate a sized operator of the same sort.
00166         /// - Scalable operators
00167         ///   - These can be multiplied and divided by scalars.
00168         ///
00169         ///@ingroup gInternal
00170         template<typename T> struct Operator{
00171             ///@name Members in the category ``sized operators''
00172             ///@{
00173 
00174             ///This must be provided in order to construct dynamic vectors.
00175             int size() const;
00176             ///This along with num_cols() must be present in order to construct matrices.
00177             int num_rows() const; 
00178             ///This along with num_rows() must be present in order to construct matrices.
00179             int num_cols() const;
00180             ///@}
00181             
00182             ///@name Members used by Vector
00183             ///@{
00184 
00185             ///This function must be present for construction and assignment
00186             ///of vectors to work.
00187             template<int Size, class Precision, class Base>
00188             void eval(Vector<Size, Precision, Base>& v) const;
00189 
00190             ///This must be present for vector += operator
00191             template <int Size, typename P1, typename B1> 
00192             void plusequals(Vector<Size, P1, B1>& v) const;
00193 
00194             ///This must be present for vector -= operator
00195             template <int Size, typename P1, typename B1>
00196             void minusequals(Vector<Size, P1, B1>& v) const;
00197 
00198             ///This function must be present for vector + operator
00199             ///and operator + vector
00200             template <int Size, typename P1, typename B1> 
00201             Operator<T> add(const Vector<Size, P1, B1>& v) const;
00202 
00203             ///This function must be present for vector - operator
00204             template <int Size, typename P1, typename B1> 
00205             Operator<T> rsubtract(const Vector<Size, P1, B1>& v) const;
00206 
00207             ///This function must be present for operator - vector
00208             template <int Size, typename P1, typename B1> 
00209             Operator<T> lsubtract(const Vector<Size, P1, B1>& v) const;
00210 
00211             ///@}
00212 
00213             ///@name Members used by Matrix
00214             ///@{
00215             ///This function must be present for construction and assignment
00216             ///of matrices to work.
00217             template<int R, int C, class P, class B>
00218             void eval(Matrix<R,C,P,B>& m) const; 
00219 
00220             ///This function must be present for matrix + operator
00221             ///and operator + matrix
00222             template <int Rows, int Cols, typename P1, typename B1> 
00223             Operator<T> add(const Matrix<Rows,Cols, P1, B1>& m) const;
00224 
00225 
00226             ///This function must be present for matrix - operator
00227             template <int Rows, int Cols, typename P1, typename B1> 
00228             Operator<T> rsubtract(const Matrix<Rows,Cols, P1, B1>& m) const;
00229 
00230             ///This function must be present for operator - matrix
00231             template <int Rows, int Cols, typename P1, typename B1> 
00232             Operator<T> lsubtract(const Matrix<Rows,Cols, P1, B1>& m) const;
00233 
00234             ///This must be present for matrix += operator
00235             template <int Rows, int Cols, typename P1, typename B1> 
00236             void plusequals(Matrix<Rows,Cols, P1, B1>& m) const;
00237 
00238             ///This must be present for matrix -= operator
00239             template <int Rows, int Cols, typename P1, typename B1> 
00240             void minusequals(Matrix<Rows,Cols, P1, B1>& m) const;
00241             ///@}
00242 
00243 
00244             ///@name Members in the category ``sizeable oberators''
00245             ///@{
00246 
00247             ///Create an operator that knows its size.
00248             ///Suitable for vectors and square matrices.
00249             Operator<T> operator()(int size) const;
00250             
00251             ///Create an operator that knows its size, suitable for matrices.
00252             Operator<T> operator()(int num_rows, int num_cols) const;
00253             ///@}
00254             
00255             ///@name Members in the category ``scalable operators''
00256             ///@{
00257             typedef T Precision; ///<Precision of the operator's scale.
00258             
00259             ///Scale the operator by a scalar and return a new opeator.
00260             template<class Pout, class Pmult> Operator<Internal::Identity<Pout> > scale_me(const Pmult& m) const
00261             {
00262                 return Operator<Internal::Identity<Pout> >(val*m);
00263             }
00264             ///@}
00265 
00266         };
00267     #else
00268         template<typename T> struct Operator;
00269     #endif
00270 
00271     ///Template size value used to indicate dynamically sized vectors and matrices.
00272     static const int Dynamic = -1;
00273     static const int Resizable = -0x7fffffff;
00274 
00275     namespace Internal
00276     {
00277         template<int i, int j> struct SimpleSizer{static const int size=i;};
00278         template<int i> struct SimpleSizer<Dynamic, i>{static const int size=i;};
00279         template<int i> struct SimpleSizer<i, Dynamic>{static const int size=i;};
00280         template<> struct SimpleSizer<Dynamic, Dynamic>    {static const int size=-1;};
00281 
00282         template<int i> struct IsStatic
00283         {
00284             static const bool is = (i!=Dynamic && i != Resizable);
00285         };
00286 
00287         //Choose an output size, given a pair of input sizes. Be static if possible.
00288         template<int i, int j=i> struct Sizer{
00289             static const int size=SimpleSizer<Sizer<i>::size, Sizer<j>::size>::size;
00290         };
00291 
00292         //Choose an output size, given an input size. Be static if possible.
00293         //Otherwise be dynamic. Never generate a resizable vector.
00294         template<int i> struct Sizer<i,i>{
00295             static const int size = IsStatic<i>::is?i:Dynamic;
00296         };
00297     }
00298     
00299     ///All TooN classes default to using this precision for computations and storage.
00300 #ifndef TOON_DEFAULT_PRECISION
00301     typedef double DefaultPrecision;
00302 #else
00303     typedef TOON_DEFAULT_PRECISION DefaultPrecision;
00304 #endif
00305 
00306 #if defined  TOON_FORTRAN_INTEGER && defined TOON_CLAPACK
00307     #error Error: both TOON_FORTRAN_INTEGER and TOON_CLAPACK defined
00308 #elif defined TOON_CLAPACK
00309     typedef long FortranInteger;
00310 #elif defined TOON_FORTRAN_INTEGER
00311     typedef TOON_FORTRAN_INTEGER FortranInteger;
00312 #else
00313     typedef int FortranInteger;
00314 #endif
00315 
00316 }
00317 
00318 #include <TooN/internal/debug.hh>
00319 
00320 #include <TooN/internal/dchecktest.hh>
00321 #include <TooN/internal/allocator.hh>
00322 
00323 #include <TooN/internal/size_mismatch.hh>
00324 #include <TooN/internal/overfill_error.hh>
00325 #include <TooN/internal/slice_error.hh>
00326 
00327 #include <TooN/internal/comma.hh>
00328 
00329 #include <TooN/internal/vbase.hh>
00330 #include <TooN/internal/vector.hh>
00331     
00332 #include <TooN/internal/mbase.hh>
00333 #include <TooN/internal/matrix.hh>
00334 #include <TooN/internal/reference.hh>
00335 
00336 #include <TooN/internal/make_vector.hh>
00337 #include <TooN/internal/operators.hh>
00338     
00339 #include <TooN/internal/objects.h>
00340 
00341 #include <TooN/internal/diagmatrix.h>
00342 
00343 #include <TooN/internal/data.hh>
00344 #include <TooN/internal/data_functions.hh>
00345 
00346 #include <TooN/helpers.h>
00347 #include <TooN/determinant.h>
00348 
00349 #endif