The Compositional Numeric Library (CNL) is a C++ library of fixed-precision numeric classes which enhance integers to deliver safer, simpler, cheaper arithmetic types. Documentation can be found here.
CNL is particularly well-suited to:
- compute or energy-constrained environments where FPUs are absent or costly;
- compute or energy-intensive environments where arithmetic is the bottleneck such as simulations, machine learning applications and DSPs; and
- domains such as finance where precision is essential.
The latest version of CNL requires a C++20-compatible tool chain. (Version 1.x supports C++11.) CNL is tested on the following systems:
Tested:
- GCC 10 / Clang 10, 11
- CMake 3.16
- Conan 1.32
Tested:
- GCC 10 / Clang 11
- CMake 3.16
- Conan 1.35
Tested:
- Visual Studio 2019 Version 16.8
- CMake 3.8.0
- Conan 1.35
The library is hosted on GitHub:
git clone https://github.com/johnmcfarlane/cnl.git
cd cnl
CMake scripts are provided.
- To build and install CNL on your system:
mkdir build && cd build
cmake ..
cmake --build . --target install
Note: you may need user privileges to install the library.
Alternatively, you can install to user directory using CMAKE_INSTALL_PREFIX
:
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX:FILE=/home/username/someplace ..
cmake --build . --target install
Alternatively, CNL is a header-only library so you can simply point to the include directory
c++ -isystem /path/to/cnl/include -std=c++20 my_program.cpp
or even include the root header directly in your code:
#include "/path/to/cnl/include/cnl/all.h"
The test suite uses CMake and depends on Google Test and Google Benchmark. Optional integration tests use Boost.Multiprecision and Boost.SIMD.
-
Conan can be used to pull in essential dependencies. This example assumes GCC but other tool chain files are provided:
cd build conan profile new --detect --force default conan profile update settings.compiler.libcxx=libstdc++11 default # GCC only conan profile update settings.compiler.cppstd=20 default conan install --build=missing --options test=unit ..
... and then configure, build and run unit tests:
conan build --configure --build --test ..
-
To run benchmarks, use
--options test=benchmark
...conan install --build=missing --options test=benchmark ..
then configure and build
conan build --configure --build ..
and finally run explicitly to see the results.
./test/benchmark/test-benchmark
The API is exposed through headers in the include directory. Add this to your system header list and include, e.g.:
// to use a specific type:
#include <cnl/scaled_integer.h>
// or to include all CNL types:
#include <cnl/all.h>
Examples of projects using CNL:
- CDSP - Compositional DSP Library for C++;
- BrewBlox firmware - firmware for a brewery controller
- cnl_example - minimal CMake-based project which uses CNL as a dependency.
- CNL documentation
- CppCon 2017 presentation
- Embedded Artistry article
- ISO C++ papers:
- Much of the simplicity and efficiency in CNL's API design can be traced back to Matheus Izvekov's fp fixed point library.
- Together with Lawrence Crowl's fixed-point paper, P0106, it lays the groundwork for integer-backed real number approximation that minimizes loss of performance and precision.
- fpm is a fixed-point math library with a high quantity of mathematical functions.
- Fixed Point Class is a single-header C++98 solution from Peter Schregle's.
All feedback greatly appreciated.