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

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