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

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