Most of the classes reside in the namespace o2scl
. Numerical constants (many of them based on the GSL constants) are placed in separate namespaces (o2scl_cgs, o2scl_cgsm, o2scl_mks, o2scl_mksa, and o2scl_const). The O2scl functions and classes for HDF5 output are in the o2scl_hdf namespace. 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 on these.
In the following documentation, function parameters are denoted by parameter
, except when used in mathematical formulas as in .
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 calls the O2scl error handler. The error handler, o2scl::err_hnd is a global pointer to an object of type o2scl::err_hnd_type. There is a global default error handler, o2scl::def_err_hnd, of type o2scl::err_hnd_cpp, which throws C++ exceptions, and an alternate default error handler, o2scl::alt_err_hnd, of type o2scl::err_hnd_gsl, which outputs an error message and aborts execution. The global error handler can be replaced by simply assigning the address of a descendant of o2scl::err_hnd_type to o2scl::err_hnd.
O2scl does not support any execution beyond the point at which the error handler is called. Many functions which would have had integer return values in GSL, now return void
in O2scl . Object destructors almost never call the error handler. Internally, O2scl does not use try
blocks, but these can easily be effectively employed by an O2scl user.
The C++ exception classes are also mapped to the list of GSL error codes (including a few extra ones for O2scl ), which is given in the documentation for the file err_hnd.h and in GSL error codes and C++ exception types below.
One can instruct the library to use the GSL-like O2scl error handler o2scl::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).
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. o2scl::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. Functions which may have convergence errors sometimes return int
, to indicate which convergence error was returned when the value of err_nonconv
has been set to false.
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. For this reason, O2scl does not typically try to handle any exceptions or errors occuring in user-specified functions.
See also the description of the error codes in err_hnd.h .
o2scl::success=0, (no error thrown)
o2scl::gsl_failure=-1, o2scl::exc_exception
o2scl::gsl_continue=-2, (no error thrown)
o2scl::exc_edom=1, o2scl::exc_range_error
o2scl::exc_erange=2, o2scl::exc_range_error
o2scl::exc_efault=3, o2scl::exc_runtime_error
o2scl::exc_einval=4, o2scl::exc_invalid_argument
o2scl::exc_efailed=5, o2scl::exc_exception
o2scl::exc_efactor=6, o2scl::exc_runtime_error
o2scl::exc_esanity=7, o2scl::exc_exception
o2scl::exc_enomem=8, o2scl::exc_runtime_error
o2scl::exc_ebadfunc=9, o2scl::exc_runtime_error
o2scl::exc_erunaway=10, o2scl::exc_runtime_error
o2scl::exc_emaxiter=11, o2scl::exc_runtime_error
o2scl::exc_ezerodiv=12, o2scl::exc_overflow_error
o2scl::exc_ebadtol=13, o2scl::exc_invalid_argument
o2scl::exc_etol=14, o2scl::exc_runtime_error
o2scl::exc_eundrflw=15, o2scl::exc_range_error
o2scl::exc_eovrflw=16, o2scl::exc_overflow_error
o2scl::exc_eloss=17, o2scl::exc_runtime_error
o2scl::exc_eround=18, o2scl::exc_runtime_error
o2scl::exc_ebadlen=19, o2scl::exc_invalid_argument
o2scl::exc_enotsqr=20, o2scl::exc_invalid_argument
o2scl::exc_esing=21, o2scl::exc_runtime_error
o2scl::exc_ediverge=22, o2scl::exc_runtime_error
o2scl::exc_eunsup=23, o2scl::exc_exception
o2scl::exc_eunimpl=24, o2scl::exc_exception
o2scl::exc_ecache=25, o2scl::exc_runtime_error
o2scl::exc_etable=26, o2scl::exc_runtime_error
o2scl::exc_enoprog=27, o2scl::exc_runtime_error
o2scl::exc_enoprogj=28, o2scl::exc_runtime_error
o2scl::exc_etolf=29, o2scl::exc_runtime_error
o2scl::exc_etolx=30, o2scl::exc_runtime_error
o2scl::exc_etolg=31, o2scl::exc_runtime_error
o2scl::exc_eof=32, o2scl::exc_ios_failure
o2scl::exc_enotfound=33, o2scl::exc_runtime_error
o2scl::exc_ememtype=34, o2scl::exc_logic_error
o2scl::exc_efilenotfound=35, o2scl::exc_ios_failure
o2scl::exc_eindex=36, o2scl::exc_invalid_argument
o2scl::exc_outsidecons=37, o2scl::exc_runtime_error
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.
Member functions which store pointers to user-specified objects should warn that they are doing so in the documentation for the class.
For example, say that a user wants to solve several equations using a o2scl::mroot_hybrids object and use the functions o2scl::mroot_hybrids::set() and o2scl::mroot_hybrids::iterate(). Since the function is specified by the call to set()
, it is important that this function object does not go out of scope before the call to iterate()
occurs.
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. Thread safety is also an issue, as care must be taken if two functions which are running simultaneously access the same instance of any class.
Various define constants used in O2scl are listed below. Note that, if acol
is installed, acol -v
reports several details about how O2scl was compiled.
acol -v
reports whether or not Armadillo support was enabled during compilation.src/linalg
directory to select between o2scl_cblas and o2scl_cblas_bracket . The end-user should not need to use this.acol -v
. In a typical installation, the end-user should not need to use this.acol -v
reports whether or not Eigen support was enabled during compilation.acol
is to be compiled. This is set by default unless the configure script is specified with –disable-acol
.–with-fast-test
option in homebrew.–enable-gsl2
is passed to the configure script. The command acol -v
reports on whether or not GSL V2.0+ support was enabled during installation.acol -v
reports whether or not HDF5 compression support was enabled during compilation.configure
script.src/base/exception.cpp
. This is useful, for example, with the g++
flag -fno-exceptions
.mcmc_para_ts
.–enable-openmp
is passed to the configure script. The end-user must also define this flag to enable OpenMP support in their code. While all current OpenMP functionality in O2scl is header only, this may change in the future. The command acol -v
reports on whether or not OpenMP was enabled during installation.–disable-partlib
is specified. End-user code which uses O2scl_part should not need to define this.acol
. The end-user should not need to use this.#include <hdf5.h>
independent of the automatically determined operating system type.src/base/exception.cpp
. Documentation generated with Doxygen. Provided under the
GNU Free Documentation License (see License Information).