main.h

00001 /*
00002   -------------------------------------------------------------------
00003   
00004   Copyright (C) 2006, 2007, Andrew W. Steiner
00005   
00006   This file is part of O2scl.
00007   
00008   O2scl is free software; you can redistribute it and/or modify
00009   it under the terms of the GNU General Public License as published by
00010   the Free Software Foundation; either version 3 of the License, or
00011   (at your option) any later version.
00012   
00013   O2scl is distributed in the hope that it will be useful,
00014   but WITHOUT ANY WARRANTY; without even the implied warranty of
00015   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00016   GNU General Public License for more details.
00017   
00018   You should have received a copy of the GNU General Public License
00019   along with O2scl. If not, see <http://www.gnu.org/licenses/>.
00020 
00021   -------------------------------------------------------------------
00022 */
00023 /** 
00024     \mainpage O2scl User's Guide
00025 
00026     \htmlonly
00027     <div align="right">
00028     <a href="dl_page.html"><b>Download o2scl
00029     </b></a></div>
00030     \endhtmlonly
00031 
00032     O2scl is a C++ class library for object-oriented numerical
00033     programming. It includes
00034     - Classes based on numerical routines from GSL and CERNLIB
00035     - Vector and matrix classes which are fully compatible with
00036     \c gsl_vector and \c gsl_matrix, yet offer indexing with
00037     \c operator[] and other object-oriented features
00038     - The CERNLIB-based classes are rewritten in C++ and are often 
00039     faster than their GSL counterparts
00040     - Classes which require function inputs are designed to accept
00041     (public or private) member functions, even if they are virtual.
00042     - Classes use templated vector types, which allow the use of 
00043     object-oriented vectors or C-style arrays. Because of this,
00044     the O2scl versions of GSL algorithms can be signficantly faster
00045     than the original.
00046     - Highly compatible - Recent versions have been tested on 
00047     Linux (32- and 64-bit systems, with Intel and AMD chips), 
00048     Windows XP with Cygwin, and MacOSX.
00049     - Free! O2scl is provided under Version 3 of the GNU 
00050     Public License
00051     - Two mini-libraries
00052     <ul>
00053     <li>Thermodynamics of ideal and nearly-ideal particles with
00054     quantum statistics</li>
00055     <li>Equations of state for finite density relelvant for 
00056     neutron stars</li>
00057     </ul>
00058 
00059     See licensing information at \ref license_section. 
00060 
00061     This is a \b pre- \f$ \beta \f$ \b version. While I have released
00062     it to anyone who finds it useful, there may still be some bugs
00063     lurking around. I use many of these classes myself frequently and
00064     most things have been tested.
00065 
00066     \htmlonly
00067     <hr />
00068     <a href="dl_page.html">Download o2scl</a>
00069     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
00070     <a href="../latex/refman.pdf">PDF documentation</a>
00071     \endhtmlonly
00072 
00073     \hline
00074     \section toc_section Quick Reference to User's Guide
00075     
00076     - \ref install_section
00077     - \ref usage_section
00078     - \ref cplxnum_section
00079     - \ref examples_section
00080     - \ref vecmat_section
00081     - \ref intp_section
00082     - \ref const_section
00083     - \ref funct_section
00084     - \ref table_section
00085     - \ref string_section
00086     - \ref diff_section
00087     - \ref inte_section
00088     - \ref poly_section
00089     - \ref solve_section
00090     - \ref min_section
00091     - \ref mcarlo_section
00092     - \ref anneal_section
00093     - \ref fit_section
00094     - \ref ode_section
00095     - \ref rng_section
00096     - \ref tintp_section
00097     - \ref other_section
00098     - \ref lset_section
00099     - \ref io_section
00100     - \ref design_section
00101     - \ref license_section
00102     - \ref ack_section
00103     - \ref ref_section
00104     - \ref todo 
00105     - \ref bug
00106 
00107     \htmlonly
00108     <UL><LI>Other mini-libraries
00109     <UL>
00110     <LI><B><a href="../part/html/index.html">Particles</a></b>
00111     <LI><B><a href="../eos/html/index.html">Equations of State</a></b>
00112     </UL>
00113     </LI>
00114     <br />
00115     <li>Add-on library: There is also a related library,
00116     <a href="../../o2scl_ext/html/index.html">O2scl_ext</a>,
00117     which has a separate source distribution.
00118     </li>
00119     </UL>
00120     \endhtmlonly
00121 
00122     \hline
00123     \section motiv_section Motivation
00124 
00125     I wanted a library for numerical programming in C++. This
00126     immediately suggests the following question: Why C++? Part of the
00127     answer to this question is practical; I am much more familiar with
00128     C/C++ so learning a different language (e.g. Fortran) never seemed
00129     like it made much sense. A related question might be: Why not an
00130     interpreted language, like python? Answer: faster
00131     execution. Finally, why C++ and not C? Answer: The object-oriented
00132     approach arguably allows for simpler and faster development while
00133     not appreciably removing flexibility. The object-orientation also
00134     encourages library development.  Furthermore, I find the syntactic
00135     simplicity provided by C++ to be very convient at times.
00136 
00137     In regards to the GNU Scientific Library (GSL), GSL is not simple
00138     to use for C++ development because it makes it very difficult to
00139     utilize member functions in those routines which take functions as
00140     inputs.
00141 
00142     I have also allowed the classes to hide their memory allocation
00143     structure, even though the user is frequently allowed to specify
00144     when it is allocated or deallocated. In light of the philosophy of
00145     'encapsulation' this makes sense, as the memory requirements for
00146     the classes are not generic. Users who do not know about the
00147     details of the algorithm need not know about the details of the
00148     memory requirements, and users who need to know about the details
00149     of the memory requirements most often also want to know the
00150     details about the algorithm.
00151 
00152     \hline
00153     \section install_section Installation
00154 
00155     The rules for installation are generally the same as that for
00156     other GNU libraries. The file \c INSTALL has some details on this
00157     procedure. Generally, you should be able to run \c ./configure and
00158     then type \c make and \c make \c install. The documentation is
00159     automatically installed by \c make \c install. 
00160 
00161     After \c make \c install, you may test the library by \c make \c
00162     o2scl-test. This should output a summary which is reproduced in
00163     the file \c test-summary.text. If the compilation of the test
00164     programs doesn't work, you may have to add the correct directory
00165     to the \c LD_LIBRARY_PATH environment variable between
00166     installation and testing.
00167 
00168     This library requires GSL and is designed to work with GSL
00169     versions 1.9 or 1.10. Some classes may work with older versions of GSL,
00170     but this cannot be guaranteed. 
00171 
00172     Range-checking for vectors and matrices is performed similar to
00173     the GSL approach, and is turned off by default. You can 
00174     enable range-checking by defining \c GSL_RANGE_CHECK=1, e.g.
00175     \code
00176     CPPFLAGS="-DGSL_RANGE_CHECK=1" ./configure
00177     \endcode
00178 
00179     The separate libraries o2scl_eos and o2scl_part are installed
00180     by default. To disable these libraries, configure with 
00181     \c --disable-eoslib or \c --disable-partlib.
00182     Note that o2scl_eos depends on o2scl_part so using \c --disable-partlib
00183     without \c --disable-eoslib may not work. 
00184 
00185     There are several warning flags that are useful when configuring
00186     and compiling with \c g++. (See the GSL documentation for an 
00187     excellent discussion.) For running \c configure, I use
00188     something like
00189     \code
00190     CFLAGS="" CXXFLAGS="" CPPFLAGS="-ansi -pedantic -Wall -W           \
00191     -Wconversion -Wno-unused -Wshadow -Wpointer-arith -Wcast-align     \
00192     -Wwrite-strings -fshort-enums -ggdb -O3 -DGSL_RANGE_CHECK=0        \
00193     -DHAVE_INLINE -I/home/asteiner/install/include"                    \
00194     LDFLAGS="-L/home/asteiner/install/lib" ./configure -C              \
00195     --enable-readline --prefix=/home/asteiner/install
00196     \endcode
00197     with the references to the directory \c /home/asteiner/install 
00198     in order to install somewhere in my user directory, and because
00199     my copy of GSL is installed there, rather than in \c /usr/local.
00200     
00201     The documentation is generated with Doxygen. In principle, the 
00202     documentation can be regenerated by the end-user, but this is 
00203     not supported and may require several external applications
00204     not included in the distribution.
00205 
00206     \b Un-installation: While there is no explicit "uninstall"
00207     procedure, there are only a couple places to check. Installation
00208     creates directories named \c o2scl in the include, doc and shared
00209     files directory (which default to \c /usr/local/include, \c
00210     /usr/local/doc, and \c /usr/local/share) which can be
00211     removed. Finally, all of the libraries are named with the prefix
00212     \c libo2scl and are created by default in /usr/local/lib. As
00213     configured with the settings above, the files are in \c
00214     /home/asteiner/install/include/o2scl, \c /home/asteiner/install/lib,
00215     \c /home/asteiner/install/share/o2scl, and \c
00216     /home/asteiner/install/doc/o2scl.
00217 
00218     \hline
00219     \section usage_section General Usage
00220 
00221     \b Namespaces
00222     
00223     Most of the classes reside in the namespace \c o2scl (removed from
00224     the documentation). Numerical and physical constants (many of them
00225     based on the GSL constants) are placed in separate
00226     namespaces. There are a couple other (mostly internal) namespaces
00227     which are documented separately.
00228 
00229     \b Documentation \b conventions
00230 
00231     In the following documentation, function parameters are denoted by
00232     \c parameter, except when used in mathematical formulas as in \f$
00233     \mathrm{variable} \f$ .
00234     
00235     \b Nomenclature
00236 
00237     Classes directly derived from the GNU Scientific Library are
00238     preceeded by the prefix \c gsl_ and classes derived from CERNLIB
00239     are preceeded by the prefix \c cern_. Some of those classes 
00240     derived from GSL and CERNLIB operate slightly differently 
00241     from the original versions. The differences are detailed
00242     in the corresponding class documentation.
00243     
00244     \b Error \b handling
00245 
00246     Error handling is GSL-like with functions returning 0 for success
00247     and calling a GSL-like error handler. The error handler, 
00248     \ref err_hnd is a global pointer to an object of type \ref err_class.
00249     
00250     The default behaviour for all errors is simply store the error
00251     code and information. You can require the default error handler to
00252     print out any error (or even exit) using \ref
00253     err_class::set_mode(). Also, if O2SCL_ARRAY_ABORT is defined,
00254     then \c exit() will be called any time a \ref gsl_index error is
00255     called, e.g. an out-of-bounds array access.
00256 
00257     Errors can be set through the macros \ref set_err, \ref set_err_ret, 
00258     \ref add_err, and \ref add_err_ret, which are defined in the
00259     file err_hnd.h.
00260 
00261     Functionality similar to assert() is provided with the macro
00262     \ref err_assert, which exits if its argument is non-zero, and 
00263     \ref bool_assert which exits if its argument is false.
00264 
00265     Note that the library functions do not typically try to 
00266     reset the error handler. For this reason the user may 
00267     need to reset the error handler before calling functions 
00268     which do not return an integer error value so that they
00269     can easily test to see if an error occured, e.g. using
00270     err_hnd::get_errno().
00271 
00272     The default error handler can be replaced by simply assigning
00273     the address of a descendant of \ref err_class to \ref err_hnd.
00274 
00275     \b Library \b dependencies
00276 
00277     All of the libraries need \c libo2scl_base, \c libgsl, and either \c
00278     libgslcblas or some externally-specified \c libcblas to
00279     operate. Other additional dependencies are listed below:
00280     - \c libo2scl_eos needs \c libo2scl_nuclei, \c libo2scl_part, 
00281     \c libo2scl_other, \c libo2scl_minimize, \c libo2scl_inte, and 
00282     \c libo2scl_root
00283     - \c libo2scl_nuclei needs \c libo2scl_part, \c libo2scl_other, 
00284     \c libo2scl_inte, and \c libo2scl_root.
00285     - \c libo2scl_part needs \c libo2scl_other, \c libo2scl_inte, and 
00286     \c libo2scl_root.
00287 
00288     \hline
00289     \section examples_section Example programs
00290     
00291     A few example programs are in the \c examples directory.
00292     After installation, they can be compiled and 
00293     executed by running \c make \c o2scl-examples in that directory. 
00294 
00295     Also, the testing code for each class is frequently useful for
00296     providing examples of their usage.  The testing source code for
00297     each source file is named with an \c _ts.cpp prefix in the same
00298     directory as the class source.
00299       
00300     \hline
00301     \section cplxnum_section Complex Numbers
00302     
00303     Some rudimentary arithmetic operators for \c gsl_complex are
00304     defined in cx_arith.h, but no constructor has been written. The
00305     object \c gsl_complex is still a \c struct, not a \c class. For
00306     example,
00307     \code
00308     gsl_complex a={{1,2}}, b={{3,4}};
00309     gsl_complex c=a+b;
00310     cout << GSL_REAL(c) << " " << GSL_IMAG(C) << endl;
00311     \endcode
00312     In case the user needs to convert between \c gsl_complex and \c
00313     std::complex<double>, two conversion functions gsl_to_complex()
00314     and complex_to_gsl() are provided in \ref ovector_cx_tlate.h.
00315 
00316     \hline
00317     \section vecmat_section Vectors, Matrices and Tensors
00318 
00319     \b Introduction
00320 
00321     Vectors and matrices are designed using the templates \ref
00322     ovector_tlate and \ref omatrix_tlate, which are compatible with \c
00323     gsl_vector and \c gsl_matrix. Vectors and matrices with unit
00324     stride are provided in \ref uvector_tlate and \ref
00325     umatrix_tlate. The most commonly used double-precision versions of
00326     these template classes are \ref ovector, \ref omatrix, \ref
00327     uvector and \ref umatrix, and their associated "views" (analogous
00328     to GSL vector and matrix views) which are named with a \c _view
00329     suffix. The classes \ref ovector_tlate and \ref omatrix_tlate
00330     offer the syntactic simplicity of array-like indexing, which is
00331     easy to apply to vectors and matrices created with GSL.
00332 
00333     The following sections primarily discuss the operation objects of
00334     type \ref ovector. The generalizations to objects of type \ref
00335     uvector, \ref omatrix, and the complex vector and matrix objects
00336     \ref ovector_cx, \ref omatrix_cx, \ref uvector_cx, and \ref
00337     umatrix_cx are straightforward.
00338 
00339     \b Views
00340 
00341     Vector and matrix views are provided as parents of the vector and
00342     matrix classes which do not have methods for memory allocation. As
00343     in GSL, it is simple to "view" normal C-style arrays or pointer
00344     arrays (see \ref ovector_array), parts of vectors (\ref
00345     ovector_subvector), and rows and columns of matrices (\ref
00346     omatrix_row and \ref omatrix_col). Several operations are defined,
00347     including addition, subtraction, and dot products.
00348 
00349     \b Typedefs
00350 
00351     Several typedefs are used to give smaller names to often used
00352     templates. Vectors and matrices of double-precision numbers all
00353     begin with the prefixes \ref ovector and \ref omatrix. Integer
00354     versions begin with the prefixes \ref ovector_int and \ref
00355     omatrix_int. Complex versions have an additional \c "_cx",
00356     e.g. \ref ovector_cx. See \ref ovector_tlate.h, \ref
00357     ovector_cx_tlate.h, \ref omatrix_tlate.h, and \ref
00358     omatrix_cx_tlate.h.
00359 
00360     \b Unit-stride \b vectors
00361 
00362     The \ref uvector_tlate objects are naturally somewhat faster
00363     albeit less flexible than their finite-stride counterparts.
00364     Conversion to GSL vectors and matrices is not trivial for \ref
00365     uvector_tlate objects, but demands copying the entire
00366     vector. Vector views, operators, and the nomenclature is similar
00367     to that of \ref ovector. 
00368 
00369     These unit-stride vectors are very useful to help optimize the
00370     internal workings of functions that do not need a finite stride.
00371 
00372     \b Memory \b allocation
00373 
00374     Memory for vectors can be allocated using ovector::allocate() and
00375     ovector::free(). Allocation can also be performed by the
00376     constructor, and the destructor automatically calls free() if
00377     necessary. In contrast to \c gsl_vector_alloc(),
00378     ovector::allocate() will call ovector::free(), if necessary, to
00379     free previously allocated space. Allocating memory does not clear
00380     the recently allocated memory to zero.  You can use \ref
00381     ovector::set_all() with an argument of \c 0.0 to clear a vector
00382     (and similarly for a matrix).
00383 
00384     If the memory allocation fails, either in the constructor or in
00385     allocate(), then the error handler will be called, partially
00386     allocated memory will be freed, and the size will be reset to
00387     zero. You can either use the error handler or test to see if the
00388     allocation succeeded by examining the size argument, e.g.
00389     \code
00390     const size_t n=10;
00391     ovector x(10);
00392     if (x.size()==0) cout << "Failed." << endl;
00393     \endcode
00394     
00395     \b Get \b and \b set
00396     
00397     Vectors and matrices can be modified using ovector::get() and
00398     ovector::set() methods analogous to \c gsl_vector_get() and \c
00399     gsl_vector_set(), or they can be modified through
00400     ovector::operator[] (or ovector::operator() ), e.g.
00401     \code
00402     ovector a(4);
00403     a.set(0,2.0);
00404     a.set(1,3.0);
00405     a[2]=4.0;
00406     a[3]=2.0*a[1];
00407     \endcode
00408 
00409     If you want to set all of the values in an \ref ovector or an \ref
00410     omatrix at the same time, then use ovector::set_all() or
00411     omatrix::set_all().
00412 
00413     \b Range \b checking
00414     
00415     Range checking is performed depending on whether or not \c
00416     O2SCL_NO_RANGE_CHECK is defined. It can be defined in the
00417     arguments to \c ./configure upon installation to turn off range
00418     checking. Note that this is completely separate from the GSL range
00419     checking mechanism, so range checking may be on in O2scl even if
00420     it has been turned off in GSL.  Range checking is used primarily
00421     in the vector, matrix, and tensor \c get() and \c set() methods.
00422 
00423     To see if range checking was turned on during installation
00424     (without calling the error handler), use
00425     lib_settings_class::range_check().
00426 
00427     Note that range checking in O2scl code is present in header files,
00428     rather than in source code. This means that range checking can be
00429     turned on or off in user-defined functions separately from whether
00430     or not it was used in the library classes and functions.
00431 
00432     \b Shallow \b and \b deep \b copy
00433 
00434     Copying O2scl vectors using constructors or the \c = operator
00435     is performed according to what kind of object is
00436     on the left-hand side (LHS) of the equals sign. If the LHS is a
00437     view, then a shallow copy is performed, and if the LHS is a \ref
00438     ovector, then a deep copy is performed. If an attempt is made to
00439     perform a deep copy onto a vector that has already been allocated,
00440     then that previously allocated memory is automatically freed. 
00441     The user must be careful to ensure that information is not lost
00442     this way, even though no memory leak will occur.
00443     
00444     For generic deep vector and matrix copying, you can use the
00445     template functions \ref vector_copy(), \ref matrix_copy(), \ref
00446     vector_cx_copy(), and \ref matrix_cx_copy() defined in the 
00447     o2scl_arith namespace. These would allow you, for example, to 
00448     copy an \ref ovector to a \c std::vector<double> object (assuming
00449     the memory allocation has already been taken care of). 
00450 
00451     \b Compatibility \b with \b MV++
00452     
00453     There is also a moderate amount of compatibility between
00454     \ref ovector_tlate, \ref ovector_view_tlate, \ref uvector_tlate, 
00455     \c std::vector<> and the vectors from \c MV++. They all offer
00456     - A blank constructor to create an empty vector
00457     - A constructor with a "size" argument (\c size_t or \c int) to
00458     create a vector with a specified size.
00459     - \c operator=() - Copy constructor
00460     - \c operator[] - Array-indexing
00461     - \c size() - Get the "size" of the vector
00462 
00463     There is a slight difference between how this works in comparison
00464     to MV++. The function allocate() operates a little differently
00465     than newsize(), as it will feel free to allocate new memory when
00466     owner is false, i.e. it will allocate memory for a new vector even
00467     if it previously pointed to a vector whose memory it did not
00468     own. This should not be an issue, however, since it is not
00469     possible to create an \ref ovector_tlate with a value of \c owner
00470     equal to zero, unless the \ref ovector_tlate class is overloaded
00471     improperly.
00472     
00473     \b Vector \b and \b matrix \b arithmetic
00474     
00475     Several operators are available as member functions of the
00476     corresponding template:
00477     
00478     Vector_view unary operators:
00479     - vector_view += vector_view
00480     - vector_view -= vector_view
00481     - vector_view += scalar
00482     - vector_view -= scalar
00483     - vector_view *= scalar
00484     - scalar = norm(vector_view)
00485 
00486     Matrix_view unary operators:
00487     - matrix += matrix
00488     - matrix -= matrix
00489     - matrix += scalar
00490     - matrix -= scalar
00491     - matrix *= scalar
00492 
00493     Binary operators like addition, subtraction, and matrix
00494     multiplication are also defined for \ref ovector, \ref uvector,
00495     and related objects in the \ref o2scl_arith namespace. The generic
00496     template for a binary operator, e.g.
00497     \code
00498     template<class vec_t> vec_t &operator+(vec_t &v1, vec_t &v2);
00499     \endcode
00500     is difficult because the compiler has no way of distinguishing vector 
00501     and non-vector classes. At the moment, this is solved by 
00502     creating a define macro for the binary operators. In addition
00503     to the predefined operators for native classes, the user may 
00504     also define binary operators for other classes using the same
00505     macros. For example, 
00506     \code
00507     O2SCL_OP_VEC_VEC_ADD(o2scl::ovector,std::vector<double>,
00508     std::vector<double>)
00509     \endcode
00510     would provide an addition operator for \ref ovector and vectors
00511     from the Standard Template Library. The macros are detailed
00512     in \ref vec_arith.h.
00513 
00514     The GSL BLAS routines can also be used directly with \ref ovector
00515     and \ref omatrix objects.
00516 
00517     Note that some of these arithmetic operations succeed even with
00518     non-matching vector and matrix sizes. For example, adding a 3x3
00519     matrix to a 4x4 matrix will result in a 3x3 matrix and the 7 outer
00520     elements of the 4x4 matrix are ignored.
00521 
00522     \b Converting \b to \b and \b from \b GSL \b forms
00523 
00524     Because of the way \ref ovector is constructed, you may use
00525     type conversion to convert to and from objects of type \c gsl_vector.
00526     \code
00527     ovector a(2);
00528     a[0]=1.0;
00529     a[1]=2.0;
00530     gsl_vector *g=(gsl_vector *)(&a);
00531     cout << gsl_vector_get(g,0) << " " << gsl_vector_get(g,1) << endl;
00532     \endcode
00533     Or,
00534     \code
00535     gsl_vector *g=gsl_vector_alloc(2);
00536     gsl_vector_set(0,1.0);
00537     gsl_vector_set(1,2.0);
00538     ovector &a=(ovector &)(*g);
00539     cout << a[0] << " " << a[1] << endl;
00540     \endcode
00541     This sort of type-casting is discouraged among unrelated classes,
00542     but is permissible here because ovector_tlate is a descendant of
00543     gsl_vector.  In particular, this will not generate "type-punning"
00544     warnings in later gcc versions.  If this bothers your
00545     sensibilities, however, then you can use the following approach:
00546     \code
00547     ovector a(2);
00548     gsl_vector *g=a.get_gsl_vector();
00549     \endcode
00550     The ease of converting between these two kind of objects makes it
00551     easy to use gsl functions on objects of type \ref ovector, i.e.
00552     \code
00553     ovector a(2);
00554     a[0]=2.0;
00555     a[1]=1.0;
00556     gsl_vector_sort((gsl_vector *)(&a));
00557     cout << a[0] << " " << a[1] << endl;
00558     \endcode
00559 
00560     \b Converting \b from \b STL \b form
00561 
00562     To "view" a \c std::vector<double>, you can use \ref ovector_array
00563     \code
00564     std::vector<double> d;
00565     d.push_back(1.0);
00566     d.push_back(3.0);
00567     ovector_array aa(d.size,&(d[0]));
00568     cout << aa[0] << " " << aa[1] << endl;
00569     \endcode
00570 
00571     However, you should note that if the memory for the \c std::vector
00572     is reallocated (for example because of a call to \c push_back()),
00573     then a previously created \ref ovector_view will be incorrect.
00574 
00575     \b push_back() \b and \b pop() \b methods
00576     
00577     These two functions give a behavior similar to the corresponding
00578     methods for \c std::vector<>. This will work in O2scl classes,
00579     but may not be compatible with all of the GSL functions. This 
00580     will break if the address of a \ref ovector_tlate is given
00581     to a GSL function which accesses the \c block->size parameter
00582     instead of the \c size parameter of a \c gsl_vector. Please 
00583     contact the author of O2scl if you find a GSL function with this
00584     behavior. 
00585     
00586     \b Views
00587 
00588     Views are slightly different than in GSL in that they are now
00589     implemented as parent classes. The code
00590     \code
00591     double x[2]={1.0,2.0};
00592     gsl_vector_view_array v(2,x);
00593     gsl_vector *g=&(v.vector);
00594     gsl_vector_set(g,0,3.0);
00595     cout << gsl_vector_get(g,0) << " " << gsl_vector_get(g,1) << endl;
00596     \endcode
00597     can be replaced by
00598     \code 
00599     double x[2]={1.0,2.0};
00600     ovector_array a(2,x);
00601     a[0]=3.0;
00602     cout << a[0] << " " << a[1] << endl;
00603     \endcode
00604 
00605     \b Passing \b ovector \b parameters
00606     
00607     It is often best to pass an \ref ovector as a const reference
00608     to an \ref ovector_view, i.e.
00609     \code
00610     void function(const ovector_view &a);
00611     \endcode
00612     If the function may change the values in the \ref ovector,
00613     then just leave out \c const
00614     \code
00615     void function(ovector_view &a);
00616     \endcode
00617     This way, you ensure that the function is not allowed to modify
00618     the memory for the vector argument.
00619 
00620     If you intend for a function (rather than the user) to handle 
00621     the memory allocation, then some care is necessary. The
00622     following code
00623     \code
00624     class my_class {
00625     int afunction(ovector &a) {
00626     a.allocate(1);
00627     // do something with a
00628     return 0;
00629     }
00630     };
00631     \endcode
00632     is confusing because the user may have already allocated memory
00633     for \c a. To avoid this, you may want to ensure that the user
00634     sends an empty vector. For example,
00635     \code
00636     class my_class {
00637     int afunction(ovector &a) {
00638     if (a.get_size()>0 && a.is_owner()==true) {
00639     set_err("Unallocated vector not sent.",1);
00640     return 1;
00641     } else {
00642     a.allocate(1);
00643     // do something with a
00644     return 0;
00645     }
00646     }
00647     };
00648     \endcode
00649     In lieu of this, it is often preferable to use a local variable for
00650     the storage and offer a \c get() function, 
00651     \code
00652     class my_class {
00653     protected:
00654     ovector a;
00655     public:
00656     int afunction() {
00657     a.allocate(1);
00658     // do something with a
00659     return 0;
00660     }
00661     int get_result(const ovector_view &av) { av=a; return 0; }
00662     };
00663     \endcode
00664     The O2scl classes run into this situation quite frequently, but
00665     the vector type is specified through a template
00666     \code
00667     template<class vec_t> class my_class {
00668     protected:
00669     vec_t a;
00670     public:
00671     int afunction(vec_t &a) {
00672     a.allocate(1);
00673     // do something with a
00674     return 0;
00675     }
00676     };
00677     \endcode
00678 
00679     \b Vectors \b and \b operator=()
00680 
00681     An "operator=(value)" method for setting all vector elements to
00682     the same value is not included because it leads to confusion
00683     between, \c ovector_tlate::operator=(const data_t &val) and
00684     ovector_tlate::ovector_tlate(size_t val) For example, after
00685     implementing \c operator=() and executing the following
00686     \code
00687     ovector_int o1=2;
00688     ovector_int o2;
00689     o2=2;
00690     \endcode
00691     \c o1 will be a vector of size two, and \c o2 will be an
00692     empty vector! 
00693 
00694     To set all of the vector elements to the same value, use
00695     ovector_tlate::set_all().  Because of the existence of
00696     constructors like ovector_tlate::ovector_tlate(size_t val), the
00697     following code
00698     \code
00699     ovector_int o1=2;
00700     \endcode
00701     still compiles, and is equivalent to 
00702     \code
00703     ovector_int o1(2);
00704     \endcode
00705     while the code
00706     \code
00707     ovector_int o1;
00708     o1=2;
00709     \endcode
00710     will not compile. As a matter of style, \c ovector_int \c o1(2);
00711     is preferable to \c ovector_int \c o1=2; to avoid confusion.
00712 
00713     \b Matrix \b structure
00714     
00715     The matrices from \ref omatrix_tlate
00716     are structured in exactly the same way as in GSL.
00717     For a matrix with 2 rows, 4 colums, and a "tda" or "trailing
00718     dimension" of 7, the memory for the matrix is structured in the
00719     following way:
00720     
00721     \verbatim
00722     00 01 02 03 XX XX XX
00723     10 11 12 13 XX XX XX
00724     \endverbatim
00725     
00726     where \c XX indicates portions of memory that are unused.  The tda
00727     can be accessed through, for example, the method
00728     omatrix_view_tlate::tda(). The \c get(size_t,size_t) methods
00729     always take the row index as the first argument and the column
00730     index as the second argument. The matrices from \ref umatrix_tlate
00731     have a trailing dimension which is always equal to the number of
00732     columns.
00733 
00734     \b Reversing the order of vectors
00735 
00736     You can get a reversed vector view from \ref
00737     ovector_reverse_tlate, or uvector_reverse_tlate. For these
00738     classes, \c operator[] and related methods are redefined to
00739     perform the reversal. If you want to make many calls to these
00740     indexing methods for a reversed vector, then simply copying the
00741     vector to a reversed version may be faster.
00742     
00743     \b Const-correctness with vectors
00744     
00745     There are several classes named with \c "_const" to provide different
00746     kinds of const
00747     views of const vectors. The keyword \c const still ought to be included
00748     to ensure that the object is treated properly. For example,
00749     \code
00750     ovector o(2);
00751     o[0]=3.0;
00752     o[1]=-1.0;
00753     const ovector_const_subvector ocs(o,1,1);
00754     \endcode
00755     
00756     At present, const-correctness in O2scl can be improperly removed,
00757     if the \c const keyword is not properly included. For example, the
00758     following code will compile, violated the const-correctness of 
00759     the \c ocs variable.
00760     \code
00761     ovector o(2);
00762     o[0]=3.0;
00763     o[1]=-1.0;
00764     ovector_const_subvector ocs(o,1,1);
00765     ovector_view ov(ocs);
00766     ov[0]=2.0;
00767     \endcode
00768     
00769     \b Tensors
00770 
00771     Some preliminary support is provided for tensors of arbitrary rank
00772     and size in the class \ref tensor. Classes \ref tensor1, \ref
00773     tensor2, \ref tensor3, and \ref tensor4 are rank-specific versions
00774     for 1-, 2-, 3- and 4-rank tensors. For n-dimsional data defined on
00775     a grid, \ref tensor_grid provides a space to define a hyper-cubic
00776     grid in addition to the the tensor data. This class \ref
00777     tensor_grid also provides n-dimensional interpolation of the data
00778     defined on the specified grid.
00779 
00780     \hline
00781     \section intp_section Interpolation
00782     
00783     The classes o2scl_interp and o2scl_interp_vec allow basic
00784     interpolation, lookup, differentiation, and integration of data
00785     given in two ovectors or ovector views. In contrast to the GSL
00786     routines, data which is presented with a decreasing independent
00787     variable is handled automatically. For interpolation with
00788     arrays rather than ovectors, use array_interp or array_interp_vec.
00789 
00790     For fast interpolation without error-checking, you can directly
00791     use the children of \ref base_interp. 
00792 
00793     \b The \b two \b interpolation \b interfaces
00794 
00795     The difference between the two classes, o2scl_interp and
00796     o2scl_interp_vec, analogous to the difference between using \c
00797     gsl_interp_eval() and \c gsl_spline_eval() in \c GSL. You can
00798     create a o2scl_interp object and use it to interpolate among any
00799     pair of chosen vectors, i.e.
00800     \code
00801     ovector x(20), y(20);
00802     // fill x and y with data
00803     o2scl_interp gi;
00804     double y_o2sclf=gi.interp(0.5,20,x,y);
00805     \endcode
00806     Alternatively, you can create a o2scl_interp_vec object which can be
00807     optimized for a pair of vectors that you specify in advance
00808     \code
00809     ovector x(20), y(20);
00810     // fill x and y with data
00811     o2scl_interp_vec gi(20,x,y);
00812     double y_o2sclf=gi.interp(0.5);
00813     \endcode
00814 
00815     \b Lookup \b and \b binary \b search
00816 
00817     The class search_vec contains a searching functions for objects of
00818     type \ref ovector which are monotonic. Note that if you want to
00819     find the index of an \ref ovector where a particular value is
00820     located without any assumptions with regard to the ordering, you
00821     can use ovector::lookup() which performs an exhaustive search.
00822 
00823     \b "Smart" \b interpolation
00824     
00825     The classes smart_interp and smart_interp_vec allow interpolation,
00826     lookup, differentiation, and integration of data which is
00827     non-monotonic or multiply-valued outside the region of interest.
00828     As with o2scl_interp above, the corresponding array versions are
00829     given in sma_interp and sma_interp_vec.
00830 
00831     \note The classes smart_interp and smart_interp_vec are still
00832     a bit experimental. 
00833 
00834     \b Two \b and \b higher \b dimensional \b interpolation
00835 
00836     Preliminary support for two-dimensional interpolation is 
00837     given in \ref twod_intp, and n-dimensional interpolation
00838     in \ref tensor_grid.
00839 
00840     \hline
00841     \section const_section Physical constants
00842     
00843     The constants from GSL are reworked with the type \c const \c
00844     double and placed in namespaces called gsl_cgs, gsl_cgsm, gsl_mks,
00845     gsl_mksa, and gsl_num. Some additional constants are given in the
00846     namespace o2scl_const.
00847 
00848     \hline
00849     \section funct_section Function Objects
00850 
00851     Functions are passed to numerical routines using template-based
00852     function classes. There are several basic "kinds" of function
00853     objects:
00854     - \ref funct : One function of one variable
00855     - \ref multi_funct : One function of several variables
00856     - \ref mm_funct : \c n functions of \c n variables
00857     - \ref fit_funct : One function of one variable with \c n 
00858     fitting parameters
00859     - \ref ode_funct : \c n derivatives as a function of \c n function
00860     values and the value of the independent variable
00861 
00862     For each of these classes, there is a version named \c _vfunct
00863     instead of \c _funct which is designed to be used with C-style
00864     arrays instead. 
00865 
00866     The class name suffixes denote children of a generic function type
00867     which are created using different kinds of inputs:
00868     - _fptr: function pointer for a static or global function
00869     - _gsl: GSL-like function pointer 
00870     - _mfptr: function pointer template for a class member function
00871     - _strings: functions specified using strings, e.g. "x^2-2"
00872     - _noerr: (for \ref funct and multi_funct) a function which 
00873     directly returns the function value rather than returning
00874     an integer error value
00875     - _nopar: (for \ref funct) a function which has no parameters
00876     specified by a \c void \c * and directly returns the function
00877     value.
00878 
00879     There is a small overhead associated with the indirection: a
00880     "user" accesses the function class which then calls function which
00881     was specified in the constructor of the function class.  This
00882     overhead can always be avoided by inheriting directly from the
00883     function class and thus the user will make a direct call, or by
00884     specifying a new type for the template parameter in the class
00885     which will call the user-specified function. In many problems,
00886     the overhead associated with the indirection is small. In problems
00887     where the associated overhead is not small, there are usually
00888     other optimization issues (such as error handling and bounds
00889     checking in the "user" of the function object) which are still
00890     larger. 
00891 
00892     Note that virtual functions can be specified through 
00893     this mechanism as well. For example, if \ref cern_mroot
00894     is used to solve a set of equations specified as
00895     \code
00896     class my_type_t {
00897     virtual member_func();
00898     };
00899     my_type_t my_instance;
00900     class my_derived_type_t : public my_type_t {
00901     virtual member_func();
00902     };
00903     my_derived_type_t my_inst2;
00904     mm_funct_mfptr<my_type_t> func(&my_inst2,&my_instance::member_func);
00905     \endcode
00906     Then the solver will solve the member function in the derived
00907     type, not the parent type. 
00908 
00909     \hline
00910     \section table_section Data tables
00911     
00912     The class \ref table is a container to hold and perform operations
00913     on related columns of data. It supports column operations,
00914     interpolation, column reference by either name or index, binary
00915     searching (in the case of ordered columns), sorting, and fitting
00916     two columns to a user-specified function.
00917 
00918     \hline
00919     \section string_section String manipulation
00920 
00921     There are a couple classes and functions to help manipulate
00922     strings of text. Conversion routines for \c std::string 
00923     objects are given in \ref string_conv.h and include
00924     - \ref ptos() - pointer to string
00925     - \ref itos() - integer to string
00926     - \ref dtos() - double to string
00927     - \ref stoi() - string to integer
00928     - \ref stod() - string to double
00929 
00930     See also \ref size_of_exponent(), \ref double_to_latex(), 
00931     \ref double_to_html, and \ref double_to_ieee_string(). 
00932 
00933     There is a class called \ref columnify, which converts a set of
00934     strings into nicely formatted columns by padding with the
00935     necessary amount of spaces. This class operates on string objects
00936     of type \c std::string, and also works will for formatting columns
00937     of floating-point numbers.  This class is used to provide output
00938     for matrices in the functions \ref matrix_out(), \ref
00939     array_2d_out(), and \ref matrix_cx_out(). For output
00940     of vectors, see \ref vector_out() in \ref array.h. 
00941 
00942     A related function, \ref screenify(), reformats a column 
00943     of strings into many columns stored row-by-row in a new 
00944     string array. It operates very similar to
00945     the way the classic Unix command \c ls organizes files and
00946     directories in multiple columns in order to save screen space.
00947     
00948     The function \ref count_words() counts the number of "words"
00949     in a string, which are delimited by whitespace. 
00950 
00951     \hline
00952     \section diff_section Differentiation
00953 
00954     Differentiation is performed by descendants of \ref deriv and the
00955     classes are provided. These allow one to calculate either first,
00956     second, and third derivatives. The GSL approach is used in \ref
00957     gsl_deriv, and the CERNLIB routine is used in \ref
00958     cern_deriv. Both of these compute derivatives for a function
00959     specified using a descendant of \ref funct. For functions which
00960     are tabulated over equally-spaced abscissas, the class \ref
00961     eqi_deriv is provided which applies the formulas from Abramowitz
00962     and Stegun at a specified order.
00963 
00964     \b Warning: For gsl_deriv and cern_deriv, the second and third
00965     derivatives are calculated by naive repeated application of the
00966     code for the first derivative and can be particularly troublesome
00967     if the function is not sufficiently smooth. Error estimation is 
00968     also incorrect for second and third derivatives.
00969 
00970     \hline
00971     \section inte_section Integration
00972 
00973     Integration is performed by descendants of \ref inte and is
00974     provided in the library \c o2scl_inte.
00975 
00976     There are several routines for one-dimensional integration.
00977     - General integration over a finite interval: cern_adapt,
00978     cern_gauss, cern_gauss56, gsl_inte_qag, and gsl_inte_qng.
00979     - General integration from 0 to  \f$ \infty \f$ : gsl_inte_qagiu
00980     - General integration from  \f$ -\infty \f$ to 0: gsl_inte_qagil
00981     - General integration from  \f$ -\infty \f$ to \f$ \infty \f$ : 
00982     gsl_inte_qagi
00983     - Integration for a finite interval over an function with equally
00984     spaced abscissas provided in an array: eqi_inte
00985     - General integration over a finite interval for a function with
00986     singularities: gsl_inte_qags and gsl_inte_qagp
00987     - Cauchy principal value integration over a finite interval:
00988     cern_cauchy and gsl_inte_qawc
00989     - Integration over a function weighted by \c cos(x) or \c sin(x):
00990     gsl_inte_qawo
00991     - Fourier integrals: gsl_inte_qawf.
00992     - Integration over a weight function
00993     \f[
00994     W(x)=(x-a)^{\alpha}(b-x)^{\beta}\log^{\mu}(x-a)\log^{\nu}(b-x)
00995     \f]
00996     is performed by gsl_inte_qaws.
00997     
00998     For the GSL-based integration routines, the variables inte::tolx
00999     and inte::tolf have the same role as the quantities usually
01000     denoted in the GSL integration routines by \c epsabs and \c
01001     epsrel. In particular, the integration classes attempt to ensure
01002     that
01003     \f[ 
01004     |\mathrm{result}-I| \leq \mathrm{Max}(\mathrm{tolx},
01005     \mathrm{tolf}|I|)
01006     \f]
01007     and returns an error to attempt to ensure that
01008     \f[
01009     |\mathrm{result}-I| \leq \mathrm{abserr} \leq
01010     \mathrm{Max}(\mathrm{tolx},\mathrm{tolf}|I|)
01011     \f]
01012     where \c I is the integral to be evaluated. Even when the
01013     corresponding descendant of inte::integ() returns success, these
01014     inequalities may fail for sufficiently difficult functions.
01015     
01016     Multi-dimensional hypercubic integration is performed by \ref
01017     composite_inte, the sole descendant of multi_inte. \ref
01018     composite_inte allows you to specify a set of one-dimensional
01019     integration routines (objects of type \ref inte) and apply them to
01020     a multi-dimensional problem.
01021 
01022     General multi-dimensional integration is performed by \ref
01023     comp_gen_inte, the sole descendant of \ref gen_inte.  The user is
01024     allowed to specify a upper and lower limits which are functions of
01025     the variables for integrations which have not yet been performed,
01026     i.e. the n-dimensional integral
01027     \f[ 
01028     \int_{x_0=a_0}^{x_0=b_0} f(x_0) \int_{x_1=a_1(x_0)}^{x_1=b_1(x_0)} 
01029     f(x_0, x_1) ...
01030     \int_{x_{\mathrm{n}-1}=a_{\mathrm{n}-1}(x_0,x_1,..,x_{\mathrm{n}-2})}^
01031     {x_{\mathrm{n}-1}=b_{\mathrm{n}-1}(x_0,x_1,..,x_{\mathrm{n}-2})} 
01032     f(x_0,x_1,...,x_{\mathrm{n-1}})~d x_{\mathrm{n}-1}~...~d x_1~d x_0
01033     \f]
01034     Again, one specifies a set of \ref inte objects to apply to
01035     each variable to be integrated over.
01036 
01037     Monte Carlo integration is also provided (see \ref mcarlo_section).
01038 
01039     \hline
01040     \section poly_section Roots of Polynomials
01041 
01042     Classes are provided for solving quadratic, cubic, and quartic
01043     equations as well as general polynomials. There is a standard
01044     nomenclature: classes which handle polynomials with real
01045     coefficients and real roots end with the suffix "_real"
01046     (quadratic_real, cubic_real and quartic_real), classes which
01047     handle real coefficients and complex roots end with the suffix
01048     "_real_coeff" (quadratic_real_coeff, cubic_real_coeff,
01049     quartic_real_coeff, and poly_real_coeff), and classes which handle
01050     complex polynomials with complex coefficients (quadratic_complex,
01051     cubic_complex, quartic_complex, and poly_complex). As a reminder,
01052     complex roots may not occur in conjugate pairs if the coefficients
01053     are not real. Most of these routines do not separately handle
01054     cases where the leading coefficient is zero.
01055 
01056     At present, the polynomial routines work with complex numbers as
01057     objects of type \c std::complex<double> and are located in library
01058     \c o2scl_other. 
01059 
01060     For quadratics, \ref gsl_quadratic_real_coeff is the best if the
01061     coefficients are real, while if the coefficients are complex, \ref
01062     quadratic_std_complex is the only option at present. For cubics
01063     with real coefficients, \ref cern_cubic_real_coeff is the best,
01064     while if the coefficients are complex, use \ref cubic_std_complex.
01065     
01066     For a quartic polynomial with real coefficients, \ref
01067     cern_quartic_real_coeff is the best, unless the coefficients of
01068     odd powers happen to be small, in which case, \ref
01069     gsl_quartic_real2 tends to work better. For quartics, generic
01070     polynomial solvers such as \ref gsl_poly_real_coeff can provide
01071     more accurate (but slower) results. If the coefficients are
01072     complex, then you can use \ref naive_quartic_complex.
01073 
01074     \hline
01075     \section solve_section Equation Solving
01076 
01077     Equation solving classes are stored in the library
01078     \c o2scl_root. 
01079 
01080     \b One-dimensional \b solvers
01081 
01082     Solution of one equation in one variable is accomplished by
01083     children of the class \ref root. This base class provides
01084     the structure for three different solving methods:
01085     - root::solve(double &x, void *pa, funct &func) which
01086     solves a function given an initial guess \c x
01087     - root::solve_bkt(double &x1, double x2, void *pa, funct &func)
01088     which solves a function given a solution bracketed between
01089     \c x1 and \c x2. The values of the function at \c x1 and
01090     \c x2 must have different signs.
01091     - root::solve_de(double &x, void *pa, funct &func, funct &df)
01092     which solves a function given an initial guess \c x and the
01093     derivative of the function \c df.  
01094 
01095     For one-dimensional solving, use cern_root or gsl_root_brent if
01096     you have the root bracketed, or gsl_root_stef if you have the
01097     derivative available. If you have neither a bracket or a
01098     derivative, you can use cern_mroot_root. 
01099 
01100     If not all of these three functions are overloaded, then the
01101     source code in \ref root is designed to try to automatically
01102     provide the solution using the remaining functions. Most of the
01103     one-dimensional solving routines, in their original form, are
01104     written in the second or third form above.  For example,
01105     gsl_root_brent is originally a bracketing routine of the form
01106     root::solve_bkt(), but calls to either root::solve() or
01107     root::solve_de() will attempt to automatically bracket the
01108     function given the initial guess that is provided. Also,
01109     gsl_root_stef is a "root-polishing" routine given
01110     derivatives of the form root::solve_de(). If either root::solve()
01111     or root::solve_bkt() are called, then root::solve_de() will be
01112     called with finite-differencing used to estimate the derivative.
01113     Of course, it is frequently most efficient to use the solver in
01114     the way it was intended.
01115 
01116     \todo Double check this documentation above
01117 
01118     \b Multi-dimensional \b solvers
01119 
01120     Solution of more than one equation is accomplished by descendants
01121     of the class \ref mroot. There are two basic functions
01122     - mroot::msolve(size_t n, ovector &x, void *pa, mm_funct &func) 
01123     which solves the \c n equations given in \c func with an initial
01124     guess \c x.
01125 
01126     For multi-dimensional solving, you can use either cern_mroot or
01127     gsl_mroot_hybrids. While cern_mroot does not use user-supplied
01128     derivatives, gsl_mroot_hybrids can use user-supplied derivative
01129     information (as in the GSL hybridsj method).
01130 
01131     \hline
01132     \section min_section Minimization
01133 
01134     One-dimensional minimization is performed by descendants of \ref
01135     minimize and provided in the library \c o2scl_minimize. There are
01136     two one-dimensional minimization algorithms, \ref cern_minimize
01137     and \ref gsl_min_brent, and they are both bracketing algorithms
01138     type where an interval and an initial guess must be provided.  If
01139     only an initial guess and no bracket is given, these two classes
01140     will attempt to find a suitable bracket from the initial
01141     guess. While the \ref minimize base class is designed to allow
01142     future descendants to optionally use derivative information, this
01143     is not yet supported for any one-dimensional minimizers.
01144 
01145     Multi-dimensional minimization is performed by descendants of
01146     multi_min: \ref gsl_mmin_simp, \ref gsl_mmin_conp, \ref
01147     gsl_mmin_conf, and \ref gsl_mmin_bfgs2. The class \ref
01148     multi_min_fix is a convenient way to perform a minimization while
01149     fixing some of the original parameters. The class \ref gsl_mmin_simp
01150     does not require or use any derivative information, but the other
01151     minimization classes are intended for use when derivatives
01152     are available. 
01153 
01154     A naive way of implementing constraints is to add a function to
01155     the original which increases the value outside of the allowed
01156     region. This can be done with the functions \ref constraint() and
01157     \ref lower_bound. There are two analogous functions, \ref
01158     cont_constraint() and \ref cont_lower_bound(), which continuous
01159     and differentiable versions.
01160 
01161     Simulated annealing methods are also provided (see \ref
01162     anneal_section).
01163 
01164     It is important to note that not all of the minimization routines
01165     test the second derivative to ensure that it doesn't vanish to 
01166     ensure that we have found a true minimum. 
01167 
01168     \hline
01169     \section mcarlo_section Monte Carlo Integration
01170 
01171     Monte Carlo integration is performed by descendants of mcarlo_inte
01172     in the library \c o2scl_mcarlo (\ref gsl_monte, \ref gsl_miser,
01173     and \ref gsl_vegas). These routines are generally superior to the
01174     direct methods for integrals over regions with large numbers of
01175     spatial dimensions.
01176 
01177     \hline
01178     \section anneal_section Simulated Annealing
01179 
01180     Minimization by simulated annealing is performed by descendants of
01181     sim_anneal (see \ref gsl_anneal). The annealing schedule is given
01182     by a descendant of tptr_schedule (see \ref tptr_geoseries).
01183 
01184     \hline
01185     \section fit_section Non-linear Least-Squares Fitting
01186 
01187     Fitting is performed by descendants of \ref fit_base and fitting
01188     functions can be specifed using \ref fit_funct.  The GSL fitting
01189     routines (scaled and unscaled) are implemented in gsl_fit. A
01190     generic fitting routine using a minimizer object specified as a
01191     child of multi_min is implemented in min_fit. When the multi_min
01192     object is (for example) a sim_anneal object, min_fit can avoid
01193     local minima which can occur when fitting noisy data.
01194 
01195     \hline
01196     \section ode_section Solution of Ordinary Differential Equations
01197 
01198     Classes for non-adaptive integration are provided as descendents
01199     of \ref odestep and classes for adaptive integration are
01200     descendants of \ref adapt_step. To specify a set of functions
01201     to these classes, use a child of ode_funct for a generic 
01202     vector type or a child of ode_vfunct when using arrays.
01203 
01204     Solution of simple initial value problems is performed by \ref
01205     ode_iv_solve.
01206 
01207     Preliminary support for boundary value problems is given in
01208     children of \ref ode_bv_solve.
01209 
01210     \hline
01211     \section rng_section Random Number Generation
01212 
01213     Random number generators are descendants of \ref rnga and are
01214     provided in the library \c o2scl_rnga. While the base object \ref
01215     rnga is created to allow user-defined random number generators,
01216     the only random number generator presently included are from
01217     GSL. The GSL random number generator code is reimplemented in the
01218     class \ref gsl_rnga to avoid an additional performance
01219     penalty. This may not be a truly "object-oriented" interface in
01220     that it does not use virtual functions, but it avoids any possible
01221     performance penalty. Random number generators are implemented as
01222     templates in \ref sim_anneal and \ref mcarlo_inte. In these
01223     classes, the random number generator is a template type, rather
01224     than a member data pointer, in order to ensure fast execution.
01225 
01226     \hline
01227     \section tintp_section Two-dimensional Interpolation
01228 
01229     Successive use of \ref smart_interp is implemented in \ref twod_intp. 
01230     Also, see \ref planar_intp and \ref quad_intp and the 
01231     computation of contour lines in \ref contour. These latter three
01232     classes are somewhat experiemental at present.
01233 
01234     \hline
01235     \section other_section Other Routines
01236 
01237     (These are all experimental)
01238 
01239     \b Fourier \b transforms - see \ref gsl_fft
01240 
01241     \b Series \b acceleration - see \ref gsl_series
01242 
01243     \b Chebyshev \b approximations - see \ref gsl_chebapp
01244 
01245     \b Timing \b execution - see \ref timer_gettod and \ref timer_clock
01246 
01247     \b Polylogarithms - see \ref polylog
01248 
01249     \hline
01250     \section lset_section Library settings
01251 
01252     There are a couple library settings which are handled by 
01253     a global object \ref lib_settings of type \ref lib_settings_class.
01254 
01255     There are several data files that are used by various classes in
01256     the library. The installation procedure should ensure that these
01257     files are automatically found. However, if these data files are
01258     moved after installation, then a call to
01259     lib_settings_class::set_data_dir() can adjust the library to use
01260     the new directory. It is assumed that the directory structure
01261     within the data directory has not changed.
01262 
01263     \hline
01264     \section io_section Object I/O
01265 
01266     The I/O portion of the library is still experimental.
01267     
01268     Collections of objects can be stored in a \ref collection class,
01269     and these collections can be written to or read from text or
01270     binary files. User-defined classes may be added to the collections
01271     and may be read and written to files as long as a descendant of
01272     \ref io_base is provided.
01273 
01274     Every type has an associated I/O type which is a descendant of
01275     \ref io_base. In order to perform any sort of input/output on any
01276     type, an object of the corresponding I/O type must be instantiated
01277     by the user. This is not done automatically by the library. (Since
01278     it doesn't know which objects are going to be used ahead of time,
01279     the library would have to instantiate <em>all</em> of the I/O
01280     objects, which is needlessly slow.) This makes the I/O slightly
01281     less user-friendly, but much more efficient. For convenience, each
01282     subsection of the library has a class (named with an \c _ioc
01283     suffix) which will automatically allocate all I/O types for that
01284     subsection.
01285     
01286     <b>Level 1 functions:</b> Functions that input/output data from
01287     library-defined objects and internal types from files and combine
01288     these objects in collections. These are primarily member functions
01289     of the class \ref collection.
01290 
01291     <b>Level 2 functions:</b> Functions which are designed to allow
01292     the user to input or output data for user-generated objects. These
01293     are primarily member functions of classes \ref cinput and \ref
01294     coutput.
01295     
01296     <b>Level 3 functions:</b> Functions which allow low-level
01297     modifications on how input and output is performed. Usage of 
01298     level 3 functions is not immediately recommended for the casual
01299     user.
01300     
01301     <b>Level 1 usage</b>:
01302 
01303     For adding an object to a collection when you have a pointer
01304     to the I/O object for the associated type:
01305     \code
01306     int collection::add(std::string name, io_base *tio, void *vec, 
01307     int sz=0, int sz2=0, bool overwrt=true, bool owner=false);
01308     \endcode
01309     For adding an object to a collection otherwise:
01310     \code
01311     int collection::add(std::string name, std::string stype,
01312     void *vec, int sz=0, int sz2=0,
01313     bool overwrt=true, bool owner=false);
01314     \endcode
01315 
01316     To retrieve an object as a <pre>void *</pre> from a collection 
01317     use one of:
01318     \code
01319     int get(std::string tname, void *&vec);
01320     int get(std::string tname, void *&vec, int &sz);
01321     int get(std::string tname, void *&vec, int &sz, int &sz2);
01322     int get(std::string tname, std::string &stype, void *&vec);
01323     int get(std::string tname, std::string &stype, void *&vec, int &sz);
01324     int get(std::string tname, std::string &stype, void *&vec, int &sz,
01325     int &sz2);
01326     \endcode
01327     When retrieving a scalar object without error- and type-checking you
01328     can use the shorthand version:
01329     \code
01330     void *get(std::string name);
01331     \endcode
01332 
01333     To output one object to a file:
01334     \code
01335     int collection::out_one(out_file_format *outs, std::string stype, 
01336     std::string name, void *vp, int sz=0, int sz2=0);
01337     \endcode
01338 
01339     To input one object from a file with a given type and name:
01340     \code
01341     int collection::in_one_name(in_file_format *ins, std::string stype, 
01342     std::string name, void *&vp, int &sz, int &sz2);
01343     \endcode
01344     To input the first object of a given type from a file:
01345     \code
01346     int collection::in_one(in_file_format *ins, std::string stype, 
01347     std::string &name, void *&vp, int &sz, int &sz2);
01348     \endcode
01349 
01350     <b>Level 2 usage (string-based)</b>:
01351 
01352     If you don't have a pointer to the io_base child object corresponding
01353     to the type of subobject that you are manipulating, then you can use
01354     the following functions, which take the type name as a string.
01355 
01356     To input a sub-object in an io_base template for which memory
01357     has already been allocated use one of:
01358     \code
01359     int collection::object_in(std::string type, in_file_format *ins, void *vp,
01360     std::string &name);
01361     int collection::object_in(std::string type, in_file_format *ins, void *vp,
01362     int sz, std::string &name);
01363     int collection::object_in(std::string type, in_file_format *ins, void *vp,
01364     int sz, int sz2, std::string &name);
01365     \endcode
01366     
01367     To automatically allocate memory and input a sub-object of a 
01368     io_base template use one of:
01369     \code
01370     int collection::object_in_mem(std::string type, in_file_format *ins, 
01371     void *vp, std::string &name);
01372     int collection::object_in_mem(std::string type, in_file_format *ins, 
01373     void *vp, int sz, std::string &name);
01374     int collection::object_in_mem(std::string type, in_file_format *ins, 
01375     void *vp, int sz, int sz2, std::string &name);
01376     \endcode
01377 
01378     To output a subobject in an io_base template use:
01379     \code
01380     int collection::object_out(std::string type, out_file_format *outs,
01381     void *op, int sz=0, int sz2=0, std::string name="");
01382     \endcode
01383     
01384     <b>Level 2 usage (with io_base pointer)</b>:
01385 
01386     To input a sub-object in an io_base template for which memory
01387     has already been allocated use one of:
01388     \code
01389     virtual int object_in(cinput *cin, in_file_format *ins, object *op,
01390     std::string &name);
01391     virtual int object_in(cinput *cin, in_file_format *ins, object *op,
01392     int sz, std::string &name);
01393     virtual int object_in(cinput *cin, in_file_format *ins, object **op,
01394     int sz, int sz2, std::string &name);
01395     template<size_t N>
01396     int object_in(cinput *co, in_file_format *ins,
01397     object op[][N], int sz, std::string &name);
01398     \endcode
01399     
01400     To automatically allocate memory and input a sub-object of a 
01401     io_base template use one of:
01402     \code
01403     virtual int object_in_mem(cinput *cin, in_file_format *ins,
01404     object *&op, std::string &name);
01405     virtual int object_in_mem(cinput *cin, in_file_format *ins, object *&op,
01406     int &sz, std::string &name);
01407     virtual int object_in_mem(cinput *cin, in_file_format *ins,
01408     object **&op, int &sz, int &sz2,
01409     std::string &name);
01410     template<size_t N>
01411     int object_in_mem(cinput *co, in_file_format *ins,
01412     object op[][N], int &sz, std::string &name);
01413     \endcode
01414     
01415     To output a subobject in an io_base template use:
01416     \code
01417     virtual int object_out(coutput *cout, out_file_format *outs, object *op,
01418     int sz=0, std::string name="");
01419     virtual int object_out(coutput *cout, out_file_format *outs, object **op,
01420     int sz, int sz2, std::string name="");
01421     template<size_t N>
01422     int object_out(coutput *cout, out_file_format *outs,
01423     object op[][N], int sz, std::string name="");
01424     \endcode
01425 
01426     To automatically allocate/deallocate memory for an object, use:
01427     \code
01428     virtual int mem_alloc(object *&op);
01429     virtual int mem_alloc_arr(object *&op, int sz);
01430     virtual int mem_alloc_2darr(object **&op, int sz, int sz2);
01431     virtual int mem_free(object *op);
01432     virtual int mem_free_arr(object *op);
01433     virtual int mem_free_2darr(object **op, int sz);
01434     \endcode
01435     
01436     \b Usage \b of \b io_tlate
01437 
01438     The functions io_tlate::input() and io_tlate::output() need to be
01439     implemented for every class has information for I/O. For
01440     subobjects of the class, cinput::object_in() and
01441     cinput::object_out() can be called to input or output the
01442     information associated with the subobject. For input,
01443     cinput::object_in_name(), cinput::object_in_mem(), and
01444     cinput::object_in_mem_name() allow the freedom to input an object
01445     with a name or with memory allocation. The function
01446     coutput::object_out_name() allows one to output an object with a
01447     name.  If the class contains a pointer to the subobject, then
01448     io_base::pointer_in() or io_base::pointer_out() can be used.
01449 
01450     \hline
01451     \section design_section Design Considerations
01452 
01453     The design goal is to create an object-oriented computing library
01454     with classes that perform common numerical tasks. The most
01455     important principle is that the library should add functionality
01456     to the user while at the same time retaining as much freedom for
01457     the user as possible and allowing for ease of use and extensibility. 
01458     To that end, 
01459     - The classes which utilize user-specified functions
01460     should be able to operate on member functions without requiring
01461     a particular inheritance structure,
01462     - The interfaces ought to be generic so that the user
01463     can create new classes which perform related numerical
01464     tasks through inheritance,
01465     - The classes should not use static variables or functions
01466     - Const-correctness and type-safety should be used wherever possible, and
01467     - The design should be somewhat compatible with GSL.
01468     Also, the library provides higher-level routines
01469     for situations which do not require lower-level access. 
01470 
01471     <b>Header file dependencies</b>
01472     
01473     For reference, it's useful to know how the top-level header files
01474     depend on each other, since it can be difficult to trace everything
01475     down. In the \c base directory, the following are the most "top-level"
01476     header files and their associated dependencies within O2scl (there
01477     are other dependencies on GSL and the C standard library not
01478     listed here). 
01479     \code
01480     err_hnd.h : (none)
01481     sring_conv.h : (none)
01482     lib_settings.h : (none)
01483     array.h: err_hnd.h
01484     uvector_tlate.h: err_hnd.h
01485     ovector_tlate.h: uvector_tlate.h array.h err_hnd.h 
01486     misc.h : ovector_tlate.h uvector_tlate.h array.h lib_settings.h err_hnd.h
01487     test_mgr.h : misc.h ovector_tlate.h uvector_tlate.h 
01488     .             array.h lib_settings.h err_hnd.h
01489     \endcode
01490 
01491     <B>The use of templates</b>
01492     
01493     Templates are used extensively, and this makes for longer
01494     compilation times so any code that can be removed conveniently
01495     from the header files should be put into source code files
01496     instead. 
01497 
01498     \b Type-casting \b in \b vector \b and \b matrix \b design
01499 
01500     O2scl uses a GSL-like approach where viewing const double *
01501     arrays is performed by explicitly casting aways const'ness
01502     internally and then preventing the user from changing the data. 
01503 
01504     In gsl-1.6, the preprocessor output for \c vector/view_source.c is:
01505     \include gcv.cpp
01506     Note the explicit cast from const double * to double *. This
01507     is similar to what is done in \c src/base/ovector.cpp.
01508 
01509     \b Global \b objects
01510 
01511     There are three global objects that are created in
01512     libo2scl_base:
01513     - def_err_hnd is the default error handler
01514     - err_hnd is the pointer to the error handler (points to
01515     def_err_hnd by default)
01516     - lib_settings to control a few library settings
01517 
01518     All other global objects are to be avoided.
01519 
01520     \b Thread \b safety
01521 
01522     Most of the classes are thread-safe, meaning that two instances of
01523     the same class will not clash if their methods are called
01524     concurrently since static variables are only used for compile-time
01525     constants.  However, two threads cannot, in general, safely access
01526     the same instance of a class. In this respect, O2scl is no
01527     different from GSL.
01528     
01529     \b Documentation \b design
01530     
01531     
01532     The commands \\comment and \\endcomment delinate comments about
01533     the documentation that are present in the header files but don't
01534     ever show up in the HTML or LaTeX documentation.
01535 
01536     \b Release \b Procedure
01537     
01538     Internally, it's useful to keep track of the steps requred
01539     to create a full release (under construction)
01540     - svn update 
01541     - Update version numbers in configure.ac 
01542     - source aconfig.scr
01543     - make version-update
01544     - Edit version number in distribution link in doc/o2scl/main.h
01545     - make sinstall
01546     - make o2scl-test
01547     - Make the \c ex_ and \c bm_ files in the examples directory
01548     - Make sure acol.help and acol.usage are up to date
01549     - make o2scl-doc 
01550     - make o2scl-docp
01551     - make dist
01552     - svn commit 
01553 
01554     \hline
01555     \section license_section License Information
01556     
01557     O2scl (as well as CERNLIB and the Gnu Scientific Library (GSL)) is
01558     licensed under version 3 of the GPL as provided in the files \c
01559     COPYING and in \c doc/o2scl/extras/gpl_license.txt. After
01560     installation, it is included in the documentation in \c
01561     PREFIX/doc/extras/gpl_license.txt where the default \c PREFIX is
01562     \c /usr/local.
01563     
01564     \include gpl_license.txt
01565 
01566     This documentation is provided under the GNU Free Documentation
01567     License, as given below and provided in \c
01568     doc/o2scl/extras/fdl_license.txt. After installation, it is included
01569     in the documentation in \c PREFIX/doc/extras/fdl_license.txt where
01570     the default \c PREFIX is \c /usr/local.
01571     
01572     \include fdl_license.txt
01573     
01574     \hline
01575     \section ack_section Acknowledgements
01576     
01577     I would like to that the creators of GSL for their excellent work
01578 
01579     \hline
01580     \section ref_section Bibliography
01581 
01582     Some of the references which contain links should direct you to
01583     the work referred to directly through dx.doi.org.
01584 
01585     \anchor Bus75 Bus75:
01586     J.C.P. Bus and T.J. Dekker, ACM
01587     Trans. Math. Software 1 (1975) 330-345.
01588 
01589     \anchor Fletcher87 Fletcher87:
01590     R. Fletcher, Practical methods of optimization (John Wiley & Sons,
01591     Chichester 1987) 39.
01592 
01593     \anchor Krabs83 Krabs83:
01594     W. Krabs, Einfuhrung in die lieare und nictlineare Optimierung
01595     fur Ingenieure (BSB B.G. Teubner, Leipzig 1983) 84.
01596 
01597     \anchor Lewin83 Lewin83:
01598     L. Lewin, Polylogarithms and Associated Functions (North-Holland,
01599     New York, 1983).
01600 
01601     \anchor Longman58 Longman58:
01602     I.M. Longman, MTAC (later renamed Math. Comp.) \b 12 (1958) 205.
01603 
01604     \anchor More79 More79:
01605     J.J. More' and M.Y. Cosnard, ACM Trans. Math. Software,
01606     \b 5 (1979) 64-85.
01607 
01608     \anchor More80 More80:
01609     J.J. More' and M.Y. Cosnard, Algoright 554 BRENTM,
01610     Collected Algorithms from CACM (1980).
01611 
01612     \anchor Rutishauser63 Rutishauser63:
01613     H. Rutishauser, Ausdehnung des Rombergschen Prinzips
01614     (Extension of Romberg's Principle), Numer. Math. 5 (1963) 48-54.
01615 
01616 */
01617 /** 
01618     \page dl_page Download O2scl
01619 
01620     The present version is 0.8, which can be obtained from \n
01621     - \c http://sourceforge.net/project/showfiles.php?group_id=206918
01622     \n
01623     \hline
01624     The previous versions are at
01625     - \c http://tharkad.pa.msu.edu/~asteiner/o2scl/hal-0.78.tar.gz
01626     - \c http://tharkad.pa.msu.edu/~asteiner/o2scl/hal-0.77.tar.gz
01627     - \c http://tharkad.pa.msu.edu/~asteiner/o2scl/hal-0.76.tar.gz
01628     
01629 */
01630 /**
01631    \brief An empty class to add some items to the todo and bug lists
01632    
01633    \todo
01634    - Fix ex_file 
01635    - Improve ex_table
01636    - Fix problems with \c -ansi compilation on Cygwin
01637    - More examples and benchmarks
01638    - Document a list of all global functions and operators
01639    - Make sure we have a uvector_alloc, uvector_cx_alloc, 
01640    ovector_cx_const_reverse, ovector_cx_const_subvector_reverse, 
01641    uvector_reverse, uvector_const_reverse, uvector_subvector_reverse,
01642    uvector_const_subvector_reverse, omatrix_cx_diag, blah_const_diag, 
01643    umatrix_diag, and umatrix_cx_diag
01644    - ovector_cx_view::operator=(uvector_cx_view &) is missing
01645    - ovector_cx::operator=(uvector_cx_view &) is missing
01646    - uvector_c_view::operator+=(complex) is missing
01647    - uvector_c_view::operator-=(complex) is missing
01648    - uvector_c_view::operator*=(complex) is missing
01649 
01650    \future There may be a problem with const-correctness in vectors. 
01651    I'm not sure how it's best solved. It could be best to create two kinds of 
01652    ovector_view's: one const and one not. 10/19/07: I think it's the
01653    case that neither ovector_const_subvector, or const ovector_subvector 
01654    are truly const, but it's only const ovector_const_subvector that
01655    would be truly const. I'm not sure if this is related to the issue
01656    of constness in ovector_view discussed above.
01657    
01658    \bug 
01659    - The file configure.ac does not correctly produce an error
01660    if the argument --disable-readline is not given when the 
01661    libncurses and libreadline libraries are not present. 
01662    - BLAS libraries not named \c libblas or \c libgslblas are not
01663    properly detected in ./configure and will have to be added
01664    manually. 
01665    - The -lm flag may not be added properly by ./configure
01666 
01667 */
01668 class other_todos_and_bugs {
01669 }
01670 
01671 /** \brief The main namespace
01672     \nothing
01673 
01674     Most of the classes reside in this namespace, but it is removed
01675     from the documentation for clarity. 
01676     \htmlonly
01677     See <a href="annotated.html">Data Structures</a> for a full list.
01678     \endhtmlonly
01679 */
01680 namespace o2scl {
01681 }
01682 
01683 /*
01684   Old example stuff
01685 
01686   \todo Maybe rewrite this as an example separate from ex_fptr below.
01687 
01688   \b An \b example
01689 
01690   \c ex_fptr gives an example of the how member functions and
01691   external parameters are supplied to numerical routines. In this
01692   case, a member function (which contains the equation  \f$ 
01693   -\sin(x-0.2)/|x+0.01|+c_1+c_2 =0 \f$  where  \f$ c_1 \f$  is a private
01694   data member and  \f$ c_2 \f$  is an externally-supplied parameter, is
01695   passed to the gsl_root_brent routine, which solves the equation.
01696 
01697   \b ex_fptr.cpp
01698   \include ex_fptr.cpp
01699 
01700   The output is \b ex_fptr.scr:
01701   \include ex_fptr.scr
01702 
01703   \hline
01704   \section examples_section Other Examples
01705 
01706   All of the following examples are in the \c examples subdirectory.
01707 
01708   \b I/O \b example
01709 
01710   This example demonstrates the ease of using text or binary files
01711   for input or output. A \ref collection is filled with data and
01712   output to several files. The data is read in from each of the
01713   files and written to \c cout.
01714 
01715   \b ex_file.cpp
01716   \include ex_file.cpp
01717 
01718   This produces the following output:
01719 
01720   \b ex_file.scr
01721   \include ex_file.scr
01722 
01723   Note that the binary files automatically store the full precision
01724   for floating-point numbers, but that the text files do not. The
01725   precision for text files can be modified, see \ref text_out_file
01726   for details.
01727 
01728   \b Differentiation
01729 
01730   \b ex_diff.cpp
01731   \include ex_diff.cpp
01732 
01733   The result of plotting \c err and \c err' from the 
01734   output file \c ex_diff.out is
01735 
01736   \image html ex_diff.gif "ex_diff.out"
01737   \image latex ex_diff.eps "ex_diff.out" width=9cm
01738 
01739   Note that the formula for equally-spaced abscissas provided
01740   by eq_interval is more accurate than interpolation with
01741   smart_interp at the boundaries, but less accurate otherwise.
01742 
01743 */

Documentation generated with Doxygen and provided under the GNU Free Documentation License. See License Information for details.

Project hosting provided by SourceForge.net Logo, O2scl Sourceforge Project Page