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

{\bf\emph{This library is provisional, and may change/disappear without warning}}

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

