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