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