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