Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-library-fixedpoint.tex

raw
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}