diff options
author | Norbert Preining <norbert@preining.info> | 2023-01-16 03:03:27 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-01-16 03:03:27 +0000 |
commit | 6f9e1680085e7bb4d258f6f8116369d122e196e1 (patch) | |
tree | 9ac0ecb239240d1d672b188f29c1479de215074b /graphics/pgf/base/doc/pgfmanual-en-math-design.tex | |
parent | b8345f39630408bb198e7636381ce4240154ca9b (diff) |
CTAN sync 202301160303
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-math-design.tex')
-rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-math-design.tex | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-math-design.tex b/graphics/pgf/base/doc/pgfmanual-en-math-design.tex new file mode 100644 index 0000000000..72e6ca084a --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-math-design.tex @@ -0,0 +1,95 @@ +% 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} |