Conceptual Requirements for Real Number Types

The functions and statistical distributions in this library can be used with any type RealType that meets the conceptual requirements given below. All the built-in floating-point types like double will meet these requirements. (Built-in types are also called fundamental (built-in) types).

User-defined types that meet the conceptual requirements can also be used. For example, with a thin wrapper class one of the types provided with NTL (RR) can be used. But now that Boost.Multiprecision library is available, this has become the preferred real-number type, typically cpp_dec_float or cpp_bin_float.

Submissions of binding to other extended precision types would also still be welcome.

The guiding principal behind these requirements is that a RealType behaves just like a built-in floating-point type.

Basic Arithmetic Requirements

These requirements are common to all of the functions in this library.

In the following table r is an object of type RealType, cr and cr2 are objects of type const RealType, and ca is an object of type const arithmetic-type (arithmetic types include all the built in integers and floating point types).

Expression	Result Type	Notes
`RealType(cr)`	RealType	RealType is copy constructible.
`RealType(ca)`	RealType	RealType is copy constructible from the arithmetic types.
`r = cr`	RealType&	Assignment operator.
`r = ca`	RealType&	Assignment operator from the arithmetic types.
`r += cr`	RealType&	Adds cr to r.
`r += ca`	RealType&	Adds ar to r.
`r -= cr`	RealType&	Subtracts cr from r.
`r -= ca`	RealType&	Subtracts ca from r.
`r *= cr`	RealType&	Multiplies r by cr.
`r *= ca`	RealType&	Multiplies r by ca.
`r /= cr`	RealType&	Divides r by cr.
`r /= ca`	RealType&	Divides r by ca.
`-r`	RealType	Unary Negation.
`+r`	RealType&	Identity Operation.
`cr + cr2`	RealType	Binary Addition
`cr + ca`	RealType	Binary Addition
`ca + cr`	RealType	Binary Addition
`cr - cr2`	RealType	Binary Subtraction
`cr - ca`	RealType	Binary Subtraction
`ca - cr`	RealType	Binary Subtraction
`cr * cr2`	RealType	Binary Multiplication
`cr * ca`	RealType	Binary Multiplication
`ca * cr`	RealType	Binary Multiplication
`cr / cr2`	RealType	Binary Subtraction
`cr / ca`	RealType	Binary Subtraction
`ca / cr`	RealType	Binary Subtraction
`cr == cr2`	bool	Equality Comparison
`cr == ca`	bool	Equality Comparison
`ca == cr`	bool	Equality Comparison
`cr != cr2`	bool	Inequality Comparison
`cr != ca`	bool	Inequality Comparison
`ca != cr`	bool	Inequality Comparison
`cr <= cr2`	bool	Less than equal to.
`cr <= ca`	bool	Less than equal to.
`ca <= cr`	bool	Less than equal to.
`cr >= cr2`	bool	Greater than equal to.
`cr >= ca`	bool	Greater than equal to.
`ca >= cr`	bool	Greater than equal to.
`cr < cr2`	bool	Less than comparison.
`cr < ca`	bool	Less than comparison.
`ca < cr`	bool	Less than comparison.
`cr > cr2`	bool	Greater than comparison.
`cr > ca`	bool	Greater than comparison.
`ca > cr`	bool	Greater than comparison.
`boost::math::tools::digits<RealType>()`	int	The number of digits in the significand of RealType.
`boost::math::tools::max_value<RealType>()`	RealType	The largest representable number by type RealType.
`boost::math::tools::min_value<RealType>()`	RealType	The smallest representable number by type RealType.
`boost::math::tools::log_max_value<RealType>()`	RealType	The natural logarithm of the largest representable number by type RealType.
`boost::math::tools::log_min_value<RealType>()`	RealType	The natural logarithm of the smallest representable number by type RealType.
`boost::math::tools::epsilon<RealType>()`	RealType	The machine epsilon of RealType.

Note that:

