summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-math-design.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-math-design.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-math-design.tex95
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}