% Copyright 2018 by Mark Wibrow and Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Design Principles}

\pgfname{} needs to perform many computations while typesetting a picture. For
this, \pgfname\ relies on a mathematical engine, which can also be used
independently of \pgfname, but which is distributed as part of the \pgfname\
package nevertheless. Basically, the engine provides a parsing mechanism
similar to the \calcname{} package so that expressions like |2*3cm+5cm| can be
parsed; but the \pgfname\ engine is more powerful and can be extended and
enhanced.

\pgfname{} provides enhanced functionality, which permits the parsing of
mathematical operations involving integers and non-integers with or without
units. Furthermore, various functions, including trigonometric functions and
random number generators can also be parsed (see
Section~\ref{pgfmath-parsing}). The \calcname{} macros |\setlength| and friends
have \pgfname{} versions which can parse these operations and functions (see
Section~\ref{pgfmath-registers}). Additionally, each operation and function has
an independent \pgfname{} command associated with it (see
Section~\ref{pgfmath-commands}), and can be accessed outside the parser.

The mathematical engine of \pgfname\ is implicitly used whenever you specify a
number or dimension in a higher-level macro. For instance, you can write
|\pgfpoint{2cm+4cm/2}{3cm*sin(30)}| or suchlike. However, the mathematical
engine can also be used independently of the \pgfname\ core, that is, you can
also just load it to get access to a mathematical parser.


\subsection{Loading the Mathematical Engine}

The mathematical engine of \pgfname\ is loaded automatically by \pgfname, but
if you wish to use the mathematical engine but you do not need \pgfname\
itself, you can load the following package:

\begin{package}{pgfmath}
    This command will load the mathematical engine of \pgfname, but not
    \pgfname{} itself. It defines commands like |\pgfmathparse|.
\end{package}


\subsection{Layers of the Mathematical Engine}

Like \pgfname\ itself, the mathematical engine is also structured into
different layers:
%
\begin{enumerate}
    \item The top layer, which you will typically use directly, provides the
        command |\pgfmathparse|. This command parses a mathematical expression
        and evaluates it.

        Additionally, the top layer also defines some additional functions
        similar to the macros of the |calc| package for setting dimensions and
        counters. These macros are just wrappers around the |\pgfmathparse|
        macro.

    \item The calculation layer provides macros for performing one specific
        computation like computing a reciprocal or a multiplication. The parser
        uses these macros for the actual computation.
    \item The implementation layer provides the actual implementations of the
        computations. These can be changed (and possibly be made more
        efficient) without affecting the higher layers.
\end{enumerate}


\subsection{Efficiency and Accuracy of the Mathematical Engine}

Currently, the mathematical algorithms are all implemented in \TeX. This poses
some intriguing programming challenges as \TeX{} is a language for typesetting,
rather than for general mathematics, and as with any programming language,
there is a trade-off between accuracy and efficiency. If you find the level of
accuracy insufficient for your purposes, you will have to replace the
algorithms in the implementation layer.

All the fancy mathematical ``bells-and-whistles'' that the parser provides,
come with an additional processing cost, and in some instances, such as simply
setting a length to |1cm|, with no other operations involved, the additional
processing time is undesirable. To overcome this, the following feature is
implemented: when no mathematical operations are required, an expression can be
preceded by |+|. This will bypass the parsing process and the assignment will
be orders of magnitude faster. This feature \emph{only} works with the macros
for setting registers described in Section~\ref{pgfmath-registers}.
%
\begin{codeexample}[code only]
\pgfmathsetlength\mydimen{1cm}  % parsed     : slower.
\pgfmathsetlength\mydimen{+1cm} % not parsed : much faster.
\end{codeexample}