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