main.h

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

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