diff options
author | Karl Berry <karl@freefriends.org> | 2007-06-17 23:22:38 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2007-06-17 23:22:38 +0000 |
commit | 5c5c7843fbd37c6960799b6e1a32d5948966316c (patch) | |
tree | ea73f6b5ba799656992ebe2f34beccd2555f1342 /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex | |
parent | f0c1f4cdb9fad83f293fd91d194538425f9f7633 (diff) |
pgf 1.18 (15jun07)
git-svn-id: svn://tug.org/texlive/trunk@4459 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex new file mode 100644 index 00000000000..d63d506db3a --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex @@ -0,0 +1,104 @@ +% 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 +typesetting language not a mathematical one, 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 addition processing time is undesirable. +To overcome this, the following feature is implemented: when no +mathematical operations are required, the value in \meta{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} + |