diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/pgfmanual-en-library-fixedpoint.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/pgfmanual-en-library-fixedpoint.tex | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/pgfmanual-en-library-fixedpoint.tex b/Master/texmf-dist/doc/generic/pgf/pgfmanual-en-library-fixedpoint.tex new file mode 100644 index 00000000000..37d20d13a38 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/pgfmanual-en-library-fixedpoint.tex @@ -0,0 +1,120 @@ +% Copyright 2019 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}[preamble={\usepgflibrary{fixedpointarithmetic}}] +\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} |