summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2007-06-17 23:22:38 +0000
committerKarl Berry <karl@freefriends.org>2007-06-17 23:22:38 +0000
commit5c5c7843fbd37c6960799b6e1a32d5948966316c (patch)
treeea73f6b5ba799656992ebe2f34beccd2555f1342 /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex
parentf0c1f4cdb9fad83f293fd91d194538425f9f7633 (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.tex104
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}
+