| 1 |
% Copyright 2019 by Mark Wibrow |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Fixed Point Arithmetic Library} |
| 12 |
|
| 13 |
\begin{pgflibrary}{fixedpointarithmetic} |
| 14 |
This library provides an interface to the \LaTeX{} package |fp| for fixed |
| 15 |
point arithmetic. In addition to loading this library you must ensure |fp| |
| 16 |
is loaded, otherwise errors will occur. |
| 17 |
\end{pgflibrary} |
| 18 |
|
| 19 |
|
| 20 |
\subsection{Overview} |
| 21 |
|
| 22 |
Whilst the mathematical engine that comes with \pgfname{} is reasonably fast |
| 23 |
and flexible when it comes to parsing, the accuracy tends to be fairly low, |
| 24 |
particularly for expressions involving many operations chained together. In |
| 25 |
addition the range of values that can be computed is very small: |
| 26 |
$\pm16383.99999$. Conversely, the |fp| package has a reasonably high accuracy, |
| 27 |
and can perform computations over a wide range of values (approximately |
| 28 |
$\pm9.999\times10^{17}$), but is comparatively slow and not very flexible, |
| 29 |
particularly regarding parsing. |
| 30 |
|
| 31 |
This library enables the combination of the two: the flexible parser of the |
| 32 |
\pgfname{} mathematical engine with the evaluation accuracy of |fp|. There are, |
| 33 |
however, a number of important points to bear in mind: |
| 34 |
% |
| 35 |
\begin{itemize} |
| 36 |
\item Whilst |fp| supports very large numbers, \pgfname{} and \tikzname{} |
| 37 |
do not. It is possible to calculate the result of |2^20| or |
| 38 |
|1.2e10+3.4e10|, but it is not possible to use these results in |
| 39 |
pictures directly without some ``extra work''. |
| 40 |
\item The \pgfname{} mathematical engine will still be used to evaluate |
| 41 |
lengths, such as |10pt| or |3em|, so it is not possible for an length |
| 42 |
to exceed the range of values supported by \TeX-dimensions |
| 43 |
($\pm16383.99999$pt), even though the resulting expression is within |
| 44 |
the range of |fp|. So, for example, one can calculate |3cm*10000|, but |
| 45 |
not |3*10000cm|. |
| 46 |
\item Not all of the functions listed in Section~\ref{pgfmath-syntax}, have |
| 47 |
been mapped onto |fp| equivalents. Of those that have been, it is not |
| 48 |
guaranteed that functions will perform in the same way as they do in |
| 49 |
\pgfname. Reference should be made to the documentation for |fp|. |
| 50 |
\item In \pgfname, trigonometric functions such as |sin| and |cos| assume |
| 51 |
arguments are in degrees, and functions such as |asin| and |acos| |
| 52 |
return results in degrees. Although |fp| uses radians for such |
| 53 |
functions, \pgfname{} automatically converts arguments from degrees to |
| 54 |
radians, and converts results from radians to degrees, to ensure |
| 55 |
everything ``works properly''. |
| 56 |
\item The overall speed will actually be slower than using \pgfname{} |
| 57 |
mathematical engine. The calculating power of |fp| comes at the cost of |
| 58 |
an increased processing time. |
| 59 |
\end{itemize} |
| 60 |
|
| 61 |
|
| 62 |
\subsection{Using Fixed Point Arithmetic in PGF and \tikzname} |
| 63 |
|
| 64 |
The following key is provided to use |fp| in \pgfname{} and \tikzname: |
| 65 |
|
| 66 |
\begin{key}{/pgf/fixed point arithmetic=\meta{options}} |
| 67 |
\keyalias{tikz} |
| 68 |
This key will set the key path to |/pgf/fixed point|, and execute |
| 69 |
\meta{options}. Then it will install the necessary commands so that the |
| 70 |
\pgfname{} parser will use |fp| to perform calculations. The best way to |
| 71 |
use this key is as an argument to a scope or picture. This means that |fp| |
| 72 |
does not always have to be used, and \pgfname{} can use its own |
| 73 |
mathematical engine at other times, which can lead to a significant |
| 74 |
reduction in the time for a document to compile. |
| 75 |
\end{key} |
| 76 |
|
| 77 |
Currently there are only a few keys key supported for \meta{options}: |
| 78 |
|
| 79 |
\begin{key}{/pgf/fixed point/scale results=\meta{factor}} |
| 80 |
As noted above, |fp| can process a far greater range of numbers than |
| 81 |
\pgfname{} and \tikzname{}. In order to use results from |fp| in a |
| 82 |
|{pgfpicture}| or a |{tikzpicture}| they need to be scaled. When this key |
| 83 |
is used \pgfname{} will scale results of any evaluation by \meta{factor}. |
| 84 |
However, as it is not desirable for every part of every expression to be |
| 85 |
scaled, scaling will only take place if a special prefix |*| is used. If |
| 86 |
|*| is used at the beginning of an expression the evaluation of the |
| 87 |
expression will evaluated and then multiplied by \meta{factor}. |
| 88 |
% |
| 89 |
\begin{codeexample}[preamble={\usepgflibrary{fixedpointarithmetic}}] |
| 90 |
\begin{tikzpicture}[fixed point arithmetic={scale results=10^-6}] |
| 91 |
\draw [help lines] grid (3,2); |
| 92 |
\draw (0,0) -- (2,2); |
| 93 |
\draw [red, line width=4pt] (*1.0e6,0) -- (*3.0e6,*2.0e6); |
| 94 |
\end{tikzpicture} |
| 95 |
\end{codeexample} |
| 96 |
|
| 97 |
A special case of scaling involves plots of data containing large numbers |
| 98 |
from files. It is possible to ``pre-process'' a file, typically using the |
| 99 |
application that generates the data, to either precede the relevant column |
| 100 |
with |*| or to perform the scaling as part of the calculation process. |
| 101 |
However, it may be desirable for the data in a plot to appear in a table as |
| 102 |
well, so, two files would be required, one pre-processed for plotting, and |
| 103 |
one not. This extra work may be undesirable so the following keys are |
| 104 |
provided: |
| 105 |
|
| 106 |
\begin{key}{/pgf/fixed point/scale file plot x=\meta{factor}} |
| 107 |
This key will scale the first column of data read from a file before it |
| 108 |
is plotted. It is independent of the |scale results| key. |
| 109 |
\end{key} |
| 110 |
|
| 111 |
\begin{key}{/pgf/fixed point/scale file plot y=\meta{factor}} |
| 112 |
This key will scale the second column of data read from a file before |
| 113 |
it is plotted. |
| 114 |
\end{key} |
| 115 |
|
| 116 |
\begin{key}{/pgf/fixed point/scale file plot z=\meta{factor}} |
| 117 |
This key will scale the third column of data read from a file before it |
| 118 |
is plotted. |
| 119 |
\end{key} |
| 120 |
\end{key} |