Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-math-design.tex

raw
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}