ppapp 1.0.0__py3-none-any.whl

userManual/userManual.tex

@@ -0,0 +1,368 @@
+\documentclass[screen,nonacm]{acmart}
+
+%---------------------------------------------------------------------------
+\usepackage{mathtools}
+\usepackage{listings}
+\usepackage{adjustbox}
+
+\lstdefinestyle{mystyle}{
+  basicstyle=\ttfamily\footnotesize,
+  breakatwhitespace=false,
+  breaklines=true,
+  captionpos=b,
+  columns=fullflexible,
+  keepspaces=true,
+  showspaces=false,
+  showstringspaces=false,
+  showtabs=false,
+  tabsize=2
+}
+\lstset{style=mystyle}
+
+\newfloat{program}{!ht}{}
+\floatname{program}{Program}
+
+\DeclareMathOperator{\IM}{Im}
+\DeclareMathOperator{\erfi}{erfi}
+
+% Define a visible unnumbered subsubsection
+\newcommand{\modeheader}[1]{\par\vspace{6pt plus 12pt minus 3pt}\pagebreak[1]\noindent\textbf{#1}\nopagebreak[4]}
+
+%---------------------------------------------------------------------------
+
+\begin{document}
+
+\title[User Manual: Python code for generating C code for piecewise Chebyshev approximation]
+{User Manual:\\ Python code for generating C code for piecewise Chebyshev approximation}
+
+\author{Joachim Wuttke}
+\email{j.wuttke@fz-juelich.de}
+\orcid{0000-0002-4028-1447}
+\affiliation{%
+  \institution{Forschungszentrum Jülich GmbH}
+  \city{Jülich Centre for Neutron Science at MLZ, Lichtenbergstraße 1, 85748 Garching}
+  \country{Germany}}
+
+\author{Alexander Kleinsorge}
+\email{alkl9873@th-wildau.de}
+\affiliation{%
+  \institution{Technische Hochschule Wildau}
+   \city{Studiengang Telematik, Hochschulring 1, 15745 Wildau}
+  \country{Germany}}
+
+\begin{abstract}
+This user guide documents Python and C software that implements the algorithms
+described in the article
+``Algorithm 1xxx: Code generation for piecewise Chebyshev approximation''.
+\end{abstract}
+
+\maketitle
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Introduction}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+This open-source Python package \textit{ppapp}
+(\textit{p}iecewise \textit{p}olynomial \textit{app}roximation)
+implements the algorithms described in the article
+``Algorithm 1xxx: Code generation for piecewise Chebyshev approximation'' \cite{WuKl2x}.
+The software is released under the GNU General Public License Version 3 or higher;
+other licensing is negotiable.
+
+The package is available in two forms:
+\begin{itemize}
+\item The \textbf{PyPI package} \texttt{ppapp}, installable via \texttt{pip install ppapp},
+      contains the Python code generator and demo functions.
+\item The \textbf{project repository} at \url{https://jugit.fz-juelich.de/mlz/ppapp}
+      contains additionally the original C++ implementation,
+      user manual source, C demonstration code, and development history.
+      Paths in Section~\ref{Sdem} referring to \texttt{demo/} are relative to this repository root.
+\end{itemize}
+The software may be further improved if new ideas arise;
+in particular, it shall be extended to tile-wise Taylor approximation in the complex plane \cite{Wut:cgt}.
+
+Section~\ref{Sgen} describes the code generator that produces C source files
+containing tables of polynomial coefficients that approximate a specific function~$f$.
+Section~\ref{Sdem} describes how the generated C code is used.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Code generator}\label{Sgen}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%===================================================================================================
+\subsection{Install and run}\label{SgenInstall}
+%===================================================================================================
+
+The generator code is written in the programming language Python3.
+It depends on the arbitrary-precision library \textit{Arb}
+that is part of \textit{FLINT}, Fast Library for Number Theory \cite{s:flint}.
+A Python wrapper of FLINT is available from \url{pypi.org}
+as package \textit{python-flint}.
+
+The software can be installed from PyPI with:
+\begin{lstlisting}
+pip install ppapp
+\end{lstlisting}
+This automatically installs the \textit{python-flint} dependency
+and provides the command:
+\begin{lstlisting}
+ppapp
+\end{lstlisting}
+
+Alternatively, when working with the source repository without installing,
+run from the directory containing the \texttt{ppapp} package:
+\begin{lstlisting}
+cd /path/to/ppapp/py/R
+python -m ppapp <mode> <arguments>
+\end{lstlisting}
+
+Running \texttt{ppapp} without arguments prints a summary of available modes:
+\begin{lstlisting}
+No mode given
+
+Usage:
+
+ppapp i <f_module>                     - run initial tests from my_testcases
+ppapp v <f_module> <x>                 - print function value f(x)
+ppapp n <f_module> <M> <Nmax> <E>      - print N_min(M',E), up to given Nmax
+ppapp e <f_module> <M> <N>             - print maximum relative error, in units of epsilon
+ppapp c <f_module> <M> <N> [<E>]       - print plain table of Chebyshev coefficients c_n
+ppapp p <f_module> <M> <N> [<E>]       - print plain table of economized coefficients p_m
+ppapp s <f_module> <M> <N> [<E>]       - print C source defining economized coefficients p_m
+ppapp t <f_module> <M> <Nxo> <E>       - print C source defining test cases
+
+where
+
+<f_module> - path to function definition file (e.g., 'mydir/f_imwofx.py')
+<M>        - integer M >= 0 specifies 2^M subdomains per octave
+<N>        - integer N >= 1 is the polynomial degree
+<E>        - double E > 0 is the maximum relative error, in units of epsilon=2^-53
+<Nxo>      - number of extra (non-Chebyshev) octaves on each side of the Chebyshev range
+\end{lstlisting}
+
+%===================================================================================================
+\subsection{Function argument}\label{SgenFunc}
+%===================================================================================================
+
+All commands require a function definition file as the second argument:
+\begin{lstlisting}
+ppapp v /path/to/my_function.py 1.0
+\end{lstlisting}
+
+The function definition file specifies the interface between the generic approximation machinery
+and the specific target function that is to be approximated.
+It defines one function and two global objects:
+\begin{lstlisting}[language=Python]
+def my_arb_f(X: arb, prec: int) -> arb:
+    """Evaluates f(x) with given precision"""
+    ...
+
+my_domain: Tuple[float, float] = (a, b)
+my_testcases: List[Tuple[float, float, float]] = [
+    (x, f_expected, tolerance),
+    ...
+]
+\end{lstlisting}
+Function \texttt{my\_arb\_f} computes $f(x)$ in interval arithmetics
+with a precision of \texttt{prec} binary digits,
+using the python-flint wrapper for Arb \cite{s:flint}.
+The tuple \texttt{my\_domain} contains the limits of the total domain $[a,b)$.
+The entries in the list \texttt{my\_testcases} are triples $(x, f_\text{expected}(x), \text{tol})$.
+The test suite will fail unless for each test case,
+the function value $f(x)$, computed by our arbitrary-precision function \texttt{my\_arb\_f},
+agrees with $f_\text{expected}(x)$ with a relative error not larger than $\text{tol}$.
+
+As an example, the package includes \texttt{ppapp/demo\_functions/imwofx.py}
+that implements the function
+\begin{align}
+  f(x)\coloneqq \exp(-x^2)\erfi(x) \equiv \IM\,w(x)
+\end{align}
+introduced in \cite[Sect 1.3]{WuKl2x}.
+The arbitrary-precision computation of~$f$ is straightforward because Arb supports $\erfi(x)$
+as built-in method \texttt{arb.erfi()}.
+The domain is $[a,b)=[0.5,12)$.
+The test cases allow a tolerance of $10^{-5}$,
+i.~e.\ they are meant to ensure the basic correctness of the high-precision implementation
+but not its accuracy.
+The latter is not a concern because of the intrinsic accuracy control of Arb.
+To support any other function~$f$,
+one needs to write a new implementation file,
+based on the model provided by~\texttt{ppapp/demo\_functions/imwofx.py}.
+
+A second example, \texttt{ppapp/demo\_functions/polynomial.py}, implements the simple polynomial
+\begin{align}
+  f(x) \coloneqq x^3 - x^2 + x - 1
+\end{align}
+over the domain $[1.5, 4)$.
+This serves as a useful test case because the Chebyshev approximation of an exact
+degree-3 polynomial should yield only four significant coefficients ($p_0$ through $p_3$),
+with all higher-order coefficients being negligible (at the level of numerical noise).
+
+%===================================================================================================
+\subsection{Run modes}\label{SgenRun}
+%===================================================================================================
+
+The program \texttt{ppapp} operates in different modes that are selected by a letter
+provided as first command-line argument.
+All output is written to \texttt{stdout};
+use redirection to save it in a file.
+
+\modeheader{Initial test mode.}
+\begin{lstlisting}
+ppapp i <f_module>
+\end{lstlisting}
+Tests the function implementation against the test cases defined in \texttt{my\_testcases}.
+This verifies that the high-precision reference function is basically correct
+before using it for coefficient generation.
+
+\modeheader{Function value mode.}
+\begin{lstlisting}
+ppapp v <f_module> <x>
+\end{lstlisting}
+Computes a single function value $f(x)$.
+
+\modeheader{Minimal degree mode.}
+\begin{lstlisting}
+ppapp n <f_module> <M> <Nmax> <relerr>
+\end{lstlisting}
+Computes the minimal polynomial degree for which the relative error,
+in units of $\epsilon$, is not larger than the given \texttt{relerr}.
+This mode has been used to produce Table~1 in \cite{WuKl2x}.
+
+\modeheader{Error bound mode.}
+\begin{lstlisting}
+ppapp e <f_module> <M> <N>
+\end{lstlisting}
+Prints an upper bound for the total relative error in units of~$\epsilon$.
+Based on results from modes \texttt{n} and \texttt{e},
+make your choice of $M$ and $N$,
+as discussed in \cite[Sect~4.4]{WuKl2x}.
+
+\modeheader{Coefficient table modes.}
+\begin{lstlisting}
+ppapp c <f_module> <M> <N> [<relerr>]
+ppapp p <f_module> <M> <N> [<relerr>]
+\end{lstlisting}
+Prints a table
+of Chebyshev coefficients $c_{ln}$ (mode \texttt{c})
+or of economized polynomial coefficients $p_{ln}$ (mode \texttt{p}).
+These modes have been used to produce Fig~3 of~\cite{WuKl2x}.
+The optional \texttt{relerr} argument, in units of~$\epsilon$,
+activates tests that ensure that the relative error never exceeds this bound.
+
+\modeheader{C source code mode.}
+\begin{lstlisting}
+ppapp s <f_module> <M> <N> [<relerr>]
+\end{lstlisting}
+Prints C source code with arrays that hold the $p_{ln}$.
+
+\modeheader{Test case mode.}
+\begin{lstlisting}
+ppapp t <f_module> <M> <Nxo> <relerr>
+\end{lstlisting}
+Prints C source code with test cases, covering a range $a 2^{-N_\text{xo}} \ldots b 2^{N_\text{xo}}$
+that extends beyond the Chebyshev domain if $N_\text{xo}>0$.
+
+%===================================================================================================
+\subsection{Hexadecimal output}
+%===================================================================================================
+
+The output files are self-explaining thanks to initial comment lines.
+Let us explain just one detail:
+In the auto-generated C source files,
+floating-point numbers are written in hexadecimal format, like
+\begin{lstlisting}
+    0x1.ef90904c7eeeep-2, 0x1.461380c17af85p-8, -0x1.9d5e2f887fe99p-15, -0x1.35c476fb1ab4ap-24, ...
+\end{lstlisting}
+Note that the letter \texttt{p} is followed by the base 2 exponent in decimal notation,
+i.e.\ \texttt{0x1.8p-13} is $1.5\cdot2^{-13}$.
+
+%===================================================================================================
+\subsection{Unit tests}\label{SGenTests}
+%===================================================================================================
+
+The PyPI package includes a comprehensive test suite.
+When working with the repository, the tests can be run with:
+\begin{lstlisting}
+python3 -m pytest tests/ -v
+\end{lstlisting}
+
+The test suite covers
+mathematical helper functions,
+power law analysis,
+error bounds,
+subdomain computation,
+output formatting,
+function modules,
+Chebyshev coefficient computation,
+polynomial approximation accuracy,
+and full pipeline integration.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Usage demonstrator}\label{Sdem}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+The C source code generated by \texttt{ppapp} can be used in C or C++ projects
+to compute function values~$f(x)$.
+In a typical application, this code would be integrated with other code that
+evaluates~$f$ outside the intermediate domain considered here,
+using expansions for small and large~$x$.
+
+A C demonstration implementation is available in directory \texttt{demo/R/outcome}
+of the project repository (not included in the PyPI package).
+It shows how to use the auto-generated coefficients for efficient function evaluation.
+
+The target algorithm for evaluating the piecewise polynomial approximation
+is also illustrated in the Python module \texttt{ppapp.target\_algorithm}
+(included in the PyPI package).
+This plain Python implementation is for illustration purposes only.
+The \textit{ppapp} project is designed to generate C code for optimized high-throughput computation.
+For production use from Python, the evaluation code should be implemented
+as a C extension module or at least use NumPy for vectorized operations.
+The Python script should not be used as a template for production code.
+
+%===================================================================================================
+\subsection{Alignment specifier}
+%===================================================================================================
+
+In order to minimize the number of cache loads,
+the auto-generated arrays that hold tables of polynomial coefficients
+must start at the beginning of a 64 bytes memory block \cite[Sect 2.3]{WuKl2x}.
+This is achieved by defining these arrays as
+\begin{lstlisting}[language=C]
+alignas(64) static const double ppapp_Coeffs0[...] = { ... };
+\end{lstlisting}
+The specifier \texttt{alignas} is defined in the language standards C23 and C++11.
+For older versions of C it is not in the standard,
+but may be supported as a compiler extension.
+C11 has a specifier \texttt{\_Alignas}.
+For even older language variants one would depend on compiler-specific attributes.
+
+The Python code generator automatically inserts the correct alignment directives
+and pads coefficient tables with zeros when necessary to maintain proper alignment
+\cite[Sect 2.4]{WuKl2x}.
+
+In the project repository, the C demonstration executable is built and run with the commands
+\begin{lstlisting}
+cd demo/R/outcome
+mkdir build
+cd build
+cmake ..
+make
+./statistics g <n>
+./statistics h <n>
+\end{lstlisting}
+In mode \texttt{g}, the relative deviation between the polynomial approximation
+and the reference code is computed for $n$ values of $x$,
+regularly spaced on a logarithmic scale.
+In mode \texttt{h}, $n$ random-drawn values of~$x$ are used to accumulate a histogram
+of absolute values of the relative deviation.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%\section*{Acknowledgement}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\bibliographystyle{switch}
+\bibliography{jw8}
+
+\end{document}