diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fixedpoint.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fixedpoint.tex | 151 |
1 files changed, 151 insertions, 0 deletions
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 new file mode 100644 index 00000000000..335bac3ed2d --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fixedpoint.tex @@ -0,0 +1,151 @@ +% Copyright 2008 by Mark Wibrow +% +% 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{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. +\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: + +\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. + + +\end{itemize} + +\subsection{Using Fixed Point Arithmetic in PGF 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. + +\end{key} + + 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}. + +\begin{codeexample}[] +\begin{tikzpicture}[fixed point arithmetic={scale results=10^-6}] +\draw [help lines] grid (3,2); +\draw (0,0) -- (2,2); +\draw [red, line width=4pt] (*1.0e6,0) -- (*3.0e6,*2.0e6); +\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} + +\end{key} |