The functions log_max_value and log_min_value can be synthesised from the others, and so no explicit specialisation is required.
The function epsilon can be synthesised from the others, so no explicit specialisation is required provided the precision of RealType does not vary at runtime (see the header boost/math/bindings/rr.hpp for an example where the precision does vary at runtime).
The functions digits, max_value and min_value, all get synthesised automatically from std::numeric_limits. However, if numeric_limits is not specialised for type RealType, then you will get a compiler error when code tries to use these functions, unless you explicitly specialise them. For example if the precision of RealType varies at runtime, then numeric_limits support may not be appropriate, see boost/math/bindings/rr.hpp for examples.

Warning

	Warning
If `std::numeric_limits<>` is not specialized for type RealType then the default float precision of 6 decimal digits will be used by other Boost programs including: Boost.Test: giving misleading error messages like "difference between {9.79796} and {9.79796} exceeds 5.42101e-19%". Boost.LexicalCast and Boost.Serialization when converting the number to a string, causing potentially serious loss of accuracy on output. Although it might seem obvious that RealType should require `std::numeric_limits` to be specialized, this is not sensible for `NTL::RR` and similar classes where the number of digits is a runtime parameter (whereas for `numeric_limits` everything has to be fixed at compile time).

If std::numeric_limits<> is not specialized for type RealType then the default float precision of 6 decimal digits will be used by other Boost programs including:

Boost.Test: giving misleading error messages like

"difference between {9.79796} and {9.79796} exceeds 5.42101e-19%".

Boost.LexicalCast and Boost.Serialization when converting the number to a string, causing potentially serious loss of accuracy on output.

Although it might seem obvious that RealType should require std::numeric_limits to be specialized, this is not sensible for NTL::RR and similar classes where the number of digits is a runtime parameter (whereas for numeric_limits everything has to be fixed at compile time).

Standard Library Support Requirements

Many (though not all) of the functions in this library make calls to standard library functions, the following table summarises the requirements. Note that most of the functions in this library will only call a small subset of the functions listed here, so if in doubt whether a user-defined type has enough standard library support to be useable the best advise is to try it and see!

In the following table r is an object of type RealType, cr1 and cr2 are objects of type const RealType, and i is an object of type int.

Expression	Result Type
`fabs(cr1)`	RealType
`abs(cr1)`	RealType
`ceil(cr1)`	RealType
`floor(cr1)`	RealType
`exp(cr1)`	RealType
`pow(cr1, cr2)`	RealType
`sqrt(cr1)`	RealType
`log(cr1)`	RealType
`frexp(cr1, &i)`	RealType
`ldexp(cr1, i)`	RealType
`cos(cr1)`	RealType
`sin(cr1)`	RealType
`asin(cr1)`	RealType
`tan(cr1)`	RealType
`atan(cr1)`	RealType
`fmod(cr1)`	RealType
`round(cr1)`	RealType
`iround(cr1)`	int
`trunc(cr1)`	RealType
`itrunc(cr1)`	int

Note that the table above lists only those standard library functions known to be used (or likely to be used in the near future) by this library. The following functions: acos, atan2, fmod, cosh, sinh, tanh, log10, lround, llround, ltrunc, lltrunc and modf are not currently used, but may be if further special functions are added.

Note that the round, trunc and modf functions are not part of the current C++ standard: they are part of the additions added to C99 which will likely be in the next C++ standard. There are Boost versions of these provided as a backup, and the functions are always called unqualified so that argument-dependent-lookup can take place.

In addition, for efficient and accurate results, a Lanczos approximation is highly desirable. You may be able to adapt an existing approximation from boost/math/special_functions/lanczos.hpp or boost/math/bindings/detail/big_lanczos.hpp: in the former case you will need change static_cast's to lexical_cast's, and the constants to strings (in order to ensure the coefficients aren't truncated to long double) and then specialise lanczos_traits for type T. Otherwise you may have to hack libs/math/tools/lanczos_generator.cpp to find a suitable approximation for your RealType. The code will still compile if you don't do this, but both accuracy and efficiency will be greatly compromised in any function that makes use of the gamma/beta/erf family of functions.