% Copyright 2007 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 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 you
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}

