FunC
====

`FunC` (Function Comparator) is a C++ tool for approximating any
univariate, pure function (without any side-effects) $f:\texttt{TIN}\to
\texttt{TOUT}$ with a lookup table (LUT) over a closed interval $[a,b]$.
$\texttt{TIN}$ and $\texttt{TOUT}$ must be types with overloads for
$\texttt{operator+,-}$, and there must be a commutative
$\texttt{operator*:TIN}\times\texttt{TOUT}\to\texttt{TOUT}$ (so
$\texttt{TOUT}$ forms a vector space over the field $\texttt{TIN}$). We
take a LUT as any piecewise approximation of $f$, so a LUT of $f$ takes
the following form.

```math
\begin{equation}
L(x) = \begin{cases} p_0(x), & \text{ if } x_0 \leq x < x_1, \\
p_1(x), & \text{ if } x_1 \leq x < x_2, \\
\quad \vdots \\
p_{N-1}(x), & \text{ if } x_{N-1} \leq x \leq x_N,\end{cases}
\end{equation}
```

Where $p_k$ are usually (but not necessarily) polynomials. `FunC` can
build LUTs where each $p_k$ in the equation above are interpolating
polynomials (up to degree 7 with Chebyshev nodes of the first kind or
degree 6 with Chebyshev nodes of the second kind), Taylor polynomials
(up to degree 7), Pade approximants, or degree 3 Hermite interpolating
polynomials. The $x_k$ in the equation above partition $[a,b]$, so
$a = x_0 < x_1 < ... < x_n = b$. The $x_k$ can form a uniform partition (so
$x_k=a+k(b-a)/N$) or be an automatically generated nonuniform partition. The
user has no control over the nonuniform partition to ensure the hash only takes
$6$ FLOPs and zero comparisons.

`FunC` aims to streamline finding a good LUT of $f$ for a user's application. To do so, we measure factors such as
- absolute and relative tolerances for error
- domain usage (i.e. the inputs to $f$ during the user's program's runtime)
- evaluation frequency (i.e. how much work is being done in between calls to $f$)

`FunC`'s DirectEvaluation class measures the first two, and a
LookupTableGenerator optimizes a LUT's step size according to maximum
tolerances for error.


Requirements
------------

- C++14 compliant compiler (tested with g++ and clang++)
- Boost 1.71.0 or newer*
- Armadillo (tested with 9.1-12.6)*

\*FunC will function without Boost and Armadillo. These dependancies are
required for _generating LUTs_. They are _not_ required when reading
existing LUT data from a JSON file. Boost is needed for building a LUT
according to a maximum tolerance for error. Armadillo is only needed for
building ChebyInterpTables and PadeTable.

### Build:

- CMake version >= 3.13
```
mkdir build && cd build/
cmake -DCMAKE_INSTALL_PREFIX=<install-dir> ..
make install
```
Running `make test` will run some tests to check your installation of FunC is good.

After make install, linking to the library (outside of cmake build) requires:
- `<install-dir>/lib` is in your `LD_LIBRARY_PATH` environment variable,
- `<install-dir>/include/func` is in your include flags, and
- `-lfunc` is used when linking


Documentation and Example Usage
-------------------------------
Much of `FunC`'s documentation is automatically generated from the source code
and comments with `doxygen`; however, `FunC User Manual.pdf` contains the
following extra content:
- Motivation for several of FunC's features and design decisions,
- Usage examples,
- Workflow diagram,
- FunC's UML diagram,
- More information on various LookupTable implementations

The html documentation in `docs/html/index.html` is better suited for quick
reference and is entirely generated by Doxygen.

Users should check `examples/experiment.cpp` for example usage of each of
`FunC`'s tools to benchmark several LUTs against directly evaluating $f$ with
its defining mathematical formula.


Notes
-----
- `FunC` is not strictly header-only. Explicit template instantiations
  are compiled into `libfunc.so`; however, user-code can still
  instantiate templates values TIN/TOUT such that TIN approximates a
  field and TOUT forms an approximate vector space over TIN. Only
  LookupTableFactory.hpp, and LookupTableComparator.hpp are compiled
  into the dynamic library. By default they are only for TIN=TOUT=float
  and TIN=TOUT=double.


References
----------
TODO reference to SISC paper


Copyright
---------
TODO decide on copyright
