Object-oriented Scientific Computing Library: Version 0.910
General Usage

Namespaces

Most of the classes reside in the namespace o2scl (this namespace has been removed from the documentation for clarity). Numerical constants (many of them based on the GSL constants) are placed in separate namespaces (gsl_cgs, gsl_cgsm, gsl_mks, gsl_mksa, gsl_num, o2scl_const, and o2scl_fm). There are also two namespaces which hold integration coefficients, o2scl_inte_gk_coeffs and o2scl_inte_qng_coeffs. There are also some namespaces for the linear algebra functions, see Linear Algebra for more information.

Documentation conventions

In the following documentation, function parameters are denoted by parameter, except when used in mathematical formulas as in $ \mathrm{variable} $ .

Nomenclature

Classes directly derived from the GNU Scientific Library are preceeded by the prefix gsl_ and classes derived from CERNLIB are preceeded by the prefix cern_. Some of those classes derived from GSL and CERNLIB operate slightly differently from the original versions. The differences are detailed in the corresponding class documentation.

Basic error handling

Error handling is a hybrid approach combining GSL with C++ exceptions. An abstract type has been defined which operates as a GSL-like error hander. The default error handler is a implementation of this abstract type which throws a C++ exception when an error is encountered. The various exceptions, and their correspondence with the GSL error codes, are given in the GSL error codes and C++ exception types section. By default in O2scl , the default GSL error handler is replaced with the O2scl default error handler, i.e. GSL functions will throw C++ exceptions.

Errors can be set by the user through the macros O2SCL_ERR, which sets an error, and O2SCL_ERR_RET, which sets an error and returns the error number.

The error handler, err_hnd is a global pointer to an object of type err_hnd_type. There is a global default error handler, def_err_hnd, of type err_hnd_cpp, which throws C++ exceptions, and an alternate default error handler, alt_err_hnd, of type err_hnd_gsl, which outputs an error message and aborts execution.

Generally, functions also follow the GSL-like behavior of calling a GSL-like error handler and (when appropriate) return a non-zero value. When functions succeed they return gsl_success (zero). O2scl functions never reset the error handler. Also, object destructors do not generally call the error handler. Internally, O2scl does not use try blocks, but these can easily be effectively employed by an O2scl user.

The list of GSL error codes (including a few extra ones for O2scl ) is given in the documentation for the file err_hnd.h. The default error handler can be replaced by simply assigning the address of a descendant of err_hnd_type to err_hnd.

Functionality similar to assert() is provided with the macro O2SCL_ASSERT, which exits if its argument is non-zero, and O2SCL_BOOL_ASSERT which exits if its argument is false.

One can instruct the library to use the GSL-like O2scl error handler alt_err_hnd by default, by defining the constant O2SCL_USE_GSL_HANDLER. This is also useful if one wants to compile without C++ exceptions (which does have a small overhead).

What is an error?

O2scl assumes that errors are events which should happen infrequently. Error handling strategies are often time-consuming and they are not a replacement for normal code flow. However, even with this in mind, one can still distinguish a large spectrum of posibillities from "fatal" errors, those likely to corrupt the stack and/or cause a dreaded "segmentation fault" and "non-fatal" errors, those errors which might cause incorrect results, but might be somehow recoverable. One of the purposes of error handling is to decide if and how these different types of errors should be handled differently.

Sometimes, it is undesirable to abort execution upon a failure to reach numerical convergence. While these failures are treated as errors (and by default an exception is thrown), some of the classes which attempt to reach numerical convergence have an option (e.g. mroot::err_nonconv) to turn this default behavior off for these convergence errors. To set these "convergence" errors in code provided by the user, the macros O2SCL_CONV and O2SCL_CONV_RET can be used.

Of course, the standard try, catch mechanism of error handling may also be used for finer-grained control.

Another related issue is that O2scl often calls functions which are supplied by the user, these user-designed functions may create errors, and the library needs to decide how to deal with them, even though it knows little about what is actually happening inside these user-defined functions. Most of the time, O2scl assumes that if a function returns a nonzero value, then an error has occured and the present calculation should abort.

GSL error codes and C++ exception types

See also the description of the error codes in err_hnd.h .

