summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-library-fixedpoint.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-library-fixedpoint.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-library-fixedpoint.tex120
1 files changed, 120 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-library-fixedpoint.tex b/graphics/pgf/base/doc/pgfmanual-en-library-fixedpoint.tex
new file mode 100644
index 0000000000..37d20d13a3
--- /dev/null
+++ b/graphics/pgf/base/doc/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}