From 22536bb2b5257046d271b1eaa11b4a275d5ec041 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 5 Jan 2019 22:40:38 +0000 Subject: pgf (5jan19) git-svn-id: svn://tug.org/texlive/trunk@49607 c570f23f-e606-0410-a88d-b1316a301751 --- .../text-en/pgfmanual-en-library-fixedpoint.tex | 195 +++++++++------------ 1 file changed, 82 insertions(+), 113 deletions(-) (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fixedpoint.tex') diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fixedpoint.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fixedpoint.tex index 1be2d41e7b8..238d0c16ad2 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fixedpoint.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fixedpoint.tex @@ -11,109 +11,81 @@ \section{Fixed Point Arithmetic Library} \begin{pgflibrary}{fixedpointarithmetic} - This library provides an interface to the \LaTeX{} package - |fp| for fixed point arithmetic. In addition to loading this - library you must ensure |fp| is loaded, otherwise errors - will occur. + This library provides an interface to the \LaTeX{} package |fp| for fixed + point arithmetic. In addition to loading this library you must ensure |fp| + is loaded, otherwise errors will occur. \end{pgflibrary} -\subsection{Overview} - Whilst the mathematical engine that comes with \pgfname{} is - reasonably fast and flexible when it comes to parsing, the accuracy - tends to be fairly low, particularly for expressions involving many - operations chained together. In addition the range of values that - can be computed is very small: $\pm16383.99999$. - Conversely, the |fp| package has a reasonably high accuracy, and - can perform computations over a wide range of - values (approximately $\pm9.999\times10^{17}$), but is comparatively - slow and not very - flexible, particularly regarding parsing. - - This library enables the combination of the two: the flexible parser - of the \pgfname{} mathematical engine with the evaluation accuracy - of |fp|. There are, however, a number of important points to - bear in mind: +\subsection{Overview} +Whilst the mathematical engine that comes with \pgfname{} is reasonably fast +and flexible when it comes to parsing, the accuracy tends to be fairly low, +particularly for expressions involving many operations chained together. In +addition the range of values that can be computed is very small: +$\pm16383.99999$. Conversely, the |fp| package has a reasonably high accuracy, +and can perform computations over a wide range of values (approximately +$\pm9.999\times10^{17}$), but is comparatively slow and not very flexible, +particularly regarding parsing. + +This library enables the combination of the two: the flexible parser of the +\pgfname{} mathematical engine with the evaluation accuracy of |fp|. There are, +however, a number of important points to bear in mind: +% \begin{itemize} - - \item - - Whilst |fp| supports very large numbers, \pgfname{} and - \tikzname{} do not. It is possible to calculate the result of - |2^20| or |1.2e10+3.4e10|, but it is not possible to use these - results in pictures directly without some ``extra work''. - - \item - - The \pgfname{} mathematical engine will still be used to evaluate - lengths, such as |10pt| or |3em|, so it is not possible for an - length to exceed the range of values supported by - \TeX-dimensions ($\pm16383.99999$pt), even though the resulting - expression is within the range of |fp|. So, for example, one can - calculate |3cm*10000|, but not |3*10000cm|. - - \item - - Not all of the functions listed in Section~\ref{pgfmath-syntax}, - have been mapped onto |fp| equivalents. Of those that have been, - it is not guaranteed that functions will perform in the same way as - they do in \pgfname. Reference should be made to the documentation - for |fp|. - - \item - - In \pgfname, trigonometric functions such as |sin| and |cos| assume - arguments are in degrees, and functions such as |asin| and |acos| - return results in degrees. Although |fp| uses radians for such - functions, \pgfname{} automatically converts arguments from degrees - to radians, and converts results from radians to degrees, to ensure - everything ``works properly''. - - \item - - The overall speed will actually be slower than using - \pgfname{} mathematical engine. The calculating power of |fp| - comes at the cost of an increased processing time. - - + \item Whilst |fp| supports very large numbers, \pgfname{} and \tikzname{} + do not. It is possible to calculate the result of |2^20| or + |1.2e10+3.4e10|, but it is not possible to use these results in + pictures directly without some ``extra work''. + \item The \pgfname{} mathematical engine will still be used to evaluate + lengths, such as |10pt| or |3em|, so it is not possible for an length + to exceed the range of values supported by \TeX-dimensions + ($\pm16383.99999$pt), even though the resulting expression is within + the range of |fp|. So, for example, one can calculate |3cm*10000|, but + not |3*10000cm|. + \item Not all of the functions listed in Section~\ref{pgfmath-syntax}, have + been mapped onto |fp| equivalents. Of those that have been, it is not + guaranteed that functions will perform in the same way as they do in + \pgfname. Reference should be made to the documentation for |fp|. + \item In \pgfname, trigonometric functions such as |sin| and |cos| assume + arguments are in degrees, and functions such as |asin| and |acos| + return results in degrees. Although |fp| uses radians for such + functions, \pgfname{} automatically converts arguments from degrees to + radians, and converts results from radians to degrees, to ensure + everything ``works properly''. + \item The overall speed will actually be slower than using \pgfname{} + mathematical engine. The calculating power of |fp| comes at the cost of + an increased processing time. \end{itemize} + \subsection{Using Fixed Point Arithmetic in PGF and \tikzname} - The following key is provided to use |fp| in \pgfname{} - and \tikzname: +The following key is provided to use |fp| in \pgfname{} and \tikzname: \begin{key}{/pgf/fixed point arithmetic=\meta{options}} \keyalias{tikz} - - This key will set the key path to |/pgf/fixed point|, and - execute \meta{options}. Then it will install the necessary - commands so that the \pgfname{} parser will use |fp| to perform - calculations. - The best way to use this key is as an argument to a scope or - picture. This means that |fp| does not always have to be used, - and \pgfname{} can use its own mathematical engine at other times, - which can lead to a significant reduction in the time for a document - to compile. - + This key will set the key path to |/pgf/fixed point|, and execute + \meta{options}. Then it will install the necessary commands so that the + \pgfname{} parser will use |fp| to perform calculations. The best way to + use this key is as an argument to a scope or picture. This means that |fp| + does not always have to be used, and \pgfname{} can use its own + mathematical engine at other times, which can lead to a significant + reduction in the time for a document to compile. \end{key} - Currently there are only a few keys key supported for \meta{options}: +Currently there are only a few keys key supported for \meta{options}: \begin{key}{/pgf/fixed point/scale results=\meta{factor}} - - As noted above, |fp| can process a far greater range of numbers - than \pgfname{} and \tikzname{}. In order to use results from - |fp| in a |{pgfpicture}| or a |{tikzpicture}| they need to be - scaled. When this key is used \pgfname{} will scale results - of any evaluation by \meta{factor}. However, as it is not - desirable for every part of every expression to be scaled, - scaling will only take place if a special prefix |*| is used. - If |*| is used at the beginning of an expression the evaluation - of the expression will evaluated and then multiplied by - \meta{factor}. - + As noted above, |fp| can process a far greater range of numbers than + \pgfname{} and \tikzname{}. In order to use results from |fp| in a + |{pgfpicture}| or a |{tikzpicture}| they need to be scaled. When this key + is used \pgfname{} will scale results of any evaluation by \meta{factor}. + However, as it is not desirable for every part of every expression to be + scaled, scaling will only take place if a special prefix |*| is used. If + |*| is used at the beginning of an expression the evaluation of the + expression will evaluated and then multiplied by \meta{factor}. + % \begin{codeexample}[] \begin{tikzpicture}[fixed point arithmetic={scale results=10^-6}] \draw [help lines] grid (3,2); @@ -122,30 +94,27 @@ \end{tikzpicture} \end{codeexample} - A special case of scaling involves plots of data containing - large numbers from files. - It is possible to ``pre-process'' a file, typically using the - application that generates the data, to either precede - the relevant column with |*| or to perform the scaling as part - of the calculation process. However, it may be desirable for - the data in a plot to appear in a table as well, so, two files would - be required, one pre-processed for plotting, and one not. This - extra work may be undesirable so the following keys are provided: - -\begin{key}{/pgf/fixed point/scale file plot x=\meta{factor}} - This key will scale the first column of data read from - a file before it is plotted. It is independent of the - |scale results| key. -\end{key} - -\begin{key}{/pgf/fixed point/scale file plot y=\meta{factor}} - This key will scale the second column of data read from - a file before it is plotted. -\end{key} - -\begin{key}{/pgf/fixed point/scale file plot z=\meta{factor}} - This key will scale the third column of data read from - a file before it is plotted. -\end{key} - + A special case of scaling involves plots of data containing large numbers + from files. It is possible to ``pre-process'' a file, typically using the + application that generates the data, to either precede the relevant column + with |*| or to perform the scaling as part of the calculation process. + However, it may be desirable for the data in a plot to appear in a table as + well, so, two files would be required, one pre-processed for plotting, and + one not. This extra work may be undesirable so the following keys are + provided: + + \begin{key}{/pgf/fixed point/scale file plot x=\meta{factor}} + This key will scale the first column of data read from a file before it + is plotted. It is independent of the |scale results| key. + \end{key} + + \begin{key}{/pgf/fixed point/scale file plot y=\meta{factor}} + This key will scale the second column of data read from a file before + it is plotted. + \end{key} + + \begin{key}{/pgf/fixed point/scale file plot z=\meta{factor}} + This key will scale the third column of data read from a file before it + is plotted. + \end{key} \end{key} -- cgit v1.2.3