Repository files navigation

GCE-Math (GeneralizedConstantExpression Math) is a templated C++ library enabling compile-time computation of mathematical functions.

Features:

• The library is written in C++11constexpr format, and is C++11/14/17/20 compatible.
• Continued fraction expansions and series expansions are implemented using recursive templates.
• Thegcem:: syntax is identical to that of the C++ standard library (std::).
• Tested and accurate to floating-point precision against the C++ standard library.
• Released under a permissive, non-GPL license.

Author: Keith O'Hara

• Status and Documentation
• Installation
• Test Suite
• Jupyter Notebook
• General Syntax
• Examples

The library is actively maintained and is still being extended. A list of features includes:

• Basic library functions:
  • abs,max,min,pow,sqrt,inv_sqrt,
  • ceil,floor,round,trunc,fmod,
  • exp,expm1,log,log1p,log2,log10, and more
• Trigonometric functions:
  • basic:cos,sin,tan
  • inverse:acos,asin,atan,atan2
• Hyperbolic (area) functions:
  • cosh,sinh,tanh,acosh,asinh,atanh
• Algorithms:
  • gcd,lcm
• Special functions:
  • factorials and the binomial coefficient:factorial,binomial_coef
  • beta, gamma, and multivariate gamma functions:beta,lbeta,lgamma,tgamma,lmgamma
  • the Gaussian error function and inverse error function:erf,erf_inv
  • (regularized) incomplete beta and incomplete gamma functions:incomplete_beta,incomplete_gamma
  • inverse incomplete beta and incomplete gamma functions:incomplete_beta_inv,incomplete_gamma_inv

Full documentation is available online:

A PDF version of the documentation is availablehere.

GCE-Math is a header-only library and does not require any additional libraries or utilities (beyond a C++11 compatible compiler). Simply add the header files to your project using:

#include"gcem.hpp"

You can install GCE-Math using the Conda package manager.

conda install -c conda-forge gcem

You can also install the library from source using CMake.

# clone gcem from GitHubgit clone https://github.com/kthohr/gcem ./gcem# make a build directorycd ./gcemmkdir buildcd build# generate Makefiles and installcmake .. -DCMAKE_INSTALL_PREFIX=/gcem/install/locationmake install

For example,/gcem/install/location could be/usr/local/.

There are two ways to build the test suite. On Unix-alike systems, a Makefile is available undertests/.

cd ./gcem/testsmake./run_tests

With CMake, the optionGCEM_BUILD_TESTS=1 generates the necessary Makefiles to build the test suite.

cd ./gcemmkdir buildcd buildcmake ../ -DGCEM_BUILD_TESTS=1 -DCMAKE_INSTALL_PREFIX=/gcem/install/locationmake gcem_testscd tests./exp.test

You can test the library online using an interactive Jupyter notebook:

GCE-Math functions are written as C++ templates withconstexpr specifiers, the format of which might appear confusing to users unfamiliar with template-based programming.

For example, theGaussian error function (erf) is defined as:

template<typename T>constexprreturn_t<T>erf(const T x)noexcept;

A set of internal templatedconstexpr functions will implement a continued fraction expansion and return a value of typereturn_t<T>. The output type ('return_t<T>') is generally determined by the input type, e.g.,int,float,double,long double, etc.; whenT is an integral type, the output will be upgraded toreturn_t<T> = double, otherwisereturn_t<T> = T. For types not covered bystd::is_integral, recasts should be used.

To calculate 10!:

#include"gcem.hpp"intmain(){constexprint x =10;constexprint res =gcem::factorial(x);return0;}

Inspecting the assembly code generated by Clang 7.0.0:

pushrbpmovrbp,rspxoreax,eaxmov     dword ptr[rbp-4],0mov     dword ptr[rbp-8],10mov     dword ptr[rbp-12],3628800poprbpret

We see that a function call has been replaced by a numeric value (10! = 3628800).

Similarly, to compute the log Gamma function at a point:

#include"gcem.hpp"intmain(){constexprlongdouble x =1.5;constexprlongdouble res =gcem::lgamma(x);return0;}

Assembly code:

.LCPI0_0:        .long1069547520              #float1.5.LCPI0_1:        .quad-622431863250842976     # x86_fp80-0.120782237635245222719        .short49147        .zero6main:                                   # @mainpushrbpmovrbp,rspxoreax,eaxmov     dword ptr[rbp-4],0fld     dword ptr[rip+ .LCPI0_0]fstp    tbyte ptr[rbp-32]fld     tbyte ptr[rip+ .LCPI0_1]fstp    tbyte ptr[rbp-48]poprbpret

• StatsLib is built on GCEM's compile-time functionality.