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 <table width="100%"><tr><td align="left"> 00028 <a href="../latex/refman.pdf">PDF documentation</a> 00029 </td><td align="right"><a href="dl_page.html"> 00030 <b>Download 00031 O<span style='position: relative; top: 0.3em; 00032 font-size: 0.8em'>2</span>scl</b></a></td></tr></table> 00033 \endhtmlonly 00034 00035 \hline 00036 \section feat_section Feature overview 00037 00038 \o2 is a C++ class library for object-oriented numerical 00039 programming. It includes 00040 - Classes based on numerical routines from GSL and CERNLIB 00041 - Vector and matrix classes which are fully compatible with 00042 \c gsl_vector and \c gsl_matrix, yet offer indexing with 00043 \c operator[] and other object-oriented features 00044 - CERNLIB-based classes which are completely rewritten in C++ 00045 - Classes which require function inputs are designed to accept 00046 (public or private) member functions, even if they are virtual. 00047 - Classes use templated vector types, which allow the use of 00048 user-specified object-oriented vectors or C-style arrays. 00049 - Highly compatible - Recent versions have been tested on 00050 Linux (32- and 64-bit systems, with Intel and AMD chips), 00051 Windows XP with Cygwin, and MacOSX. 00052 - Free! \o2 is provided under Version 3 of the GNU 00053 Public License (see \ref license_section for more). 00054 - Two mini-libraries 00055 <ul> 00056 <li>Thermodynamics of ideal and nearly-ideal particles with 00057 quantum statistics</li> 00058 <li>Equations of state for finite density relevant for 00059 neutron stars</li> 00060 </ul> 00061 00062 This is a beta version. The library should install and 00063 test successfully, and most of the classes are ready 00064 for production use. Some of the interfaces may change 00065 slightly in future versions. There are a few classes 00066 which are more experimental, and this is clearly stated 00067 at the top of the documentation for these classes. 00068 00069 \hline 00070 \section toc_section Quick Reference to User's Guide 00071 00072 - \ref install_section 00073 - \ref usage_section 00074 - \ref examples_section 00075 - \ref related_section 00076 - \ref cplxnum_section 00077 - \ref vecmat_section 00078 - \ref permute_section 00079 - \ref linalg_section 00080 - \ref intp_section 00081 - \ref const_section 00082 - \ref funct_section 00083 - \ref table_section 00084 - \ref string_section 00085 - \ref diff_section 00086 - \ref inte_section 00087 - \ref poly_section 00088 - \ref solve_section 00089 - \ref min_section 00090 - \ref conmin_section 00091 - \ref mcarlo_section 00092 - \ref anneal_section 00093 - \ref fit_section 00094 - \ref ode_section 00095 - \ref rng_section 00096 - \ref tintp_section 00097 - \ref gslcheb_section 00098 - \ref unitconv_section 00099 - \ref other_section 00100 - \ref lset_section 00101 - \ref io_section 00102 - \ref source_section 00103 - \ref design_section 00104 - \ref license_section 00105 - \ref ack_section 00106 - \ref ref_section 00107 - \ref todo 00108 - \ref bug 00109 00110 \htmlonly 00111 <UL><LI>Other mini-libraries 00112 <UL> 00113 <LI><B><a href="../part/html/index.html">Particles : 00114 O<span style='position: relative; top: 0.3em; font-size: 0.8em'>2</span>scl_part</a></b> 00115 <LI><B><a href="../eos/html/index.html">Equations of State : 00116 O<span style='position: relative; top: 0.3em; font-size: 0.8em'>2</span>scl_eos</a></b> 00117 </UL> 00118 </LI> 00119 <br /> 00120 <li>Add-on library: There is also a related library, 00121 <a href='../../o2scl_ext/html/index.html'>O<span style='position: relative; top: 0.3em; font-size: 0.8em'>2</span>scl_ext</a>, 00122 which has a separate source distribution. 00123 </li> 00124 </UL> 00125 \endhtmlonly 00126 00127 \hline 00128 \section install_section Installation 00129 00130 The rules for installation are generally the same as that for 00131 other GNU libraries. The file \c INSTALL has some details on this 00132 procedure. Generally, you should be able to run 00133 <tt>./configure</tt> and then type \c make and \c make \c 00134 install. More information on the \c configure command can also be 00135 obtained from <tt>./configure --help</tt>. \o2 requires the GSL 00136 libraries. If the <tt>configure</tt> script cannot find them, you 00137 may have to specify their location in the <tt>CPPFLAGS</tt> and 00138 <tt>LDFLAGS</tt> environment variables (<tt>./configure 00139 --help</tt> shows some information on this). The documentation is 00140 included in the distribution and automatically installed 00141 by \c make \c install. 00142 00143 After \c make \c install, you may test the library with \c make \c 00144 o2scl-test. At the end, the phrase <tt>All O2scl tests passed</tt> 00145 indicates that the testing was successful. 00146 00147 This library requires GSL and is designed to work with GSL 00148 versions 1.12 or greater. Some classes may work with older 00149 versions of GSL, but this cannot be guaranteed. A CBLAS library is 00150 also required, and <tt>./configure</tt> will look for 00151 <tt>libcblas</tt> first, and if not found then it will look for 00152 <tt>libgslcblas</tt>. If neither is present, then you may have to 00153 manually specify a CBLAS library using the <tt>LIBS</tt> and 00154 <tt>LDFLAGS</tt> environment variables. 00155 00156 Range-checking for vectors and matrices is performed similar to 00157 the GSL approach, and is turned on by default. You can 00158 disable range-checking by defining -DO2SCL_NO_RANGE_CHECK 00159 \code 00160 CPPFLAGS="-DO2SCL_NO_RANGE_CHECK" ./configure 00161 \endcode 00162 00163 The separate libraries \o2e and \o2p are installed by default. To 00164 disable the installation of these libraries and their associated 00165 documentation, run <tt>./configure</tt> with the flags \c 00166 --disable-eoslib or \c --disable-partlib. Note that \o2e depends 00167 on \o2p so using \c --disable-partlib without \c --disable-eoslib 00168 will not work. 00169 00170 There are several warning flags that are useful when configuring 00171 and compiling with \o2. See the GSL documentation for an 00172 excellent discussion, and also see the generic installation 00173 documentation in the file <tt>INSTALL</tt> in the \o2 top-level 00174 directory. For running \c configure, for example, if you do 00175 not have privileges to write to <tt>/usr/local</tt>, 00176 \code 00177 CPPFLAGS="-O3" -I/home/asteiner/install/include" \ 00178 LDFLAGS="-L/home/asteiner/install/lib" ./configure -C \ 00179 --prefix=/home/asteiner/install 00180 \endcode 00181 In this example, specifying 00182 <tt>-I/home/asteiner/install/include</tt> and 00183 <tt>-L/home/asteiner/install/lib</tt> above ensures that the GSL 00184 libraries can be found (this is where they are installed on my 00185 machine). The <tt>--prefix=/home/asteiner/install</tt> argument to 00186 <tt>./configure</tt> ensures that \o2 is installed there as well. 00187 00188 The documentation is generated with \doxygen. In principle, the 00189 documentation can be regenerated by the end-user, but this is 00190 not supported and requires several external applications 00191 not included in the distribution. 00192 00193 \b Un-installation: While there is no explicit "uninstall" 00194 procedure, there are only a couple places to check. Installation 00195 creates directories named <tt>o2scl</tt> in the include, doc and shared 00196 files directory (which default to \c /usr/local/include, \c 00197 /usr/local/doc, and \c /usr/local/share) which can be 00198 removed. Finally, all of the libraries are named with the prefix 00199 \c libo2scl and are created by default in /usr/local/lib. As 00200 configured with the settings above, the files are in \c 00201 /home/asteiner/install/include/o2scl, \c /home/asteiner/install/lib, 00202 \c /home/asteiner/install/share/o2scl, and \c 00203 /home/asteiner/install/doc/o2scl. 00204 00205 \hline 00206 \section usage_section General Usage 00207 00208 \subsection namespace_subsect Namespaces 00209 00210 Most of the classes reside in the namespace \c o2scl (this 00211 namespace has been removed from the documentation for clarity). 00212 Numerical constants (many of them based on the GSL constants) are 00213 placed in separate namespaces (gsl_cgs, gsl_cgsm, gsl_mks, 00214 gsl_mksa, gsl_num, o2scl_const, and o2scl_fm). There are also two 00215 namespaces which hold integration coefficients, 00216 o2scl_inte_qag_coeffs and o2scl_inte_qng_coeffs. There are also 00217 some namespaces for the linear algebra functions, see \ref 00218 linalg_section for more information. 00219 00220 \subsection docconv_subsect Documentation conventions 00221 00222 In the following documentation, function parameters are denoted by 00223 \c parameter, except when used in mathematical formulas as in \f$ 00224 \mathrm{variable} \f$ . 00225 00226 \subsection nomen_subsect Nomenclature 00227 00228 Classes directly derived from the GNU Scientific Library are 00229 preceeded by the prefix \c gsl_ and classes derived from CERNLIB 00230 are preceeded by the prefix \c cern_. Some of those classes 00231 derived from GSL and CERNLIB operate slightly differently 00232 from the original versions. The differences are detailed 00233 in the corresponding class documentation. 00234 00235 \subsection errorhand_subsect Basic error handling 00236 00237 Error handling is a hybrid approach combining GSL with C++ 00238 exceptions. An abstract type has been defined which operates as a 00239 GSL-like error hander. The default error handler is a 00240 implementation of this abstract type which throws a C++ exception 00241 when an error is encountered. The various exceptions, and their 00242 correspondence with the GSL error codes, are given in the \ref 00243 exc_types_subsect section. By default in \o2, the default GSL 00244 error handler is replaced with the \o2 default error handler, i.e. 00245 GSL functions will throw C++ exceptions. 00246 00247 Errors can be set by the user through the macros \ref O2SCL_ERR, 00248 which sets an error, and \ref O2SCL_ERR_RET, which sets an error 00249 and returns the error number. 00250 00251 The error handler, \ref err_hnd is a global pointer to an object 00252 of type \ref err_hnd_type. There is a global default error 00253 handler, \ref def_err_hnd, of type \ref err_hnd_cpp, which throws 00254 C++ exceptions, and an alternate default error handler, \ref 00255 alt_err_hnd, of type \ref err_hnd_gsl, which outputs an error 00256 message and aborts execution. 00257 00258 Generally, functions also follow the GSL-like behavior of calling 00259 a GSL-like error handler and (when appropriate) return a non-zero 00260 value. When functions succeed they return 0 (\ref gsl_success). 00261 \o2 functions never reset the error handler. Also, object 00262 destructors do not generally call the error handler. Internally, 00263 \o2 does not use <tt>try</tt> blocks, but these can easily be 00264 effectively employed by an \o2 user. 00265 00266 The list of GSL error codes (including a few extra ones for \o2) 00267 is given in the documentation for the file \ref err_hnd.h. The 00268 default error handler can be replaced by simply assigning the 00269 address of a descendant of \ref err_hnd_type to \ref err_hnd. 00270 00271 Functionality similar to assert() is provided with the macro 00272 \ref O2SCL_ASSERT, which exits if its argument is non-zero, and 00273 \ref O2SCL_BOOL_ASSERT which exits if its argument is false. 00274 00275 One can instruct the library to use the GSL-like \o2 error 00276 handler \ref alt_err_hnd by default, by defining the 00277 constant <tt>O2SCL_USE_GSL_HANDLER</tt>. This is also useful 00278 if one wants to compile without C++ exceptions (which does 00279 have a small overhead). 00280 00281 \subsection errorhand2_subsect What is an error? 00282 00283 \o2 assumes that errors are events which should happen 00284 infrequently. Error handling strategies are often time-consuming 00285 and they are not a replacement for normal code flow. However, even 00286 with this in mind, one can still distinguish a large spectrum of 00287 posibillities from "fatal" errors, those likely to corrupt the 00288 stack and/or cause a dreaded "segmentation fault" and "non-fatal" 00289 errors, those errors which might cause incorrect results, but 00290 might be somehow recoverable. One of the purposes of error 00291 handling is to decide if and how these different types of errors 00292 should be handled differently. 00293 00294 Sometimes, it is undesirable to abort execution upon a failure to 00295 reach numerical convergence. While these failures are treated as 00296 errors (and by default an exception is thrown), some of the 00297 classes which attempt to reach numerical convergence have an 00298 option (e.g. mroot::err_nonconv) to turn this default behavior off 00299 for these convergence errors. To set these "convergence" errors in 00300 code provided by the user, the macros \ref O2SCL_CONV and \ref 00301 O2SCL_CONV_RET can be used. 00302 00303 Another related issue is that \o2 often calls functions which are 00304 supplied by the user, these user-designed functions may create 00305 errors, and the library needs to decide how to deal with them, 00306 even though it knows little about what is actually happening 00307 inside these user-defined functions. Most of the time, \o2 assumes 00308 that if a function returns a nonzero value, then an error has 00309 occured and the present calculation should abort. 00310 00311 \subsection exc_types_subsect GSL error codes and C++ exception types 00312 00313 See also the description of the error codes in \ref err_hnd.h . 00314 00315 gsl_success=0, (no error thrown) \n 00316 gsl_failure=-1, \ref exc_exception \n 00317 gsl_continue=-2, (no error thrown) \n 00318 gsl_edom=1, \ref exc_range_error \n 00319 gsl_erange=2, \ref exc_range_error \n 00320 gsl_efault=3, \ref exc_runtime_error \n 00321 gsl_einval=4, \ref exc_invalid_argument \n 00322 gsl_efailed=5, \ref exc_exception \n 00323 gsl_efactor=6, \ref exc_runtime_error \n 00324 gsl_esanity=7, \ref exc_exception \n 00325 gsl_enomem=8, \ref exc_runtime_error \n 00326 gsl_ebadfunc=9, \ref exc_runtime_error \n 00327 gsl_erunaway=10, \ref exc_runtime_error \n 00328 gsl_emaxiter=11, \ref exc_runtime_error \n 00329 gsl_ezerodiv=12, \ref exc_overflow_error \n 00330 gsl_ebadtol=13, \ref exc_invalid_argument \n 00331 gsl_etol=14, \ref exc_runtime_error \n 00332 gsl_eundrflw=15, \ref exc_range_error \n 00333 gsl_eovrflw=16, \ref exc_overflow_error \n 00334 gsl_eloss=17, \ref exc_runtime_error \n 00335 gsl_eround=18, \ref exc_runtime_error \n 00336 gsl_ebadlen=19, \ref exc_invalid_argument \n 00337 gsl_enotsqr=20, \ref exc_invalid_argument \n 00338 gsl_esing=21, \ref exc_runtime_error \n 00339 gsl_ediverge=22, \ref exc_runtime_error \n 00340 gsl_eunsup=23, \ref exc_exception \n 00341 gsl_eunimpl=24, \ref exc_exception \n 00342 gsl_ecache=25, \ref exc_runtime_error \n 00343 gsl_etable=26, \ref exc_runtime_error \n 00344 gsl_enoprog=27, \ref exc_runtime_error \n 00345 gsl_enoprogj=28, \ref exc_runtime_error \n 00346 gsl_etolf=29, \ref exc_runtime_error \n 00347 gsl_etolx=30, \ref exc_runtime_error \n 00348 gsl_etolg=31, \ref exc_runtime_error \n 00349 gsl_eof=32, \ref exc_ios_failure \n 00350 gsl_enotfound=33, \ref exc_runtime_error \n 00351 gsl_ememtype=34, \ref exc_logic_error \n 00352 gsl_efilenotfound=35, \ref exc_ios_failure \n 00353 gsl_eindex=36, \ref exc_invalid_argument \n 00354 gsl_outsidecons=37, \ref exc_runtime_error \n 00355 00356 \subsection objscope_subsect Objects and scope 00357 00358 \o2 objects frequently take inputs which are of the form of a 00359 reference to a smaller object. This is particularly convenient 00360 because it allows a lot of flexibility, while providing a certain 00361 degree of safety. However, the user retains the responsibility of 00362 ensuring that input objects do not go out of scope before they are 00363 utilized by objects which require them. (This is actually no 00364 different than the requirements on the user imposed by GSL, for 00365 example.) 00366 00367 A simple example of this is provided by the multi-dimensional 00368 integrator \ref composite_inte. It works by combining several 00369 one-dimensional integrators to integrate over a multi-dimensional 00370 hybercube. If the specified one-dimensional integrator goes 00371 out of scope an integration is attempted, the integration will 00372 fail, for example, 00373 \include scope_doc.cpp 00374 00375 This will fail because the one-dimensional integration objects go 00376 out of scope (it's a local variable in the function and its 00377 destructor is called before the <tt>set_integrator()</tt> function 00378 exits) before the <tt>minteg_err()</tt> function is called. 00379 00380 \hline 00381 \section examples_section Compiling examples 00382 00383 The example programs are in the \c examples directory. After 00384 installation, they can be compiled and executed by running \c make 00385 \c o2scl-examples in that directory. This will also test the 00386 output of the examples to make sure it is correct. If all the 00387 examples succeed, the message <tt>All O2scl tests passed.</tt> 00388 will appear at the end. The output for each example is placed in 00389 the corresponding file with a <tt>.scr</tt> extension. 00390 00391 Alternatively, you can make the executable for each example in the 00392 \c examples directory individually using, e.g. <tt>make 00393 ex_mroot</tt>. 00394 00395 See \ref source_section for the documented source code of the 00396 individual examples 00397 00398 Also, the testing code for each class is occasionally useful for 00399 providing examples of their usage. The testing source code for 00400 each source file is named with an \c _ts.cpp prefix in the same 00401 directory as the class source. 00402 00403 \hline 00404 \section related_section Related projects 00405 00406 Several noteworthy related projects: 00407 00408 - GSL - The GNU Scientific Library \n The first truly free, 00409 ANSI-compliant, fully tested, and well-documented scientific 00410 computing library. The GSL is located at 00411 http://www.gnu.org/software/gsl . Manual is available at 00412 http://www.gnu.org/software/gsl/manual/html_node/ . Many GSL 00413 routines are included and reworked in \o2 (the corresponding 00414 classes begin with the \c gsl_ prefix) and \o2 was specifically 00415 designed to be used with GSL. GSL is a must-have for most serious 00416 numerical work in C or C++ and is required for installation of 00417 \o2. 00418 00419 - CERNLIB - The gold standard in FORTRAN computing libraries \n 00420 Several CERNLIB routines are rewritten completely in C++ and 00421 included in \o2 (they begin with the \c cern_ prefix). CERNLIB is 00422 located at http://cernlib.web.cern.ch/cernlib/mathlib.html 00423 00424 - LAPACK and ATLAS - The gold standard for linear algebra \n 00425 Available at http://www.netlib.org/lapack and 00426 http://www.netlib.org/atlas . See also 00427 http://www.netlib.org/clapack . 00428 00429 - QUADPACK - FORTRAN adaptive integration library \n This is the 00430 library on which the GSL integration routines are based (prefix \c 00431 gsl_inte_). It is available at http://www.netlib.org/quadpack . 00432 00433 - TNT - Template numerical toolkit (http://math.nist.gov) \n TNT 00434 provides vector and matrix types and basic arithmetic operations. 00435 Most of the classes in \o2 which use vector and matrix types are 00436 templated to allow compatbility with TNT. (Though there are a few 00437 small differences.) This software is in the public domain. 00438 00439 - Blitz++ - http://www.oonumerics.org/blitz \n Another linear 00440 algebra library designed in C++ which includes vector and matrix 00441 types and basic arithmetic. As the name implies, Blitz++ has the 00442 capability to be particularly fast. Distributed with a Perl-like 00443 artistic license "or the GPL". 00444 00445 - Boost - http://www.boost.org \n Free (license is compatible with 00446 GPL) peer-reviewed portable C++ source libraries that work well 00447 with the C++ Standard Library. Boost also contains uBlas, 00448 for linear algebra computing. 00449 \comment 00450 For examples of how to use 00451 \o2 with uBlas vector and matrices, see \ref ex_ublas_sect. 00452 \endcomment 00453 00454 - FLENS - http://flens.sourceforge.net \n A C++ library with 00455 object-oriented linear algebra types and an interface to BLAS 00456 and LAPACK. 00457 00458 - MESA - Modules for Experiments in Stellar Astrophysics 00459 (http://mesa.sourceforge.net) \n An excellent FORTRAN library with 00460 accurate low-density equations of state, interpolation, opacities 00461 and other routines useful in stellar physics. Work is currently 00462 under way to rewrite some of the MESA routines in C/C++ for \o2. 00463 Licensed with LGPL (not GPL). 00464 00465 - OOL - Open Optimization Library (http://ool.sourceforge.net) \n 00466 Constrained minimization library designed with GSL in mind. The 00467 \o2 constrained minimization classes are derived from this 00468 library. See \ref conmin_section . 00469 00470 - Root - CERN's new C++ analysis package (http://root.cern.ch) \n 00471 A gargantuan library for data analysis, focused mostly on 00472 high-energy physics. Their histograms, graphics, file I/O and 00473 support for large data sets is particuarly good. 00474 00475 \hline 00476 \section cplxnum_section Complex Numbers 00477 00478 Several arithmetic operations for \c gsl_complex are 00479 defined in cx_arith.h, but no constructor has been written. The 00480 object \c gsl_complex is still a \c struct, not a \c class. For 00481 example, 00482 \include cx_arith_doc.cpp 00483 00484 In case the user needs to convert between \c gsl_complex and \c 00485 std::complex<double>, two conversion functions gsl_to_complex() 00486 and complex_to_gsl() are also provided in \ref cx_arith.h. 00487 00488 A short example using complex number arithmetic is 00489 given in \ref ex_mandel_sect . 00490 00491 \hline 00492 \section vecmat_section Arrays, Vectors, Matrices and Tensors 00493 00494 \subsection vmintro_subsect Introduction 00495 00496 The \o2 library uses a standard nomenclature to distinguish 00497 a couple different concepts. The word "array" is always used to 00498 refer to C-style arrays, i.e. \c double[]. If there are two 00499 dimensions in the array, it is a "two-dimensional array", i.e. \c 00500 double[][] . The word "vector" is reserved generic objects with 00501 array-like semantics, i.e. any type of object or class which can 00502 be treated similar to an array in that it has an function \c 00503 operator[] which gives array-like indexing. Thus arrays are 00504 vectors, but not all vectors are arrays. There are a couple 00505 specific vector types defined in \o2 like \ref ovector and \ref 00506 uvector . The STL vector <tt>std::vector<double></tt> is also a 00507 vector type in this language. The word "matrix" is reserved for 00508 the a generic object which has matrix-like semantics and can be 00509 accessed using either \c operator() or two successive applications 00510 of \c operator[] (or sometimes both). The \o2 objects \ref omatrix 00511 and \ref umatrix are matrix objects, as is a C-style 00512 two-dimensional array, \c double[][] . The header files are named 00513 in this spirit also: functions and classes which operate on 00514 generic vector types are in \ref vector.h and functions and 00515 classes which work only with C-style arrays are in \ref array.h . 00516 The word "tensor" is used for a generic object which has 00517 rank \c n and then has \c n associated indices. A vector is just 00518 a \tensor of rank 1 and a matrix is just a \tensor of rank 2. 00519 00520 Most of the classes in \o2 which use vectors and/or matrices are 00521 designed so that they can be used with any appropriately-defined 00522 vector or matrix types. This is a major part of the design goals 00523 for \o2 and most of the classes are compatible with matrix and 00524 vector objects from GSL, TNT, MV++, uBlas, and Blitz++. 00525 00526 The first index of a matrix type is defined always to be the index 00527 associated with "rows" and the second is associated with 00528 "columns". The \o2 matrix output functions respect this notation 00529 as well, so that all of the elements of the first row is sent to 00530 the screen, then all of the elements in the second row, and so on. 00531 With this in mind, one can make the distinction between 00532 "row-major" and "column-major" matrix storage. C-style 00533 two-dimensional arrays are "row-major" in that the elements 00534 of the first row occupy the first locations in memory as 00535 opposed "column-major" where the first column occupies the 00536 first locations in memory. It is important to note that the 00537 majority of the classes in \o2 do not care about the details 00538 of the underlying memory structure, so long as two 00539 successive applications of <tt>operator[]</tt> (or 00540 in some cases <tt>operator(,)</tt> ) works properly. The storage 00541 format used by \ref omatrix and \ref umatrix is row-major, and there 00542 are no column-major matrix classes in \o2 (yet). 00543 00544 \subsection index_subsect Matrix indexing with [][] vs. (,) 00545 00546 While vector indexing with \c operator[] is very compatible with 00547 almost any vector type, matrix indexing is a bit more difficult. 00548 There are two options: assume matrix objects provide an \c 00549 operator[] method which can be applied twice, i.e. 00550 <tt>m[i][j]</tt>, or assume that matrix elements should be 00551 referred to with <tt>m(i,j)</tt>. Most of the \o2 classes use the 00552 former approach so that they are also compatible with 00553 two-dimensional arrays. However, there are sometimes good reasons 00554 to want to use <tt>operator()</tt> for matrix-intensive operations 00555 from linear algebra. For this reason, some of the functions given 00556 in the <tt>linalg</tt> directory are specified in two forms: the 00557 first default form which assumes <tt>[][]</tt>, and the second 00558 form with the same name, but in a namespace which has a suffix 00559 <tt>_paren</tt> and assumes matrix types use <tt>(,)</tt>. 00560 00561 \subsection rowcol_subsect Rows and columns vs. x and y 00562 00563 Sometimes its useful to think about the rows and columns in a 00564 matrix as referring to a elements of a grid, and the matrix 00565 indices refer to points in a grid in \f$ (x,y) \f$. It might seem 00566 intuitive to think of a matrix as \c A[ix][iy] where \c ix and \c 00567 iy are the \f$ x \f$ and \f$ y \f$ indices because the ordering of 00568 the indices is alphabetical. However, it is useful to note that 00569 because functions like \ref matrix_out print the first "row" first 00570 rather than the first column, a matrix constructed as \c A[ix][iy] 00571 will be printed out with x on the "vertical axis" and y on the 00572 "horizontal axis", so it is sometimes useful to store data 00573 in the form \c A[iy][ix] (for example, in the two dimensional 00574 interpolation class, twod_intp). In any case, all classes 00575 which take matrix data as input will document how the matrix 00576 ought to be arranged. 00577 00578 \subsection genvec_subsection Generic vector functions 00579 00580 There are a couple functions which operate on generic vectors of 00581 any type in \ref vector.h . They perform sorting, summing, 00582 rotating, copying, and computations of minima and maxima. For 00583 more statistically-oriented operations, see also \ref vec_stats.h . 00584 00585 \subsection nativetypes_subsect Native matrix and vector types 00586 00587 The rest of this section in the User's guide is dedicated to 00588 describing the \o2 implementations of vector, matrix, 00589 and \tensor types. 00590 00591 Vectors and matrices are designed using the templates \ref 00592 ovector_tlate and \ref omatrix_tlate, which are compatible with \c 00593 gsl_vector and \c gsl_matrix. Vectors and matrices with unit 00594 stride are provided in \ref uvector_tlate and \ref umatrix_tlate. 00595 The most commonly used double-precision versions of these template 00596 classes are \ref ovector, \ref omatrix, \ref uvector and \ref 00597 umatrix, and their associated "views" (analogous to GSL vector and 00598 matrix views) which are named with a \c _view suffix. The classes 00599 \ref ovector_tlate and \ref omatrix_tlate offer the syntactic 00600 simplicity of array-like indexing, which is easy to apply to 00601 vectors and matrices created with GSL. 00602 00603 The following sections primarily discuss the operation objects of 00604 type \ref ovector. The generalizations to objects of type \ref 00605 uvector, \ref omatrix, and the complex vector and matrix objects 00606 \ref ovector_cx, \ref omatrix_cx, \ref uvector_cx, and \ref 00607 umatrix_cx are straightforward. 00608 00609 \subsection view_subsect Vector and matrix views 00610 00611 Vector and matrix views are provided as parents of the vector and 00612 matrix classes which do not have methods for memory allocation. As 00613 in GSL, it is simple to "view" normal C-style arrays or pointer 00614 arrays (see \ref ovector_array), parts of vectors (\ref 00615 ovector_subvector), and rows and columns of matrices (\ref 00616 omatrix_row and \ref omatrix_col). Several operations are defined, 00617 including addition, subtraction, and dot products. 00618 00619 \subsection typedef_subsect Vector and matrix typedefs 00620 00621 Several typedefs are used to give smaller names to often used 00622 templates. Vectors and matrices of double-precision numbers all 00623 begin with the prefixes \ref ovector and \ref omatrix. Integer 00624 versions begin with the prefixes \ref ovector_int and \ref 00625 omatrix_int. Complex versions have an additional \c "_cx", 00626 e.g. \ref ovector_cx. See \ref ovector_tlate.h, \ref 00627 ovector_cx_tlate.h, \ref omatrix_tlate.h, and \ref 00628 omatrix_cx_tlate.h. 00629 00630 \subsection unit_subsect Unit-stride vectors 00631 00632 The \ref uvector_tlate objects are naturally somewhat faster 00633 albeit less flexible than their finite-stride counterparts. 00634 Conversion to GSL vectors and matrices is not trivial for \ref 00635 uvector_tlate objects, but demands copying the entire 00636 vector. Vector views, operators, and the nomenclature is similar 00637 to that of \ref ovector. 00638 00639 \subsection memalloc_subsect Memory allocation 00640 00641 Memory for vectors can be allocated using ovector::allocate() and 00642 ovector::free(). Allocation can also be performed by the 00643 constructor, and the destructor automatically calls <tt>free()</tt> if 00644 necessary. In contrast to \c gsl_vector_alloc(), 00645 ovector::allocate() will call ovector::free(), if necessary, to 00646 free previously allocated space. Allocating memory does not clear 00647 the recently allocated memory to zero. You can use \ref 00648 ovector::set_all() with a zero argument to clear a vector 00649 (and similarly for a matrix). 00650 00651 If the memory allocation fails, either in the constructor or in 00652 allocate(), then the error handler will be called, partially 00653 allocated memory will be freed, and the size will be reset to 00654 zero. 00655 00656 Although memory allocation in \o2 vectors is very similar to 00657 that in GSL, the user must not mix allocation and deallocation 00658 between GSL and \o2. 00659 00660 \subsection getset_subsect Get and set 00661 00662 Vectors and matrices can be modified using ovector::get() and 00663 ovector::set() methods analogous to \c gsl_vector_get() and \c 00664 gsl_vector_set(), or they can be modified through 00665 ovector::operator[] (or ovector::operator() ), e.g. 00666 \comment 00667 For some reason the references to ovector::operator have been 00668 failing in the Doxygen compilation. 00669 \endcomment 00670 \code 00671 ovector a(4); 00672 a.set(0,2.0); 00673 a.set(1,3.0); 00674 a[2]=4.0; 00675 a[3]=2.0*a[1]; 00676 \endcode 00677 00678 If you want to set all of the values in an \ref ovector or an \ref 00679 omatrix at the same time, then use ovector::set_all() or 00680 omatrix::set_all(). 00681 00682 \subsection rangecheck_subsect Range checking 00683 00684 Range checking is performed depending on whether or not \c 00685 O2SCL_NO_RANGE_CHECK is defined. It can be defined in the 00686 arguments to \c ./configure upon installation to turn off range 00687 checking. Note that this is completely separate from the GSL range 00688 checking mechanism, so range checking may be on in \o2 even if 00689 it has been turned off in GSL. Range checking is used primarily 00690 in the vector, matrix, and \tensor \c get() and \c set() methods. 00691 00692 To see if range checking was turned on during installation 00693 (without calling the error handler), use 00694 lib_settings_class::range_check(). 00695 00696 Note that range checking in \o2 code is most often present in 00697 header files, rather than in source code. This means that range 00698 checking can be turned on or off in user-defined functions 00699 separately from whether or not it was used in the library classes 00700 and functions. 00701 00702 \subsection copy_subsect Shallow and deep copy 00703 00704 Copying \o2 vectors using constructors or the \c = operator 00705 is performed according to what kind of object is 00706 on the left-hand side (LHS) of the equals sign. If the LHS is a 00707 view, then a shallow copy is performed, and if the LHS is a \ref 00708 ovector, then a deep copy is performed. If an attempt is made to 00709 perform a deep copy onto a vector that has already been allocated, 00710 then that previously allocated memory is automatically freed. 00711 The user must be careful to ensure that information is not lost 00712 this way, even though no memory leak will occur. 00713 00714 For generic deep vector and matrix copying, you can use the 00715 template functions \ref vector_copy(), \ref matrix_copy(). These 00716 would allow you, for example, to copy an \ref ovector to a \c 00717 std::vector<double> object. These functions do not do any 00718 memory allocation so that must be handled beforehand by the user. 00719 00720 \subsection vecarith_subsect Vector and matrix arithmetic 00721 00722 Several operators are available as member functions of the 00723 corresponding template: 00724 00725 Vector_view unary operators: 00726 - vector_view += vector_view 00727 - vector_view -= vector_view 00728 - vector_view += scalar 00729 - vector_view -= scalar 00730 - vector_view *= scalar 00731 - scalar = norm(vector_view) 00732 00733 Matrix_view unary operators: 00734 - matrix_view += matrix_view 00735 - matrix_view -= matrix_view 00736 - matrix_view += scalar 00737 - matrix_view -= scalar 00738 - matrix_view *= scalar 00739 00740 Binary operators like addition, subtraction, and matrix 00741 multiplication are also defined for \ref ovector, \ref uvector, 00742 and related objects. The generic template for a binary operator, 00743 e.g. 00744 \code 00745 template<class vec_t> vec_t &operator+(vec_t &v1, vec_t &v2); 00746 \endcode 00747 is difficult because the compiler has no way of distinguishing vector 00748 and non-vector classes. At the moment, this is solved by 00749 creating a define macro for the binary operators. In addition 00750 to the predefined operators for native classes, the user may 00751 also define binary operators for other classes using the same 00752 macros. For example, 00753 \code 00754 O2SCL_OP_VEC_VEC_ADD(o2scl::ovector,std::vector<double>, 00755 std::vector<double>) 00756 \endcode 00757 would provide an addition operator for \ref ovector and vectors 00758 from the Standard Template Library. A full list of the 00759 operators which are defined by default and the associated macros 00760 are detailed in the documentation for \ref vec_arith.h. 00761 00762 The GSL BLAS routines can also be used directly with \ref ovector 00763 and \ref omatrix objects. 00764 00765 Note that some of these arithmetic operations succeed even with 00766 non-matching vector and matrix sizes. For example, adding a 3x3 00767 matrix to a 4x4 matrix will result in a 3x3 matrix and the 7 outer 00768 elements of the 4x4 matrix are ignored. 00769 00770 \subsection gslconv_subsect Converting to and from GSL forms 00771 00772 Because of the way \ref ovector is constructed, you may use 00773 type conversion to convert to and from objects of type \c gsl_vector. 00774 \code 00775 ovector a(2); 00776 a[0]=1.0; 00777 a[1]=2.0; 00778 gsl_vector *g=(gsl_vector *)(&a); 00779 cout << gsl_vector_get(g,0) << " " << gsl_vector_get(g,1) << endl; 00780 \endcode 00781 Or, 00782 \code 00783 gsl_vector *g=gsl_vector_alloc(2); 00784 gsl_vector_set(0,1.0); 00785 gsl_vector_set(1,2.0); 00786 ovector &a=(ovector &)(*g); 00787 cout << a[0] << " " << a[1] << endl; 00788 \endcode 00789 This sort of type-casting is discouraged among unrelated classes, 00790 but is permissible here because ovector_tlate is a descendant of 00791 gsl_vector. In particular, this will not generate "type-punning" 00792 warnings in later gcc versions. If this bothers your 00793 sensibilities, however, then you can use the following approach: 00794 \code 00795 ovector a(2); 00796 gsl_vector *g=a.get_gsl_vector(); 00797 \endcode 00798 The ease of converting between these two kind of objects makes it 00799 easy to use gsl functions on objects of type \ref ovector, i.e. 00800 \code 00801 ovector a(2); 00802 a[0]=2.0; 00803 a[1]=1.0; 00804 gsl_vector_sort((gsl_vector *)(&a)); 00805 cout << a[0] << " " << a[1] << endl; 00806 \endcode 00807 00808 \subsection stlconv_subsect Converting from STL form 00809 00810 To "view" a \c std::vector<double>, you can use \ref ovector_array 00811 \code 00812 std::vector<double> d; 00813 d.push_back(1.0); 00814 d.push_back(3.0); 00815 ovector_array aa(d.size,&(d[0])); 00816 cout << aa[0] << " " << aa[1] << endl; 00817 \endcode 00818 00819 However, you should note that if the memory for the \c std::vector 00820 is reallocated (for example because of a call to \c push_back()), 00821 then a previously created \ref ovector_view will be incorrect. 00822 00823 \subsection pushpop_subsect push_back() and pop() methods 00824 00825 These two functions give a behavior similar to the corresponding 00826 methods for \c std::vector<>. This will work in \o2 classes, 00827 but may not be compatible with all of the GSL functions. This 00828 will break if the address of a \ref ovector_tlate is given 00829 to a GSL function which accesses the \c block->size parameter 00830 instead of the \c size parameter of a \c gsl_vector. Please 00831 contact the author of \o2 if you find a GSL function with this 00832 behavior. 00833 00834 \subsection view_subsect Views 00835 00836 Views are slightly different than in GSL in that they are now 00837 implemented as parent classes. Effectively, this means that vector 00838 views are just the same as normal vectors, except that they have 00839 no memory allocation functions (because the memory is presumably 00840 owned by a different object or scope). The code 00841 \code 00842 double x[2]={1.0,2.0}; 00843 gsl_vector_view_array v(2,x); 00844 gsl_vector *g=&(v.vector); 00845 gsl_vector_set(g,0,3.0); 00846 cout << gsl_vector_get(g,0) << " " << gsl_vector_get(g,1) << endl; 00847 \endcode 00848 can be replaced by 00849 \code 00850 double x[2]={1.0,2.0}; 00851 ovector_array a(2,x); 00852 a[0]=3.0; 00853 cout << a << endl; 00854 \endcode 00855 00856 \subsection vecparm_subsect Passing ovector parameters 00857 00858 It is often best to pass an \ref ovector as a const reference 00859 to an \ref ovector_view, i.e. 00860 \code 00861 void function(const ovector_base &a); 00862 \endcode 00863 If the function may change the values in the \ref ovector, 00864 then just leave out \c const 00865 \code 00866 void function(ovector_base &a); 00867 \endcode 00868 This way, you ensure that the function is not allowed to modify 00869 the memory for the vector argument. 00870 00871 If you intend for a function (rather than the user) to handle 00872 the memory allocation, then some care is necessary. The 00873 following code 00874 \include ovector_doc1.cpp 00875 is confusing because the user may have already allocated memory 00876 for \c a. To avoid this, you may want to ensure that the user 00877 sends an empty vector. For example, 00878 \include ovector_doc2.cpp 00879 In lieu of this, it is often preferable to use a local variable for 00880 the storage and offer a \c get() function, 00881 \include ovector_doc3.cpp 00882 The \o2 classes run into this situation quite frequently, but 00883 the vector type is specified through a template 00884 \include ovector_doc4.cpp 00885 00886 \subsection eqoper_subsect Vectors and operator=() 00887 00888 An "operator=(value)" method for setting all vector elements to 00889 the same value is not included because it leads to confusion 00890 between, \c ovector_tlate::operator=(const data_t &val) and 00891 ovector_tlate::ovector_tlate(size_t val) For example, after 00892 implementing \c operator=() and executing the following 00893 \code 00894 ovector_int o1=2; 00895 ovector_int o2; 00896 o2=2; 00897 \endcode 00898 \c o1 will be a vector of size two, and \c o2 will be an 00899 empty vector! 00900 00901 To set all of the vector elements to the same value, use 00902 ovector_tlate::set_all(). Because of the existence of 00903 constructors like ovector_tlate::ovector_tlate(size_t val), the 00904 following code 00905 \code 00906 ovector_int o1=2; 00907 \endcode 00908 still compiles, and is equivalent to 00909 \code 00910 ovector_int o1(2); 00911 \endcode 00912 while the code 00913 \code 00914 ovector_int o1; 00915 o1=2; 00916 \endcode 00917 will not compile. As a matter of style, \c ovector_int \c o1(2); 00918 is preferable to \c ovector_int \c o1=2; to avoid confusion. 00919 00920 \subsection matstruct_subsect Matrix structure 00921 00922 The matrices from \ref omatrix_tlate 00923 are structured in exactly the same way as in GSL. 00924 For a matrix with 2 rows, 4 colums, and a "tda" or "trailing 00925 dimension" of 7, the memory for the matrix is structured in the 00926 following way: 00927 00928 \verbatim 00929 00 01 02 03 XX XX XX 00930 10 11 12 13 XX XX XX 00931 \endverbatim 00932 00933 where \c XX indicates portions of memory that are unreferenced. The tda 00934 can be accessed through, for example, the method 00935 omatrix_view_tlate::tda(). The \c get(size_t,size_t) methods 00936 always take the row index as the first argument and the column 00937 index as the second argument. The matrices from \ref umatrix_tlate 00938 have a trailing dimension which is always equal to the number of 00939 columns. 00940 00941 \subsection rev_subsect Reversing the order of vectors 00942 00943 You can get a reversed vector view from \ref 00944 ovector_reverse_tlate, or uvector_reverse_tlate. For these 00945 classes, \c operator[] and related methods are redefined to 00946 perform the reversal. If you want to make many calls to these 00947 indexing methods for a reversed vector, then simply copying the 00948 vector to a reversed version may be faster. 00949 00950 \subsection constvec_subsect Const-correctness with vectors 00951 00952 Vector objects, like \ref ovector, can be const in the usual way. 00953 However because vector views, like \ref ovector_view are like 00954 pointers to vectors, there are two ways in which they can be 00955 const. The view can point to a const vector, or the view can be a 00956 'const view' which is fixed to point only to one vector (whether 00957 or not the vector pointed to happens to be const). This is exactly 00958 analogous to the distinction between const double *p, double * 00959 const p, and const double * const p. The first is a non-const 00960 pointer to const data, the second is a const pointer to non-const 00961 data, and the third is a const pointer to const data. The 00962 equivalent expressions in \o2 are 00963 \code 00964 ovector_const_view v1; 00965 const ovector_view v2; 00966 const ovector_const_view v3; 00967 \endcode 00968 Explicitly, 00969 - <tt>ovector_const_view</tt> is a view of a const vector, the 00970 view may change, but the vector may not. 00971 - <tt>const ovector_const_view</tt> is a const view of a const 00972 vector, the view may not point to a different vector and the 00973 vector may not change. 00974 - <tt>const ovector_view</tt> is a const view of a normal vector, 00975 the view may not change, but the vector can. 00976 This same distinction is also present, for example, in ublas vectors 00977 views within boost. 00978 00979 A reference of type \ref ovector_base is often used as a function 00980 argument, and can hold either a \ref ovector or a \ref 00981 ovector_view. The important rule to remember with \ref ovector_base 00982 is that, a const reference, i.e. 00983 \code 00984 const ovector_base &v; 00985 \endcode 00986 is always a const reference to data which cannot be changed. A 00987 normal \ref ovector_base reference does not refer to const data. 00988 00989 \comment 00990 00991 Vector objects, like \ref ovector, can be const in the usual 00992 way. However, in order to properly prevent the user from 00993 making a non-const view of a const vector, A separate 00994 view class \ref ovector_const_view was created. To demonstrate, 00995 the following code is allowed 00996 \code 00997 ovector x(2); 00998 const ovector_view y=x; 00999 \endcode 01000 However, if the original vector is <tt>const</tt>, then the 01001 \ref ovector_const_view class should be used 01002 \code 01003 const ovector x(2); 01004 const ovector_const_view y=x; 01005 \endcode 01006 01007 \endcomment 01008 01009 \subsection vmout_subsect Vector and matrix output 01010 01011 Both the \ref ovector_view_tlate and \ref omatrix_view_tlate 01012 classes have an << operator defined for each class. For 01013 writing generic vectors to a stream, you can use \ref vector_out() 01014 which is defined in \ref vector.h . Pretty matrix output is 01015 performed by global template functions \ref matrix_out(), \ref 01016 matrix_cx_out_paren(), and \ref matrix_out_paren() which are 01017 defined in \ref columnify.h since they internally use a \ref 01018 columnify object to format the output. 01019 01020 \subsection tensor_subsect Tensors 01021 01022 Some preliminary support is provided for tensors of arbitrary rank 01023 and size in the class \ref tensor. Classes \ref tensor1, \ref 01024 tensor2, \ref tensor3, and \ref tensor4 are rank-specific versions 01025 for 1-, 2-, 3- and 4-rank tensors. For n-dimsional data defined on 01026 a grid, \ref tensor_grid provides a space to define a hyper-cubic 01027 grid in addition to the the tensor data. This class \ref 01028 tensor_grid also provides n-dimensional interpolation of the data 01029 defined on the specified grid. 01030 01031 \hline 01032 \section permute_section Permutations 01033 01034 Permutations are implemented through the \ref permutation class. 01035 This class is fully compatible with gsl_permutation objects since 01036 it is inherited from gsl_permutation_struct. The class also 01037 contains no new data members, so upcasting and downcasting can 01038 always be performed. It is perfectly permissible to call 01039 GSL permutation functions from \ref permutation objects by 01040 simply passing the address of the permutation, i.e. 01041 \code 01042 permutation p(4); 01043 p.init(); 01044 gsl_permutation_swap(&p,2,3); 01045 \endcode 01046 01047 The functions which apply a permutation to a 01048 user-specified vector are member template functions in the \ref 01049 permutation class (see \ref permutation::apply() ). 01050 01051 Memory allocation/deallocation between the class and the 01052 gsl_struct is compatible in many cases, but mixing these forms is 01053 strongly discouraged, i.e. avoid using 01054 <tt>gsl_permutation_alloc()</tt> on a \ref permutation object, but 01055 rather use \ref permutation::allocate() instead. The use of \ref 01056 permutation::free() is encouraged, but any remaining memory will 01057 be deallocated in the object destructor. 01058 01059 \hline 01060 \section linalg_section Linear algebra 01061 01062 There is a small set of linear algebra routines. These are not 01063 intended to be a replacement for higher performance linear algebra 01064 libraries, but are designed for use by \o2 routines so that they 01065 work for generic matrix and vector types. For vector and matrix 01066 types using \c operator[], the BLAS and linear algebra routines 01067 are inside the \ref o2scl_cblas and \ref o2scl_linalg namespaces. 01068 For vector and matrix types using \c operator(), the BLAS and 01069 linear algebra routines routines are inside the \ref 01070 o2scl_cblas_paren and \ref o2scl_linalg_paren namespaces. 01071 01072 The linear algebra classes and functions include: 01073 - Householder transformations (\ref householder.h) 01074 - Householder solver (\ref hh.h) 01075 - LU decomposition and solver (\ref lu.h) 01076 - QR decomposition and solver (\ref qr.h) 01077 - Solve tridiagonal systems (\ref tridiag.h) 01078 - Lanczos diagonalization is inside class \ref lanczos, which 01079 also can compute the eigenvalues of a tridiagonal matrix. 01080 - Givens rotations (\ref givens.h) 01081 01082 There is also a set of linear solvers for generic matrix and 01083 vector types which descend from \ref o2scl_linalg::linear_solver. 01084 These classes provide GSL-like solvers, but are generalized so 01085 that they are compatible with vector and matrix types which allow 01086 access through <tt>operator[]</tt>. 01087 01088 For users who require high-performance linear algebra, the \ref 01089 ovector and \ref omatrix objects can be used to call LAPACK 01090 routines directly, just as can be done with GSL. For an example of 01091 how to do this, see 01092 http://sourceware.org/ml/gsl-discuss/2001/msg00326.html . 01093 \comment 01094 For 01095 uBlas users, there is an example of how to use uBlas vectors with 01096 \o2 in \ref ex_ublas_sect. 01097 \endcomment 01098 Finally, there are also a couple of 01099 examples, <tt>gesvd.cpp</tt> and <tt>zheev.cpp</tt> in the 01100 <tt>src/internal</tt> directory which show how to call LAPACK with 01101 \o2 objects which may be adaptable for your platform and 01102 configuration. 01103 01104 \hline 01105 \section intp_section Interpolation 01106 01107 The classes o2scl_interp and o2scl_interp_vec allow basic 01108 interpolation, lookup, differentiation, and integration of data 01109 given in two ovectors or ovector views. In contrast to the GSL 01110 routines, data which is presented with a decreasing independent 01111 variable is handled automatically. For interpolation with 01112 arrays rather than ovectors, use array_interp or array_interp_vec. 01113 01114 For fast interpolation of arrays where the independent variable 01115 is strictly increasing and without error-checking, you can directly 01116 use the children of \ref base_interp. 01117 01118 \subsection twoint_subsect The two interpolation interfaces 01119 01120 The difference between the two classes, o2scl_interp and 01121 o2scl_interp_vec, analogous to the difference between using \c 01122 gsl_interp_eval() and \c gsl_spline_eval() in \c GSL. You can 01123 create a o2scl_interp object and use it to interpolate among any 01124 pair of chosen vectors, i.e. 01125 \code 01126 ovector x(20), y(20); 01127 // fill x and y with data 01128 o2scl_interp oi; 01129 double y_half=oi.interp(0.5,20,x,y); 01130 \endcode 01131 Alternatively, you can create a o2scl_interp_vec object which can be 01132 optimized for a pair of vectors that you specify in advance 01133 \code 01134 ovector x(20), y(20); 01135 // fill x and y with data 01136 o2scl_interp_vec oi(20,x,y); 01137 double y_half=oi.interp(0.5); 01138 \endcode 01139 01140 \subsection search_subsect Lookup and binary search 01141 01142 The class search_vec contains a searching functions for objects of 01143 type \ref ovector which are monotonic. Note that if you want to 01144 find the index of an \ref ovector where a particular value is 01145 located without any assumptions with regard to the ordering, you 01146 can use ovector::lookup() which performs an exhaustive search. 01147 01148 \subsection smintp_subsect "Smart" interpolation 01149 01150 The classes smart_interp and smart_interp_vec allow interpolation, 01151 lookup, differentiation, and integration of data which is 01152 non-monotonic or multiply-valued outside the region of interest. 01153 As with o2scl_interp above, the corresponding array versions are 01154 given in sma_interp and sma_interp_vec. 01155 01156 \subsection lowinterp_subsect Lower-level interpolation objects 01157 01158 There are five lower-level interpolation objects which 01159 specify the basic \o2 interpolation types. They are 01160 - \ref linear_interp 01161 - \ref cspline_interp 01162 - \ref cspline_peri_interp 01163 - \ref akima_interp 01164 - \ref akima_peri_interp 01165 01166 \subsection interp_mgr_subsect Interpolation manager objects 01167 01168 Many \o2 classes require the ability to create and destroy 01169 interpolation objects at will, given one of the lower-level 01170 interpolation types described above. For this purpose, 01171 interpolation managers have been created, which allow the user to 01172 provide a class with an interpolation manager associated with a 01173 low-level interpolation type (and thus free the user from having 01174 to worry about the associated memory management). The abstract 01175 base interpolation manager type is \ref base_interp_mgr, and the 01176 default interpolation manager object is \ref def_interp_mgr . The 01177 \ref def_interp_mgr class has two template arguments: the first is 01178 the vector type to be interpolated, and the second is the 01179 lower-lever interpolation type. 01180 01181 For an example usage of the default interpolation manager, see 01182 the \ref ex_contour_sect , which specifies an interpolation manager 01183 for the \ref contour class. The \ref table class also works with 01184 interpolation manager objects (see \ref table::set_interp() ). 01185 01186 \subsection highdintp_subsect Two and higher dimensional interpolation 01187 01188 Support for two-dimensional interpolation (by successive 01189 one-dimensional interpolations) is given in \ref twod_intp (see 01190 \ref tintp_section, and a simple version of n-dimensional 01191 interpolation in \ref tensor_grid. 01192 01193 \hline 01194 \section const_section Physical constants 01195 01196 The constants from GSL are reworked with the type \c const \c 01197 double and placed in namespaces called gsl_cgs, gsl_cgsm, gsl_mks, 01198 gsl_mksa, and gsl_num. Some additional constants are given in the 01199 namespace o2scl_const. Some of the numerical values have been 01200 updated from recently released data from NIST. 01201 01202 \hline 01203 \section funct_section Function Objects 01204 01205 Functions are passed to numerical routines using template-based 01206 function classes, sometimes called "functors". There are several 01207 basic kinds of function 01208 objects: 01209 - \ref funct : One function of one variable 01210 - \ref multi_funct : One function of several variables 01211 - \ref mm_funct : \c n functions of \c n variables 01212 - \ref fit_funct : One function of one variable with \c n 01213 fitting parameters 01214 - \ref ode_funct : \c n derivatives as a function of \c n function 01215 values and the value of the independent variable 01216 - \ref jac_funct : Jacobian function for solver 01217 - \ref grad_funct : Gradient function for minimizers 01218 - \ref ool_hfunct : Hessian product for constrained minimization 01219 01220 For each of these classes (except \ref funct), there is a version 01221 named \c _vfunct instead of \c _funct which is designed to be used 01222 with C-style arrays instead of vector classes. 01223 01224 The class name suffixes denote children of a generic function type 01225 which are created using different kinds of inputs: 01226 - _fptr: function pointer for a static or global function 01227 - _gsl: GSL-like function pointer 01228 - _mfptr: function pointer template for a class member function 01229 - _cmfptr: function pointer template for a class member function which 01230 is const 01231 - _strings: functions specified using strings, e.g. "x^2-2", 01232 which are in the separate \o2x package. 01233 - _noerr: (for \ref funct and multi_funct) a function which 01234 directly returns the function value rather than returning 01235 an integer error value 01236 - _nopar: (for \ref funct) a function which has no parameters and 01237 directly returns the function value. 01238 01239 See the \ref ex_fptr_sect and the \ref ex_mroot_sect which 01240 provide detailed examples of how functions can be specified 01241 to classes through these function objects. 01242 01243 There is a small overhead associated with the indirection: a "user 01244 class" accesses the function class which then calls function which 01245 was specified in the constructor of the function class. In many 01246 problems, the overhead associated with the indirection is small. 01247 Some of this overhead can always be avoided by inheriting directly 01248 from the function class and thus the user class will make a direct 01249 virtual function call. To eliminate the overhead entirely, one can 01250 specify a new type for the template parameter in the user class. 01251 01252 Note that virtual functions can be specified through 01253 this mechanism as well. For example, if \ref cern_mroot 01254 is used to solve a set of equations specified as 01255 \include fptr_doc.cpp 01256 Then the solver will solve the member function in the derived 01257 type, not the parent type. 01258 01259 Note also that providing a user access to a function object 01260 instantiatied with a protected or private member function is 01261 (basically) the same as providing them access to that function. 01262 01263 \hline 01264 \section table_section Data tables 01265 01266 The class \ref table is a container to hold and perform operations 01267 on related columns of data. It supports column operations, 01268 interpolation, column reference by either name or index, binary 01269 searching (in the case of ordered columns), sorting, and fitting 01270 two columns to a user-specified function. 01271 01272 \hline 01273 \section string_section String manipulation 01274 01275 There are a couple classes and functions to help manipulate 01276 strings of text. Conversion routines for \c std::string 01277 objects are given in \ref string_conv.h and include 01278 - \ref ptos() - pointer to string 01279 - \ref itos() - integer to string 01280 - \ref dtos() - double to string 01281 - \ref stoi() - string to integer 01282 - \ref stod() - string to double 01283 01284 See also \ref size_of_exponent(), \ref format_float, 01285 and \ref double_to_ieee_string(). 01286 01287 A class called \ref columnify converts a set of 01288 strings into nicely formatted columns by padding with the 01289 necessary amount of spaces. This class operates on string objects 01290 of type \c std::string, and also works will for formatting columns 01291 of floating-point numbers. This class is used to provide output 01292 for matrices in the functions \ref matrix_out(), \ref 01293 matrix_out_paren(), and \ref matrix_cx_out_paren(). For output 01294 of vectors, see \ref vector_out() in \ref array.h. 01295 01296 A related function, \ref screenify(), reformats a column of 01297 strings into many columns stored row-by-row in a new string 01298 array. It operates very similar to the way the classic Unix 01299 command \c ls organizes files and directories in multiple columns 01300 in order to save screen space. 01301 01302 The function \ref count_words() counts the number of "words" 01303 in a string, which are delimited by whitespace. 01304 01305 \hline 01306 \section diff_section Differentiation 01307 01308 Differentiation is performed by descendants of \ref deriv and the 01309 classes are provided. These allow one to calculate either first, 01310 second, and third derivatives. The GSL approach is used in \ref 01311 gsl_deriv, and the CERNLIB routine is used in \ref 01312 cern_deriv. Both of these compute derivatives for a function 01313 specified using a descendant of \ref funct. For functions which 01314 are tabulated over equally-spaced abscissas, the class \ref 01315 eqi_deriv is provided which applies the formulas from Abramowitz 01316 and Stegun at a specified order. 01317 01318 \b Warning: For gsl_deriv and cern_deriv, the second and third 01319 derivatives are calculated by naive repeated application of the 01320 code for the first derivative and can be particularly troublesome 01321 if the function is not sufficiently smooth. Error estimation is 01322 not provided for second and third derivatives. 01323 01324 \hline 01325 \section inte_section Integration 01326 01327 Integration is performed by descendants of \ref inte and is 01328 provided in the library \c o2scl_inte. 01329 01330 There are several routines for one-dimensional integration. 01331 - General integration over a finite interval: cern_adapt, 01332 cern_gauss, cern_gauss56, gsl_inte_qag, and gsl_inte_qng. 01333 - General integration from 0 to \f$ \infty \f$ : gsl_inte_qagiu 01334 - General integration from \f$ -\infty \f$ to 0: gsl_inte_qagil 01335 - General integration from \f$ -\infty \f$ to \f$ \infty \f$ : 01336 gsl_inte_qagi 01337 - General integration over a finite interval for a function with 01338 singularities: gsl_inte_qags and gsl_inte_qagp 01339 - Cauchy principal value integration over a finite interval: 01340 cern_cauchy and gsl_inte_qawc 01341 - Integration over a function weighted by \c cos(x) or \c sin(x): 01342 \ref gsl_inte_qawo_cos and \ref gsl_inte_qawo_sin 01343 - Fourier integrals: \ref gsl_inte_qawf_cos and \ref 01344 gsl_inte_qawf_sin 01345 - Integration over a weight function 01346 \f[ 01347 W(x)=(x-a)^{\alpha}(b-x)^{\beta}\log^{\mu}(x-a)\log^{\nu}(b-x) 01348 \f] 01349 is performed by \ref gsl_inte_qaws. 01350 01351 For the GSL-based integration routines, the variables inte::tolx 01352 and inte::tolf have the same role as the quantities usually 01353 denoted in the GSL integration routines by \c epsabs and \c 01354 epsrel. In particular, the integration classes attempt to ensure 01355 that 01356 \f[ 01357 |\mathrm{result}-I| \leq \mathrm{Max}(\mathrm{tolx}, 01358 \mathrm{tolf}|I|) 01359 \f] 01360 and returns an error to attempt to ensure that 01361 \f[ 01362 |\mathrm{result}-I| \leq \mathrm{abserr} \leq 01363 \mathrm{Max}(\mathrm{tolx},\mathrm{tolf}|I|) 01364 \f] 01365 where \c I is the integral to be evaluated. Even when the 01366 corresponding descendant of inte::integ() returns success, these 01367 inequalities may fail for sufficiently difficult functions. All 01368 of the GSL integration routines except for gsl_inte_qng use 01369 a workspace given in gsl_inte_table which holds the results 01370 of the various subdivisions of the original interval. The 01371 size of this workspace (and thus then number of subdivisions) can 01372 be controlled with gsl_inte_table::set_wkspace(). 01373 01374 The GSL routines were originally based on QUADPACK, which is 01375 available at http://www.netlib.org/quadpack . 01376 01377 \note The GSL integration routines can sometimes lose precision 01378 if the integrand is everywhere much smaller than unity. Some 01379 rescaling is required in these cases. 01380 01381 Multi-dimensional hypercubic integration is performed by \ref 01382 composite_inte, the sole descendant of multi_inte. \ref 01383 composite_inte allows you to specify a set of one-dimensional 01384 integration routines (objects of type \ref inte) and apply them to 01385 a multi-dimensional problem. 01386 01387 General multi-dimensional integration is performed by \ref 01388 comp_gen_inte, the sole descendant of \ref gen_inte. The user is 01389 allowed to specify a upper and lower limits which are functions of 01390 the variables for integrations which have not yet been performed, 01391 i.e. the n-dimensional integral 01392 \f[ 01393 \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)} 01394 f(x_0, x_1) ... 01395 \int_{x_{\mathrm{n}-1}=a_{\mathrm{n}-1}(x_0,x_1,..,x_{\mathrm{n}-2})}^ 01396 {x_{\mathrm{n}-1}=b_{\mathrm{n}-1}(x_0,x_1,..,x_{\mathrm{n}-2})} 01397 f(x_0,x_1,...,x_{\mathrm{n-1}})~d x_{\mathrm{n}-1}~...~d x_1~d x_0 01398 \f] 01399 Again, one specifies a set of \ref inte objects to apply to 01400 each variable to be integrated over. 01401 01402 Monte Carlo integration is also provided (see \ref mcarlo_section). 01403 01404 \hline 01405 \section poly_section Roots of Polynomials 01406 01407 Classes are provided for solving quadratic, cubic, and quartic 01408 equations as well as general polynomials. There is a standard 01409 nomenclature: classes which handle polynomials with real 01410 coefficients and real roots end with the suffix <tt>_real</tt> 01411 (quadratic_real, cubic_real and quartic_real), classes which 01412 handle real coefficients and complex roots end with the suffix 01413 <tt>_real_coeff</tt> (quadratic_real_coeff, cubic_real_coeff, 01414 quartic_real_coeff, and poly_real_coeff), and classes which handle 01415 complex polynomials with complex coefficients end with the suffix 01416 <tt>_complex</tt> (quadratic_complex, cubic_complex, 01417 quartic_complex, and poly_complex). As a reminder, complex roots 01418 may not occur in conjugate pairs if the coefficients are not 01419 real. Most of these routines will return an error if the leading 01420 coefficient is zero. 01421 01422 In the public interfaces to the polynomial solvers, the 01423 complex type <tt>std::complex<double></tt> is used. These can 01424 be converted to and from the GSL complex type using the 01425 \ref complex_to_gsl() and \ref gsl_to_complex() functions. 01426 01427 At present, the polynomial routines work with complex numbers as 01428 objects of type \c std::complex<double> and are located in library 01429 \c o2scl_other. 01430 01431 For quadratics, \ref gsl_quadratic_real_coeff is the best if the 01432 coefficients are real, while if the coefficients are complex, use 01433 \ref quadratic_std_complex. For cubics with real coefficients, 01434 \ref cern_cubic_real_coeff is the best, while if the coefficients 01435 are complex, use \ref cubic_std_complex. 01436 01437 For a quartic polynomial with real coefficients, \ref 01438 cern_quartic_real_coeff is the best, unless the coefficients of 01439 odd powers happen to be small, in which case, \ref 01440 gsl_quartic_real2 tends to work better. For quartics, generic 01441 polynomial solvers such as \ref gsl_poly_real_coeff can provide 01442 more accurate (but slower) results. If the coefficients are 01443 complex, then you can use \ref simple_quartic_complex. 01444 01445 \hline 01446 \section solve_section Equation Solving 01447 01448 \subsection onedsolve_subsect One-dimensional solvers 01449 01450 Solution of one equation in one variable is accomplished by 01451 children of the class \ref root. 01452 01453 For one-dimensional solving, use cern_root or gsl_root_brent if 01454 you have the root bracketed, or gsl_root_stef if you have the 01455 derivative available. If you have neither a bracket or a 01456 derivative, you can use cern_mroot_root. 01457 01458 The \ref root base class provides the structure for three 01459 different solving methods: 01460 - \ref root::solve() which solves a function given an initial 01461 guess \c x 01462 - \ref root::solve_bkt() which solves a function given a solution 01463 bracketed between \c x1 and \c x2. The values of the function at 01464 \c x1 and \c x2 should have different signs. 01465 - \ref root::solve_de() which solves a function given an initial 01466 guess \c x and the derivative of the function \c df. 01467 01468 If not all of these three functions are overloaded, then the 01469 source code in the \ref root base class is designed to try to 01470 automatically provide the solution using the remaining 01471 functions. Most of the one-dimensional solving routines, in their 01472 original form, are written in the second or third form above. For 01473 example, gsl_root_brent is originally a bracketing routine of the 01474 form root::solve_bkt(), but calls to either root::solve() or 01475 root::solve_de() will attempt to automatically bracket the 01476 function given the initial guess that is provided. Of 01477 course, it is frequently most efficient to use the solver in the 01478 way it was intended. 01479 01480 \subsection multisolve_subsect Multi-dimensional solvers 01481 01482 Solution of more than one equation is accomplished by descendants 01483 of the class \ref mroot . The higher-level interface is provided 01484 by the function \ref mroot::msolve() . 01485 01486 For multi-dimensional solving, you can use either cern_mroot or 01487 gsl_mroot_hybrids. While cern_mroot cannot utilize user-supplied 01488 derivatives, gsl_mroot_hybrids can use user-supplied derivative 01489 information (as in the GSL hybridsj method) using the function 01490 \ref gsl_mroot_hybrids::msolve_de() . 01491 01492 \hline 01493 \section min_section Minimization 01494 01495 One-dimensional minimization is performed by descendants of \ref 01496 minimize . There are two one-dimensional minimization algorithms, 01497 \ref cern_minimize and \ref gsl_min_brent, and they are both 01498 bracketing algorithms type where an interval and an initial guess 01499 must be provided. If only an initial guess and no bracket is 01500 given, these two classes will attempt to find a suitable bracket 01501 from the initial guess. While the \ref minimize base class is 01502 designed to allow future descendants to optionally use derivative 01503 information, this is not yet supported for any one-dimensional 01504 minimizers. 01505 01506 Multi-dimensional minimization is performed by descendants of 01507 multi_min: \ref gsl_mmin_simp2, \ref gsl_mmin_conp, \ref 01508 gsl_mmin_conf, and \ref gsl_mmin_bfgs2. (The class \ref 01509 gsl_mmin_simp2 has been updated with the new "simplex2" method 01510 from GSL-1.12. The older "simplex" method is also available in 01511 \ref gsl_mmin_simp .) The classes \ref gsl_mmin_simp and \ref 01512 gsl_mmin_simp2 do not require any derivative information. The 01513 remaining minimization classes are intended for use when the 01514 gradient of the function is available, but they can also 01515 automaticallly compute the \gradient numerically. The standard way 01516 to provide the \gradient is to use a child of \ref grad_funct (or 01517 \ref grad_vfunct). Finally, the user may specify the automatic 01518 gradient object of type \ref gradient (or \ref gradient_array) 01519 which is used by the minimizer to compute the gradient numerically 01520 when a function is not specified. 01521 01522 See an example for the usage of the multi-dimensional minimizers 01523 in \ref ex_mmin_sect . 01524 01525 Simulated annealing methods are also provided for multi-dimensional 01526 minimization (see \ref anneal_section). 01527 01528 It is important to note that not all of the minimization routines 01529 test the second derivative to ensure that it doesn't vanish to 01530 ensure that we have indeed found a true minimum. 01531 01532 The class \ref multi_min_fix provides a convenient way of 01533 fixing some of the parameters and minimizing over others, 01534 without requiring a the function interface to be rewritten. An 01535 example is given in \ref ex_mmin_fix_sect. 01536 01537 \hline 01538 \section conmin_section Constrained Minimization 01539 01540 \o2 reimplements the Open Optimization Library (OOL) available at 01541 http://ool.sourceforge.net. The associated classes allow 01542 constrained minimization when the constraint can be expressed as a 01543 hyper-cubic constraint on all of the independent variables. The 01544 routines have been rewritten and reformatted for C++ in order to 01545 facilitate the use of member functions and user-defined vector 01546 types as arguments. The base class is ool_constr_mmin and there 01547 are two different constrained minimzation algorithms implemented 01548 in ool_mmin_pgrad, ool_mmin_spg. (The ool_mmin_gencan minimizer is 01549 not yet finished). The \o2 implementation should be essentially 01550 identical to the most recently released version of OOL. 01551 01552 The constrained minimization classes operate in a similar way 01553 to the other multi-dimensional minimization classes (which are 01554 derived from multi_min). The constraints are specified with 01555 the function 01556 \code 01557 ool_constr_mmin::set_constraints(size_t nc, vec_t &lower, 01558 vec_t &upper); 01559 \endcode 01560 and the minimization can be performed by calling either 01561 multi_min::mmin() or multi_min::mmin_de() (if the \gradient is 01562 provided by the user). The method in \ref ool_mmin_gencan requires 01563 a Hessian vector product and the user can specify this product for 01564 the minimization by using \ref ool_constr_mmin::mmin_hess(). The 01565 Hessian product function can be specified as an object of type 01566 \ref ool_hfunct or \ref ool_hvfunct in a similar way to the other 01567 function objects in \o2. 01568 01569 There are five error codes defined in \ref ool_constr_mmin 01570 which are specific to the classes derived from OOL. 01571 01572 The class \ref gsl_anneal can handle some kinds of 01573 constraints by ignoring proposed steps which cause the 01574 user-specified function to return a non-zero value. 01575 01576 Also, a simple way of implementing constraints is to add a 01577 function to the original which increases the value outside of the 01578 allowed region. This can be done with the functions \ref 01579 constraint() and \ref lower_bound(). There are two analogous 01580 functions, \ref cont_constraint() and \ref cont_lower_bound(), 01581 which continuous and differentiable versions. Where possible, it 01582 is better to use the constrained minimization routines described 01583 below. 01584 01585 \hline 01586 \section mcarlo_section Monte Carlo Integration 01587 01588 Monte Carlo integration is performed by descendants of mcarlo_inte 01589 (\ref gsl_monte, \ref gsl_miser, and \ref gsl_vegas). These 01590 routines are generally superior to the direct methods for 01591 integrals over regions with large numbers of spatial dimensions. 01592 01593 \hline 01594 \section anneal_section Simulated Annealing 01595 01596 Minimization by simulated annealing is performed by descendants of 01597 sim_anneal (see \ref gsl_anneal). Because simulated annealing is 01598 particularly well-suited to parallelization, a multi-threaded 01599 minimizer analogous to \ref gsl_anneal is given in \ref anneal_mt. 01600 This header-only class uses the Boost libraries and requires it 01601 for use. 01602 01603 \hline 01604 \section fit_section Non-linear Least-Squares Fitting 01605 01606 Fitting is performed by descendants of \ref fit_base and fitting 01607 functions can be specifed using \ref fit_funct. The GSL fitting 01608 routines (scaled and unscaled) are implemented in gsl_fit. A 01609 generic fitting routine using a minimizer object specified as a 01610 child of multi_min is implemented in min_fit. When the multi_min 01611 object is (for example) a sim_anneal object, min_fit can avoid 01612 local minima which can occur when fitting noisy data. 01613 01614 \hline 01615 \section ode_section Solution of Ordinary Differential Equations 01616 01617 Classes for non-adaptive integration are provided as descendents 01618 of \ref odestep and classes for adaptive integration are 01619 descendants of \ref adapt_step. To specify a set of functions 01620 to these classes, use a child of ode_funct for a generic 01621 vector type or a child of ode_vfunct when using arrays. 01622 01623 Solution of simple initial value problems is performed by \ref 01624 ode_iv_solve. This class contains a couple different methods, 01625 depending on whether the user needs only the final value or the 01626 solution on a fixed grid. A example demonstrating the solution 01627 of initial value problems is given in \ref ex_ode_sect. 01628 01629 The solution of boundary-value problems is based on the abstract 01630 base class \ref ode_bv_solve. At the moment, a simple shooting method 01631 is the only implementation of this base class and is given 01632 in \ref ode_bv_shoot . An experimental multishooting class is 01633 given in \ref ode_bv_multishoot . 01634 01635 An application of linear solvers to solve finite-difference 01636 equations approximating a boundary value problem is given in \ref 01637 ode_it_solve . A example demonstrating the iterative solution of a 01638 boundary value problem is given in \ref ex_ode_it_sect . 01639 01640 \hline 01641 \section rng_section Random Number Generation 01642 01643 Random number generators are descendants of \ref rnga . While the 01644 base object \ref rnga is created to allow user-defined random 01645 number generators, the only random number generator presently 01646 included are from GSL. Because speed is frequently an issue, 01647 some design choices were made to ensure fast execution 01648 - The GSL random number generator code is 01649 reimplemented, rather than simply wrapped around the GSL code. 01650 - The interface does not use virtual functions. 01651 - Random number generators are implemented as template parameters 01652 in \ref sim_anneal and \ref mcarlo_inte, rather than as pointers. 01653 01654 \hline 01655 \section tintp_section Two-dimensional Interpolation 01656 01657 Successive use of \ref smart_interp is implemented in \ref 01658 twod_intp, which is useful for interpolating data presented on a 01659 two-dimensional grid (though the spacings between grid points need 01660 not be equal). An example demonstrating the use of \ref twod_intp 01661 is given in ex_twod_intp_sect. Also, one can compute \contour 01662 lines from data represented on a grid using the \ref contour 01663 class. 01664 01665 If data is arranged without a grid, then \ref planar_intp can 01666 be used. At present, the only way to compute \contour lines on 01667 data which is not defined on a grid is to use \ref planar_intp to 01668 recast the data on a grid and then use \ref contour afterwards. 01669 01670 Higher-dimensional interpolation is possible with \ref tensor_grid. 01671 01672 \hline 01673 \section gslcheb_section Chebyshev Approximation 01674 01675 A class implementing the Chebyshev approximations based on GSL is 01676 given in \ref gsl_chebapp. This class has its own copy 01677 constructor, so that Chebyshev approximations can be copied and 01678 passed as arguments to functions. Derivatives and integrals of 01679 \ref gsl_chebapp objects are created as new \ref gsl_chebapp 01680 objects which can be easily manipulated. 01681 01682 \hline 01683 \section unitconv_section Unit Conversions 01684 01685 There is a class which performs conversion between units specified 01686 with strings in \ref convert_units. The \ref convert_units class 01687 also uses a system call to the GNU units command to obtain the 01688 proper conversion factors. Unit conversions are cached 01689 to avoid unnecessary system calls. 01690 01691 \hline 01692 \section other_section Other classes and functions 01693 01694 The \o2 library contains several classes which are still under 01695 development and are to be considered experimental. While it is 01696 expected that the testing code associated with these classes will 01697 succeed on most any system, the interface, structure, and basic 01698 approaches used by these classes may change in future versions of 01699 \o2. 01700 01701 \b Three-dimensional data tables - \ref table3d \n 01702 \b Series \b acceleration - \ref gsl_series \n 01703 \b Command-line interface - \ref cli \n 01704 \b Automatic bin sizing - \ref bin_size \n 01705 \b Fourier \b transforms - \ref gsl_fft \n 01706 \b Polylogarithms - \ref polylog \n 01707 01708 \hline 01709 \section lset_section Library settings 01710 01711 There are a couple library settings which are handled by 01712 a global object \ref lib_settings of type \ref lib_settings_class. 01713 01714 There are several data files that are used by various classes in 01715 the library. The installation procedure should ensure that these 01716 files are automatically found. However, if these data files are 01717 moved after installation, then a call to 01718 lib_settings_class::set_data_dir() can adjust the library to use 01719 the new directory. It is assumed that the directory structure 01720 within the data directory has not changed. 01721 01722 \hline 01723 \section io_section Object I/O 01724 01725 The I/O portion of the library is still experimental. 01726 01727 Collections of objects can be stored in a \ref collection class, 01728 and these collections can be written to or read from text or 01729 binary files. User-defined classes may be added to the collections 01730 and may be read and written to files as long as a descendant of 01731 \ref io_base is provided. 01732 01733 Every type has an associated I/O type which is a descendant of 01734 \ref io_base. In order to perform any sort of input/output on any 01735 type, an object of the corresponding I/O type must be instantiated 01736 by the user. This is not done automatically by the library. (Since 01737 it doesn't know which objects are going to be used ahead of time, 01738 the library would have to instantiate <em>all</em> of the I/O 01739 objects, which is needlessly slow.) This makes the I/O slightly 01740 less user-friendly, but much more efficient. For convenience, each 01741 subsection of the library has a class (named with an \c _ioc 01742 suffix) which will automatically allocate all I/O types for that 01743 subsection. 01744 01745 <b>Level 1 functions:</b> Functions that input/output data from 01746 library-defined objects and internal types from files and combine 01747 these objects in collections. These are primarily member functions 01748 of the class \ref collection. 01749 01750 <b>Level 2 functions:</b> Functions which are designed to allow 01751 the user to input or output data for user-generated objects. These 01752 are primarily member functions of classes \ref cinput and \ref 01753 coutput. 01754 01755 <b>Level 3 functions:</b> Functions which allow low-level 01756 modifications on how input and output is performed. Usage of 01757 level 3 functions is not immediately recommended for the casual 01758 user. 01759 01760 <b>Level 1 usage</b>: 01761 01762 For adding an object to a collection when you have a pointer 01763 to the I/O object for the associated type: 01764 \code 01765 int collection::add(std::string name, io_base *tio, void *vec, 01766 int sz=0, int sz2=0, bool overwrt=true, bool owner=false); 01767 \endcode 01768 For adding an object to a collection otherwise: 01769 \code 01770 int collection::add(std::string name, std::string stype, 01771 void *vec, int sz=0, int sz2=0, 01772 bool overwrt=true, bool owner=false); 01773 \endcode 01774 01775 To retrieve an object as a <pre>void *</pre> from a collection 01776 use one of: 01777 \code 01778 int get(std::string tname, void *&vec); 01779 int get(std::string tname, void *&vec, int &sz); 01780 int get(std::string tname, void *&vec, int &sz, int &sz2); 01781 int get(std::string tname, std::string &stype, void *&vec); 01782 int get(std::string tname, std::string &stype, void *&vec, int &sz); 01783 int get(std::string tname, std::string &stype, void *&vec, int &sz, 01784 int &sz2); 01785 \endcode 01786 When retrieving a scalar object without error- and type-checking you 01787 can use the shorthand version: 01788 \code 01789 void *get(std::string name); 01790 \endcode 01791 01792 To output one object to a file: 01793 \code 01794 int collection::out_one(out_file_format *outs, std::string stype, 01795 std::string name, void *vp, int sz=0, int sz2=0); 01796 \endcode 01797 01798 To input one object from a file with a given type and name: 01799 \code 01800 int collection::in_one_name(in_file_format *ins, std::string stype, 01801 std::string name, void *&vp, int &sz, int &sz2); 01802 \endcode 01803 To input the first object of a given type from a file: 01804 \code 01805 int collection::in_one(in_file_format *ins, std::string stype, 01806 std::string &name, void *&vp, int &sz, int &sz2); 01807 \endcode 01808 01809 <b>Level 2 usage (string-based)</b>: 01810 01811 If you don't have a pointer to the io_base child object corresponding 01812 to the type of subobject that you are manipulating, then you can use 01813 the following functions, which take the type name as a string. 01814 01815 To input a sub-object in an io_base template for which memory 01816 has already been allocated use one of: 01817 \include io_doc1.cpp 01818 01819 To automatically allocate memory and input a sub-object of a 01820 io_base template use one of: 01821 \include io_doc2.cpp 01822 01823 To output a subobject in an io_base template use: 01824 \code 01825 int collection::object_out(std::string type, out_file_format *outs, 01826 void *op, int sz=0, int sz2=0, std::string name=""); 01827 \endcode 01828 01829 <b>Level 2 usage (with io_base pointer)</b>: 01830 01831 To input a sub-object in an io_base template for which memory 01832 has already been allocated use one of: 01833 \include io_doc4.cpp 01834 01835 To automatically allocate memory and input a sub-object of a 01836 io_base template use one of: 01837 \include io_doc5.cpp 01838 01839 To output a subobject in an io_base template use: 01840 \include io_doc6.cpp 01841 01842 To automatically allocate/deallocate memory for an object, use: 01843 \code 01844 virtual int mem_alloc(object *&op); 01845 virtual int mem_alloc_arr(object *&op, int sz); 01846 virtual int mem_alloc_2darr(object **&op, int sz, int sz2); 01847 virtual int mem_free(object *op); 01848 virtual int mem_free_arr(object *op); 01849 virtual int mem_free_2darr(object **op, int sz); 01850 \endcode 01851 01852 \subsection iotlate_subsect Usage of io_tlate 01853 01854 The functions io_tlate::input() and io_tlate::output() need to be 01855 implemented for every class has information for I/O. For 01856 subobjects of the class, cinput::object_in() and 01857 cinput::object_out() can be called to input or output the 01858 information associated with the subobject. For input, 01859 cinput::object_in_name(), cinput::object_in_mem(), and 01860 cinput::object_in_mem_name() allow the freedom to input an object 01861 with a name or with memory allocation. The function 01862 coutput::object_out_name() allows one to output an object with a 01863 name. If the class contains a pointer to the subobject, then 01864 io_base::pointer_in() or io_base::pointer_out() can be used. 01865 01866 \hline 01867 \section source_section Example source code 01868 01869 \note All of these examples are provided under the GPLv3 license, 01870 although to save space the licenses are not reproduced for each 01871 example. See \ref license_section for more information. 01872 01873 \subsection exlist_subsect Example list 01874 01875 - \ref ex_fptr_sect 01876 - \ref ex_mroot_sect 01877 - \ref ex_mmin_sect 01878 - \ref ex_mmin_fix_sect 01879 - \ref ex_deriv_sect 01880 - \ref ex_inte_sect 01881 - \ref ex_ode_sect 01882 - \ref ex_stiff_sect 01883 - \ref ex_anneal_sect 01884 - \ref ex_minte_sect 01885 - \ref ex_contour_sect 01886 - \ref ex_twod_intp_sect 01887 - \ref ex_mandel_sect 01888 - \ref ex_ode_it_sect 01889 01890 \comment 01891 01892 - \ref ex_ublas_sect 01893 01894 \c ex_diff.cpp computes the derivative of a tabulated function 01895 01896 \c ex_table.cpp demonstrates the use of the \ref table class 01897 01898 \c ex_file.cpp demonstrates the file I/O 01899 01900 \endcomment 01901 01902 \subsection ex_fptr_sect Function and solver example 01903 01904 This example shows how to provide functions to \o2 01905 classes by solving the equation 01906 \f[ 01907 \left\{ 1+\frac{1}{p_2} 01908 \sin \left[ 50 \left( x-p_1 \right) \right] \right\} 01909 \tan^{-1} \left[ 4 \left( x-p_1 \right) \right] = 0 01910 \f] 01911 Where \f$ p_1 = 0.01 \f$ and \f$ p_2 = 1.1 \f$. The parameter 01912 \f$ p_1 \f$ is stored as member data for the class, and the 01913 parameter \f$ p_2 \f$ is an argument to the member function. 01914 01915 The image below shows how the solver progresses to the 01916 solution of the example function. 01917 \image html ex_fptr.png "ex_fptr.png" 01918 \image latex ex_fptr.eps "ex_fptr.eps" width=9cm 01919 01920 \dontinclude ex_fptr.cpp 01921 \skip Example: 01922 \until End of example 01923 01924 \subsection ex_mroot_sect Multi-dimensional solver example 01925 01926 This demonstrates several ways of using the multi-dimensional 01927 solvers to solve the equations 01928 \f{eqnarray*} 01929 \sin \left( x_0 - \frac{1}{4} \right) &=& 0 \nonumber \\ 01930 \sin \left( x_1 - \frac{1}{5} \right) &=& 0 01931 \f} 01932 01933 \dontinclude ex_mroot.cpp 01934 \skip Example: 01935 \until End of example 01936 01937 \subsection ex_mmin_sect Multidimensional minimizer example 01938 01939 This example uses the \o2 minimizers based on GSL to \minimize 01940 the function 01941 \f[ 01942 y=\left(x_0-2\right)^2+\left(x_1-1\right)^2 01943 \f] 01944 01945 \dontinclude ex_mmin.cpp 01946 \skip Example: 01947 \until End of example 01948 01949 \subsection ex_mmin_fix_sect Minimizer fixing variables example 01950 01951 This example uses the \ref multi_min_fix class to \minimize 01952 the function 01953 \f[ 01954 y=\left(x_0-2\right)^2+\left(x_1-1\right)^2+x_2^2 01955 \f] 01956 while fixing some of the parameters. 01957 01958 \dontinclude ex_mmin_fix.cpp 01959 \skip Example: 01960 \until End of example 01961 01962 \subsection ex_deriv_sect Numerical differentiation example 01963 01964 This example computes first and second derivatives of 01965 \f[ 01966 y(x) = \sin (2 x) + \frac{1}{2} 01967 \f] 01968 01969 \dontinclude ex_deriv.cpp 01970 \skip Example: 01971 \until End of example 01972 01973 \subsection ex_inte_sect Numerical integration example 01974 01975 This example computes the integrals 01976 \f{eqnarray*} 01977 &\int_{-\infty}^{\infty} e^{-x^2} ~dx& \nonumber \\ 01978 &\int_0^{\infty} e^{-x^2} ~dx& \nonumber \\ 01979 &\int_{-\infty}^{0} e^{-x^2} ~dx& \nonumber \\ 01980 &\int_0^1 \left[ \sin (2 x) + \frac{1}{2} \right]~dx& 01981 \f} 01982 and compares the computed results with the exact results. 01983 01984 \dontinclude ex_inte.cpp 01985 \skip Example: 01986 \until End of example 01987 01988 \subsection ex_ode_sect Ordinary differential equations example 01989 01990 This example solves the differential equations defining the the 01991 Bessel and Airy functions with both the Cash-Karp and 01992 Prince-Dormand Steppers. It demonstrates the use of \ref gsl_rkck, 01993 \ref gsl_rk8pd, \ref gsl_astep, and \ref ode_iv_solve. 01994 01995 The Bessel functions are defined by 01996 \f[ 01997 y^{\prime\prime} = \frac{1}{x^2} \left[ 01998 y \left(\alpha^2 - x^2\right) -x y^{\prime} \right] 01999 \f] 02000 The Bessel functions of the first kind, \f$ J_{\alpha}(x) \f$ are 02001 finite at the origin, and the example solves the \f$ \alpha=1 \f$ case, 02002 where \f$ J_1(0) = 0 \f$ and \f$ J_1^{\prime}(0) = 1/2 \f$. 02003 02004 The Airy functions are defined by 02005 \f[ 02006 y^{\prime\prime} = y x 02007 \f] 02008 This example solves for the Airy function of the first kind, 02009 \f$ Ai(x) \f$. 02010 02011 Note that, when the step size is fixed, the Bessel function 02012 example is one case where the Prince-Dormand stepper (even though 02013 of higher order than the Cash-Karp stepper) is actually less 02014 accurate! 02015 02016 \dontinclude ex_ode.cpp 02017 \skip Example: 02018 \until End of example 02019 02020 \subsection ex_stiff_sect Stiff differential equation example 02021 02022 This example solves the differential equations 02023 \f{eqnarray*} 02024 y_0^{\prime} &=& 480 y_0 + 980 y_1 \nonumber \\ 02025 y_1^{\prime} &=& -490 y_0 - 990 y_1 02026 \f} 02027 which have the exact solution 02028 \f{eqnarray*} 02029 y_0 &=& -e^{-500 x} + 2 e^{-10 x} \nonumber \\ 02030 y_1 &=& e^{-500 x} - e^{-10 x} 02031 \f} 02032 using both the stiff stepper \ref gsl_bsimp and the standard 02033 adaptive stepper \ref gsl_astep . The adaptive stepper fails 02034 as \f$ x \f$ becomes larger. 02035 02036 \dontinclude ex_stiff.cpp 02037 \skip Example: 02038 \until End of example 02039 02040 \subsection ex_anneal_sect Simulated annealing example 02041 02042 \dontinclude ex_anneal.cpp 02043 \skip Example: 02044 \until End of example 02045 02046 \subsection ex_minte_sect Multidimensional integration example 02047 02048 \dontinclude ex_minte.cpp 02049 \skip Example: 02050 \until End of example 02051 02052 \subsection ex_contour_sect Contour lines example 02053 02054 \dontinclude ex_contour.cpp 02055 \skip Example: 02056 \until End of example 02057 02058 \subsection ex_twod_intp_sect Two-dimensional interpolation example 02059 02060 \dontinclude ex_twod_intp.cpp 02061 \skip Example: 02062 \until End of example 02063 02064 This example creates a sample 3 by 3 grid of data with the 02065 function \f$ \left[ \sin \left( x/10 + 3 y/10 \right) \right]^2 \f$ 02066 and performs some interpolations and compares them with the 02067 exact result. 02068 \include ex_twod_intp.out 02069 02070 \subsection ex_mandel_sect Mandelbrot example 02071 02072 \dontinclude ex_mandel.cpp 02073 \skip Example: 02074 \until End of example 02075 02076 The information stored in the table3d object in ex_mandel.out 02077 can be plotted: 02078 \image html mandel_plot.png "mandel_plot.png" 02079 \image latex mandel_plot.eps "mandel_plot.eps" width=9cm 02080 02081 \subsection ex_ode_it_sect Iterative solution of ODEs example 02082 02083 This example solves the ODEs 02084 \f{eqnarray*} 02085 y_0^{\prime\prime} &=& y_1 \nonumber \\ 02086 y_1^{\prime\prime} &=& y_0+y_1\nonumber \\ 02087 y_2^{\prime\prime} &=& y_0+y_2 02088 \f} 02089 given the boundary conditions 02090 \f{eqnarray*} 02091 y_0(x=0)&=&1 \nonumber \\ 02092 y_1(x=0)^2+y_2(x=0)^2&=&2 \nonumber \\ 02093 y_1(x=1) &=& 3 02094 \f} 02095 02096 \dontinclude ex_ode_it.cpp 02097 \skip Example: 02098 \until End of example 02099 02100 \comment 02101 \subsection ex_ublas_sect ublas vector example 02102 02103 \dontinclude ex_ublas.cpp 02104 \skip Example: 02105 \until End of example 02106 \endcomment 02107 02108 \hline 02109 \section design_section Design Considerations 02110 02111 The design goal is to create an object-oriented computing library 02112 with classes that perform common numerical tasks. The most 02113 important principle is that the library should add functionality 02114 to the user while at the same time retaining as much freedom for 02115 the user as possible and allowing for ease of use and extensibility. 02116 To that end, 02117 - The classes which utilize user-specified functions 02118 should be able to operate on member functions without requiring 02119 a particular inheritance structure, 02120 - The interfaces ought to be generic so that the user 02121 can create new classes which perform related numerical 02122 tasks through inheritance, 02123 - The classes should not use static variables or functions 02124 - Const-correctness and type-safety should be used wherever possible, and 02125 - The design should be somewhat compatible with GSL. 02126 Also, the library provides higher-level routines 02127 for situations which do not require lower-level access. 02128 02129 <b>Header file dependencies</b> 02130 02131 For reference, it's useful to know how the top-level header files 02132 depend on each other, since it can be difficult to trace 02133 everything down. In the \c base directory, the following are some 02134 of the most "top-level" header files and their associated 02135 dependencies within \o2 (there are other dependencies on GSL and 02136 the C standard library not listed here). 02137 \code 02138 err_hnd.h : (none) 02139 lib_settings.h : (none) 02140 array.h: err_hnd.h 02141 vector.h: err_hnd.h 02142 sring_conv.h : lib_settings.h 02143 misc.h : err_hnd.h lib_settings.h 02144 test_mgr.h : string_conv.h 02145 uvector_tlate.h: err_hnd.h string_conv.h array.h vector.h 02146 ovector_tlate.h: err_hnd.h string_conv.h 02147 uvector_tlate.h array.h vector.h 02148 \endcode 02149 02150 <B>The use of templates</b> 02151 02152 Templates are used extensively, and this makes for longer 02153 compilation times so any code that can be removed conveniently 02154 from the header files should be put into source code files 02155 instead. 02156 02157 \subsection errdesign_subsect Error handling 02158 02159 <b>Thread safety</b> 02160 02161 Two approaches to thread-safe error handling which are worth 02162 comparing: the first is GSL which uses return codes and global 02163 function for an error handler, and the second is the Math/Special 02164 Functions section of Boost, which uses a separate policy type for 02165 each function. One issue is thread safety: the GSL approach is 02166 thread safe only in the sense that one can in principle use the 02167 return codes in different threads to track errors. What one cannot 02168 do in GSL is use different user-defined error handlers for 02169 different threads. The Special Functions library allows one to 02170 choose a different Policy for every special function call, and 02171 thus allows quite a bit more flexibility in designing 02172 multi-threaded error handling. 02173 02174 \subsection memalloc_subsect Memory allocation functions 02175 02176 Several classes have allocate() and free() functions to allocate 02177 and deallocate memory. If an error occurs in an allocate() 02178 function, the function should free() the partial memory that was 02179 allocated and then call the error handler. Functions which 02180 deallocate memory should never fail and should never 02181 be required to call the error handler. Similarly, class 02182 destructors should never be required to call the error 02183 handler. 02184 02185 \subsection vecdesign_subsect Vector design 02186 02187 \o2 vector and matrix types are a hybrid approach: creating objects 02188 compatibile with GSL, while providing syntactic simplicity and 02189 object-oriented features common to C++ vector classes. In terms 02190 of their object-oriented nature, they are not as elegant as 02191 the ublas vector types from ublas, but for many applications they 02192 are also faster (and they are always at least as fast). 02193 02194 However, ensuring const-correctness makes the design a bit thorny, 02195 and this is still in progress. 02196 02197 \subsection typecase_subsect Type-casting in vector and matrix design 02198 02199 \o2 uses a GSL-like approach where viewing const double * 02200 arrays is performed by explicitly casting aways const'ness 02201 internally and then preventing the user from changing the data. 02202 02203 In GSL, the preprocessor output for \c vector/view_source.c is: 02204 \include gsl_vector_doc.cpp 02205 Note the explicit cast from const double * to double *. This 02206 is similar to what is done in \c src/base/ovector_tlate.h. 02207 02208 \subsection define_subsect Define constants and macros 02209 02210 There are a couple define constants and macros that \o2 02211 understands, they are all in upper case and begin with the prefix 02212 <tt>O2SCL_</tt>. 02213 02214 Range-checking for arrays and matrices is turned on by default, 02215 but can be turned off by defining <tt>O2SCL_NO_RANGE_CHECK</tt> 02216 during the initial configuration of the library. To see how the 02217 library was configured at runtime, use the \ref lib_settings 02218 class. 02219 02220 There are several macros for error handling defined in \ref 02221 err_hnd.h, and several for vector/matrix arithmetic in \ref 02222 vec_arith.h . 02223 02224 There is a define constant O2SCL_NO_SYSTEM_FUNC which permanently 02225 disables the shell command <tt>'!'</tt> in \ref cli (when the 02226 constant is defined, the shell command doesn't work even if 02227 \ref cli::shell_cmd_allowed is <tt>true</tt>). 02228 02229 The constant O2SCL_DATA_DIR is defined internally to provide 02230 the directory which contains the \o2 data files. After installation, 02231 this can be accessed in \ref lib_settings. 02232 02233 All of the header files have their own define constant of 02234 the form <tt>O2SCL_HEADER_FILE_NAME</tt> which ensures that 02235 the header file is only included once. 02236 02237 Finally, I sometimes comment out sections of code with 02238 \code 02239 #ifdef O2SCL_NEVER_DEFINED 02240 ... 02241 #endif 02242 \endcode 02243 This constant should not be defined by the user as it will cause 02244 compilation to fail. 02245 02246 \comment 02247 These are makefile constants not source code define constants 02248 02249 The two define constants O2SCL_PARTLIB and O2SCL_EOSLIB are used 02250 internally to control which sublibraries are compiled together 02251 with the main library (see \ref install_section ). The end-user 02252 shouldn't have to worry about these. 02253 \endcomment 02254 02255 \subsection paramorder_subsection Parameter ordering 02256 02257 In functions where this makes sense, generally input parameters 02258 will appear first, while output parameters or parameters which 02259 handle both input and output will appear later. 02260 02261 \subsection global_subsect Global objects 02262 02263 There are four global objects that are created in 02264 libo2scl: 02265 - \ref def_err_hnd is the default error handler 02266 - \ref alt_err_hnd is the GSL-like error handler 02267 - \ref err_hnd is the pointer to the error handler (points to 02268 def_err_hnd by default) 02269 - \ref lib_settings to control a few library settings 02270 02271 All other global objects are to be avoided. 02272 02273 \subsection thread_subsect Thread safety 02274 02275 Most of the classes are thread-safe, meaning that two instances of 02276 the same class will not clash if their methods are called 02277 concurrently since static variables are only used for compile-time 02278 constants. However, two threads cannot, in general, safely access 02279 the same instance of a class. In this respect, \o2 is no 02280 different from GSL. 02281 02282 \subsection docdesign_subsect Documentation design 02283 02284 The commands \\comment and \\endcomment delineate comments about 02285 the documentation that are present in the header files but don't 02286 ever show up in the HTML or LaTeX documentation. 02287 02288 \subsection crightfoo_subsect Copyright notices 02289 02290 For files where it is appropriate to do so, I have followed the 02291 prescription suggested in 02292 http://lists.gnu.org/archive/html/help-gsl/2008-11/msg00017.html 02293 retaining the GSL copyright notices and putting the \o2 notices at 02294 the top. CERNLIB has no such standard, but their licensing information 02295 is outlined at 02296 http://cernlib.web.cern.ch/cernlib/conditions.html . 02297 02298 \subsection futurework_subsect Design plans 02299 02300 <b>Boost and linear algebra:</b> \n I would like to ensure this 02301 class is compatible with boost, and start integrating things 02302 accordingly. IMHO object-oriented linear algebra is in a rather 02303 sad state at the moment. uBlas and MTL are both promising, 02304 however, and I'd like to start implementing some sort of 02305 compatibility with uBlas vectors and matrices soon. The uBlas 02306 documentation is pretty sparse, but that's the pot calling the 02307 kettle a cheap piece of metal. 02308 02309 <b>Other Improvements:</b> \n I'm particularly interested in 02310 improving the ODE and fitting classes, as well as updating the 02311 BFGS2 minimizer. Of course, more examples and better documentation 02312 are also a must. 02313 02314 <b>Algorithms to include</b> 02315 - Method of lines for PDEs 02316 - Some of the MESA interpolation routines. 02317 - C++ translation of MINUIT (done already by ROOT, but quite difficult). 02318 - Creating closed regions from contour lines (I have no idea how to 02319 do this at the moment, though I'm sure someone has solved this 02320 problem already somewhere.) 02321 02322 <b>Complex numbers</b> \n I'm not sure where to go with complex 02323 numbers. My guess is that <tt>std::complex</tt> is not 02324 significantly slower (or is faster) than <tt>gsl_complex</tt>, but 02325 it would be good to check this. Then there's the C99 standard, 02326 which is altogether different. Unfortunately the interfaces may be 02327 sufficiently different that it's impossible to make templated 02328 classes which operate on generic complex number types. 02329 02330 <b>I/O</b> \n The I/O classes are (admittedly) not structured very 02331 well, and there are a lot of things which could be done there. 02332 There are a lot of alternative solutions out there, but most of 02333 them work on binary file formats (which I find difficult to use). 02334 - On a shorter time scale I'd like to replace the inner workings 02335 of the \ref collection class with a mechanism using 02336 <tt>boost::any</tt>, which will avoid the silly <tt>void *</tt>s 02337 all over the place. This is already in progress. 02338 - On a longer time scale, I'd like to replace the file format I/O 02339 classes with something using Boost pipes. 02340 02341 \hline 02342 \section license_section License Information 02343 02344 \o2 (as well as CERNLIB and the Gnu Scientific Library (GSL)) is 02345 licensed under version 3 of the GPL as provided in the files \c 02346 COPYING and in \c doc/o2scl/extras/gpl_license.txt. After 02347 installation, it is included in the documentation in \c 02348 PREFIX/doc/extras/gpl_license.txt where the default \c PREFIX is 02349 \c /usr/local. 02350 02351 \verbinclude gpl_license.txt 02352 02353 This documentation is provided under the GNU Free Documentation 02354 License, as given below and provided in \c 02355 doc/o2scl/extras/fdl_license.txt. After installation, it is included 02356 in the documentation in \c PREFIX/doc/extras/fdl_license.txt where 02357 the default \c PREFIX is \c /usr/local. 02358 02359 \verbinclude fdl_license.txt 02360 02361 \hline 02362 \section ack_section Acknowledgements 02363 02364 I would like to thank the creators of GSL and Doxygen for their 02365 excellent work! Thanks also to Julien Garaud for contributing the 02366 ODE multishooting class and for the <tt>ex_hydrogen</tt> example. 02367 02368 \hline 02369 \section ref_section Bibliography 02370 02371 Some of the references which contain links should direct you to 02372 the work referred to using its DOI identifer. 02373 02374 \anchor Bader83 Bader83: 02375 G. Bader and P. Deuflhard, Numer. Math. \b 41 (1983) 373. 02376 02377 \anchor Bus75 Bus75: 02378 \htmlonly 02379 <a href="http://dx.doi.org/10.1145/355656.355659"> 02380 J. C. P. Bus and T. J. Dekker</a>, 02381 \endhtmlonly 02382 \latexonly 02383 \href{http://dx.doi.org/10.1145/355656.355659}{ 02384 J.~C.~P. Bus and T.~J. Dekker}, 02385 \endlatexonly 02386 ACM Trans. Math. Soft. \b 1 (1975) 330. 02387 02388 \anchor Cash90 Cash90: 02389 \htmlonly 02390 <a href="http://dx.doi.org/10.1145/79505.79507"> 02391 J. R. Cash and A. H. Karp</a>, 02392 \endhtmlonly 02393 \latexonly 02394 \href{http://dx.doi.org/10.1145/79505.79507}{ 02395 J.~R. Cash and A.~H. Karp}, 02396 \endlatexonly 02397 ACM Trans. Math. Soft. \b 16 (1990) 201. 02398 02399 \anchor EngelnMullges96 EngelnMullges96: 02400 \htmlonly 02401 G. Engeln-Mullges and F. Uhlig, 02402 \endhtmlonly 02403 \latexonly 02404 G. Engeln-M\"{u}llges and F. Uhlig, 02405 \endlatexonly 02406 Numerical Algorithms in C (1996) Springer, p. 96. 02407 02408 \anchor Fletcher87 Fletcher87: 02409 R. Fletcher, Practical methods of optimization (John Wiley & Sons, 02410 Chichester 1987) p. 39. 02411 02412 \anchor Garbow80 Garbow80: 02413 B. S. Garbow, K. E. Hillstrom, and J. J. More, MINPACK project, 02414 Argonne Nat'l Lab, March 1980. 02415 02416 \anchor Hairer00 Hairer00: 02417 Hairer, E., Norsett S.P., Wanner, G. Solving ordinary 02418 differential equations I, Nonstiff Problems, 2nd revised edition, 02419 Springer, 2000. 02420 02421 \anchor Krabs83 Krabs83: 02422 W. Krabs, Einfuhrung in die lieare und nictlineare Optimierung 02423 fur Ingenieure (BSB B.G. Teubner, Leipzig 1983) p. 84. 02424 02425 \anchor Lepage78 Lepage78: 02426 \htmlonly 02427 <a href="http://dx.doi.org/10.1016/0021-9991(78)90004-9"> 02428 G. P. Lepage</a>, 02429 \endhtmlonly 02430 \latexonly 02431 \href{http://dx.doi.org/10.1016/0021-9991(78)90004-9}{ 02432 G.~P. Lepage}, 02433 \endlatexonly 02434 J. Comp. Phys. \b 27 (1978) 192. 02435 02436 \anchor Lewin83 Lewin83: 02437 L. Lewin, Polylogarithms and Associated Functions (North-Holland, 02438 New York, 1983). 02439 02440 \anchor Longman58 Longman58: 02441 I.M. Longman, MTAC (later renamed Math. Comp.) \b 12 (1958) 205. 02442 02443 \anchor More79 More79: 02444 J.J. More' and M.Y. Cosnard, ACM Trans. Math. Software, 02445 \b 5 (1979) 64-85. 02446 02447 \anchor More80 More80: 02448 J.J. More' and M.Y. Cosnard, Algoright 554 BRENTM, 02449 Collected Algorithms from CACM (1980). 02450 02451 \anchor Nelder65 Nelder65: 02452 Nelder, J.A., Mead, R., Computer Journal 7 (1965) pp. 308-313. 02453 02454 \anchor Press90 Press90: 02455 W.H. Press, G.R. Farrar, "Recursive Stratified Sampling for 02456 Multidimensional Monte Carlo Integration", Computers in Physics, 02457 v4 (1990), pp. 190-195. 02458 02459 \anchor Prince81 Prince81: 02460 P.J. Prince and J.R. Dormand J. Comp. Appl. Math., 7 (1981) 67. 02461 02462 \anchor Rutishauser63 Rutishauser63: 02463 H. Rutishauser, Ausdehnung des Rombergschen Prinzips 02464 (Extension of Romberg's Principle), Numer. Math. \b 5 (1963) 48-54. 02465 02466 */ 02467 /* 02468 --------- 02469 This section has been removed from the documentation since the 02470 vector classes have been updated. 02471 --------- 02472 02473 \page cvn_page Notes on const vectors 02474 02475 The code 02476 02477 \code 02478 const ovector x; 02479 //ovector_const_base &cb=x; 02480 \endcode 02481 02482 doesn't complile, which is a bit weird (you have to use a 02483 const ovector_const_base reference instead). 02484 02485 Also, ovector_base has a function like 02486 02487 \code 02488 double &operator[](size_t i) 02489 \endcode 02490 02491 which in principle could be actually const, i.e. 02492 02493 \code 02494 double &operator[](size_t i) const 02495 \endcode 02496 02497 but isn't. Also annoying is that "const ovector_base &x" is not a 02498 perfectly generic base, since it's not a base for 02499 "ovector_const_base &y" or "const ovector_const_base &y2" (last one 02500 I'm not sure about). I had thought about making ovector_const_base a 02501 child of ovector_base instead, but that means that the interpolation 02502 routines which have ovector_const_base as a default template 02503 parameter will have to be changed. (Is this a problem?) Even worse, 02504 ovector_const_base classes could be upcasted easily to ovector_base 02505 removing const correctness. 02506 02507 Finally, the meaning of "const ovector_view" vs. "ovector_view" is 02508 kind of confusing, though maybe we just have to explain to the 02509 user that "const" means const where-ever it appears. 02510 02511 Happily, this new branch removes the need for "ovector_view_assign", 02512 in the trunk which was kind of frustrating. 02513 02514 Probably the best new solution is to rework the hierarchy altogether 02515 and admit that ovector and ovector_view aren't really related 02516 objects. There is no such thing as a generic base for both ovector 02517 and ovector_view. This of course might require a redesign of the 02518 solver classes, for example, as they treat these two classes as 02519 necessarily related (alloc_vec_t is supposed to be related to 02520 vec_t). Maybe not though, I need to think about this more. 02521 02522 */ 02523 /** 02524 \page dl_page Download O2scl 02525 02526 The current version is 0.905. The source distribution can 02527 be obtained from \n 02528 - \c http://sourceforge.net/project/showfiles.php?group_id=206918 02529 02530 You may also download \o2 from version from the Subversion 02531 repository. To obtain the bleeding-edge developer version, use 02532 something like 02533 \verbatim 02534 svn co https://o2scl.svn.sourceforge.net/svnroot/o2scl/trunk o2scl 02535 \endverbatim 02536 The checkout process is a bit more time consuming than directly 02537 downloading the source distribution. 02538 02539 Version 0.905 corresponds with version 48 in the svn repository. 02540 02541 Version 0.904 corresponds with version 40 in the svn repository. 02542 02543 Version 0.903 does not exist (this number was skipped to help 02544 coordinate numbering with \o2x). 02545 02546 Version 0.902 corresponds with version 37 in the svn respository. 02547 02548 Version 0.901 corresponds with version 31 in the svn respository. 02549 02550 Version 0.9 corresponds with version 26 in the svn respository. 02551 02552 Version 0.806 was a quick release to fix some issues with 02553 compilations in Mac OS X and does not correspond exactly 02554 with a version in the repository. 02555 02556 Version 0.805 corresponds with version 16 in the svn respository. 02557 02558 */ 02559 /* 02560 \htmlonly 02561 <table border=0> 02562 <tr><td>Release version number</td><td>SVN repository number</td></tr> 02563 <tr><td>0.901</td><td>31</td></tr> 02564 <tr><td>0.9</td><td>26</td></tr> 02565 <tr><td>0.806</td><td>none</td></tr> 02566 <tr><td>0.805</td><td>16</td></tr> 02567 </table> 02568 \endhtmlonly 02569 02570 */ 02571 /** 02572 \brief An empty class to add some items to the todo and bug lists 02573 02574 \future 02575 - Make sure we have a uvector_cx_alloc, 02576 ovector_cx_const_reverse, ovector_cx_const_subvector_reverse, 02577 uvector_reverse, uvector_const_reverse, uvector_subvector_reverse, 02578 uvector_const_subvector_reverse, omatrix_cx_diag, blah_const_diag, 02579 umatrix_diag, and umatrix_cx_diag 02580 - ovector_cx_view::operator=(uvector_cx_view &) is missing 02581 - ovector_cx::operator=(uvector_cx_view &) is missing 02582 - uvector_c_view::operator+=(complex) is missing 02583 - uvector_c_view::operator-=(complex) is missing 02584 - uvector_c_view::operator*=(complex) is missing 02585 02586 \future Currently, I believe the testing code requires the 02587 shared libraries and may not work if the static libraries 02588 only are installed. It would be nice to ensure the tests 02589 could be complied in either case. 02590 02591 \future Consider breaking documentation up into sections? 02592 02593 */ 02594 class other_todos_and_bugs { 02595 } 02596
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