diff options
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 | 135 |
1 files changed, 60 insertions, 75 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 index 59295dc7c9d..43a93b08b5f 100644 --- 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 @@ -8,46 +8,42 @@ % 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. +\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: +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|. + This command will load the mathematical engine of \pgfname, but not + \pgfname{} itself. It defines commands like |\pgfmathparse|. \end{package} @@ -55,56 +51,45 @@ not need \pgfname\ itself, you can load the following package: 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. + \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}. - +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} - |