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