gsl_success=0, (no error thrown)
gsl_failure=-1, exc_exception
gsl_continue=-2, (no error thrown)
gsl_edom=1, exc_range_error
gsl_erange=2, exc_range_error
gsl_efault=3, exc_runtime_error
gsl_einval=4, exc_invalid_argument
gsl_efailed=5, exc_exception
gsl_efactor=6, exc_runtime_error
gsl_esanity=7, exc_exception
gsl_enomem=8, exc_runtime_error
gsl_ebadfunc=9, exc_runtime_error
gsl_erunaway=10, exc_runtime_error
gsl_emaxiter=11, exc_runtime_error
gsl_ezerodiv=12, exc_overflow_error
gsl_ebadtol=13, exc_invalid_argument
gsl_etol=14, exc_runtime_error
gsl_eundrflw=15, exc_range_error
gsl_eovrflw=16, exc_overflow_error
gsl_eloss=17, exc_runtime_error
gsl_eround=18, exc_runtime_error
gsl_ebadlen=19, exc_invalid_argument
gsl_enotsqr=20, exc_invalid_argument
gsl_esing=21, exc_runtime_error
gsl_ediverge=22, exc_runtime_error
gsl_eunsup=23, exc_exception
gsl_eunimpl=24, exc_exception
gsl_ecache=25, exc_runtime_error
gsl_etable=26, exc_runtime_error
gsl_enoprog=27, exc_runtime_error
gsl_enoprogj=28, exc_runtime_error
gsl_etolf=29, exc_runtime_error
gsl_etolx=30, exc_runtime_error
gsl_etolg=31, exc_runtime_error
gsl_eof=32, exc_ios_failure
gsl_enotfound=33, exc_runtime_error
gsl_ememtype=34, exc_logic_error
gsl_efilenotfound=35, exc_ios_failure
gsl_eindex=36, exc_invalid_argument
gsl_outsidecons=37, exc_runtime_error

Objects and scope

O2scl objects frequently take inputs which are of the form of a reference to a smaller object. This is particularly convenient because it allows a lot of flexibility, while providing a certain degree of safety. In many cases, the user retains the responsibility of ensuring that input objects do not go out of scope before they are utilized by objects which require them. This is actually no different than the requirements on the user imposed by GSL, for example.

A simple example of this is provided by the multi-dimensional integrator composite_inte. It works by combining several one-dimensional integrators to integrate over a multi-dimensional hybercube. If the specified one-dimensional integrator goes out of scope an integration is attempted, the integration will fail, for example,

// How not to provide subobjects to O2scl classes

void set_integrator(multi_inte<int> &mi) {
  gsl_inte_qag<size_t> one_dim_it[2];
  mi.set_oned_inte(one_dim_it[0],0);
  mi.set_oned_inte(one_dim_it[1],1);
}

void function() {
  composite_inte<int> cit;
  set_integrator(cit);
  cit.minteg_err(func,2,a,b,pa,res,err);
}

This will fail because the one-dimensional integration objects go out of scope (it's a local variable in the function and its destructor is called before the set_integrator() function exits) before the minteg_err() function is called.

In C++, this difficulty can be solved by using shared pointers, which ensure that an object is deleted only when it has no more references which are pointing to it. While shared pointer objects are part of the new TR1 standard, not all compilers implement this standard yet. O2scl defines a template struct o2_shared_ptr, which provides the user a consistent interface to a working shared pointer type, o2_shared_ptr<T>::type (located in the o2scl namespace). If TR1 is not available, then one can compile O2scl with O2SCL_NO_TR1_MEMORY. In this case, if O2SCL_HAVE_BOOST is defined, then the boost shared pointer type is used, and otherwise an internal O2scl shared pointer template named o2_int_shared_ptr is used . See the documentation for o2_shared_ptr for more details.

Reference parameters

When a O2scl function contains two reference parameters for objects, it is not typically possible to provide the same object to both parameters or to provide two objects which share the same memory. This is particularly an issue when the associated types are template types, since then the O2scl library has no way of knowing how memory is organized in these unspecified types.

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Documentation generated with Doxygen. Provided under the GNU Free Documentation License (see License Information).

Get Object-oriented Scientific Computing
Lib at SourceForge.net. Fast, secure and Free Open Source software
downloads.