| 1 |
% Copyright 2018 by Mark Wibrow and Till Tantau |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Design Principles} |
| 12 |
|
| 13 |
\pgfname{} needs to perform many computations while typesetting a picture. For |
| 14 |
this, \pgfname\ relies on a mathematical engine, which can also be used |
| 15 |
independently of \pgfname, but which is distributed as part of the \pgfname\ |
| 16 |
package nevertheless. Basically, the engine provides a parsing mechanism |
| 17 |
similar to the \calcname{} package so that expressions like |2*3cm+5cm| can be |
| 18 |
parsed; but the \pgfname\ engine is more powerful and can be extended and |
| 19 |
enhanced. |
| 20 |
|
| 21 |
\pgfname{} provides enhanced functionality, which permits the parsing of |
| 22 |
mathematical operations involving integers and non-integers with or without |
| 23 |
units. Furthermore, various functions, including trigonometric functions and |
| 24 |
random number generators can also be parsed (see |
| 25 |
Section~\ref{pgfmath-parsing}). The \calcname{} macros |\setlength| and friends |
| 26 |
have \pgfname{} versions which can parse these operations and functions (see |
| 27 |
Section~\ref{pgfmath-registers}). Additionally, each operation and function has |
| 28 |
an independent \pgfname{} command associated with it (see |
| 29 |
Section~\ref{pgfmath-commands}), and can be accessed outside the parser. |
| 30 |
|
| 31 |
The mathematical engine of \pgfname\ is implicitly used whenever you specify a |
| 32 |
number or dimension in a higher-level macro. For instance, you can write |
| 33 |
|\pgfpoint{2cm+4cm/2}{3cm*sin(30)}| or suchlike. However, the mathematical |
| 34 |
engine can also be used independently of the \pgfname\ core, that is, you can |
| 35 |
also just load it to get access to a mathematical parser. |
| 36 |
|
| 37 |
|
| 38 |
\subsection{Loading the Mathematical Engine} |
| 39 |
|
| 40 |
The mathematical engine of \pgfname\ is loaded automatically by \pgfname, but |
| 41 |
if you wish to use the mathematical engine but you do not need \pgfname\ |
| 42 |
itself, you can load the following package: |
| 43 |
|
| 44 |
\begin{package}{pgfmath} |
| 45 |
This command will load the mathematical engine of \pgfname, but not |
| 46 |
\pgfname{} itself. It defines commands like |\pgfmathparse|. |
| 47 |
\end{package} |
| 48 |
|
| 49 |
|
| 50 |
\subsection{Layers of the Mathematical Engine} |
| 51 |
|
| 52 |
Like \pgfname\ itself, the mathematical engine is also structured into |
| 53 |
different layers: |
| 54 |
% |
| 55 |
\begin{enumerate} |
| 56 |
\item The top layer, which you will typically use directly, provides the |
| 57 |
command |\pgfmathparse|. This command parses a mathematical expression |
| 58 |
and evaluates it. |
| 59 |
|
| 60 |
Additionally, the top layer also defines some additional functions |
| 61 |
similar to the macros of the |calc| package for setting dimensions and |
| 62 |
counters. These macros are just wrappers around the |\pgfmathparse| |
| 63 |
macro. |
| 64 |
|
| 65 |
\item The calculation layer provides macros for performing one specific |
| 66 |
computation like computing a reciprocal or a multiplication. The parser |
| 67 |
uses these macros for the actual computation. |
| 68 |
\item The implementation layer provides the actual implementations of the |
| 69 |
computations. These can be changed (and possibly be made more |
| 70 |
efficient) without affecting the higher layers. |
| 71 |
\end{enumerate} |
| 72 |
|
| 73 |
|
| 74 |
\subsection{Efficiency and Accuracy of the Mathematical Engine} |
| 75 |
|
| 76 |
Currently, the mathematical algorithms are all implemented in \TeX. This poses |
| 77 |
some intriguing programming challenges as \TeX{} is a language for typesetting, |
| 78 |
rather than for general mathematics, and as with any programming language, |
| 79 |
there is a trade-off between accuracy and efficiency. If you find the level of |
| 80 |
accuracy insufficient for your purposes, you will have to replace the |
| 81 |
algorithms in the implementation layer. |
| 82 |
|
| 83 |
All the fancy mathematical ``bells-and-whistles'' that the parser provides, |
| 84 |
come with an additional processing cost, and in some instances, such as simply |
| 85 |
setting a length to |1cm|, with no other operations involved, the additional |
| 86 |
processing time is undesirable. To overcome this, the following feature is |
| 87 |
implemented: when no mathematical operations are required, an expression can be |
| 88 |
preceded by |+|. This will bypass the parsing process and the assignment will |
| 89 |
be orders of magnitude faster. This feature \emph{only} works with the macros |
| 90 |
for setting registers described in Section~\ref{pgfmath-registers}. |
| 91 |
% |
| 92 |
\begin{codeexample}[code only] |
| 93 |
\pgfmathsetlength\mydimen{1cm} % parsed : slower. |
| 94 |
\pgfmathsetlength\mydimen{+1cm} % not parsed : much faster. |
| 95 |
\end{codeexample} |