| 1 |
% Copyright 2019 by Christian Feuersaenger |
| 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{Floating Point Unit Library} |
| 12 |
\label{pgfmath-floatunit} |
| 13 |
\label{section-library-fpu} |
| 14 |
|
| 15 |
{\noindent {\emph{by Christian Feuersänger}}} |
| 16 |
|
| 17 |
\begingroup |
| 18 |
\pgfqkeys{/pgf/number format}{sci} |
| 19 |
\pgfkeys{/pgf/fpu} |
| 20 |
|
| 21 |
\begin{pgflibrary}{fpu} |
| 22 |
The floating point unit (fpu) allows the full data range of scientific |
| 23 |
computing for use in \pgfname. Its core is the \pgfname\ math routines for |
| 24 |
mantissa operations, leading to a reasonable trade-off between speed and |
| 25 |
accuracy. It does not require any third-party packages or external |
| 26 |
programs. |
| 27 |
\end{pgflibrary} |
| 28 |
|
| 29 |
|
| 30 |
\subsection{Overview} |
| 31 |
|
| 32 |
The fpu provides a replacement set of math commands which can be installed in |
| 33 |
isolated placed to achieve large data ranges at reasonable accuracy. It |
| 34 |
provides at least% |
| 35 |
\footnote{To be more precise, the FPU's exponent is currently a 32-bit |
| 36 |
integer. That means it supports a significantly larger data range than an |
| 37 |
IEEE double precision number -- but if a future \TeX\ version may provide |
| 38 |
low-level access to doubles, this may change.}% |
| 39 |
the IEEE double precision data range, $\pgfmathprintnumber{-1e+324}, \dotsc, |
| 40 |
\pgfmathprintnumber{+1e324}$. The absolute smallest number bigger than zero is |
| 41 |
$\pgfmathprintnumber{1e-324}$. The FPU's relative precision is at least |
| 42 |
$\pgfmathprintnumber{1e-4}$ although operations like addition have a relative |
| 43 |
precision of $\pgfmathprintnumber{1e-6}$. |
| 44 |
|
| 45 |
Note that the library has not really been tested together with any drawing |
| 46 |
operations. It should be used to work with arbitrary input data which is then |
| 47 |
transformed somehow into \pgfname\ precision. This, in turn, can be processed |
| 48 |
by \pgfname. |
| 49 |
|
| 50 |
|
| 51 |
\subsection{Usage} |
| 52 |
|
| 53 |
\begin{key}{/pgf/fpu=\marg{boolean} (default true)} |
| 54 |
This key installs or uninstalls the FPU. The installation exchanges any |
| 55 |
routines of the standard math parser with those of the FPU: |\pgfmathadd| |
| 56 |
will be replaced with |\pgfmathfloatadd| and so on. Furthermore, any number |
| 57 |
will be parsed with |\pgfmathfloatparsenumber|. |
| 58 |
% |
| 59 |
\begin{codeexample}[preamble={\usepgflibrary{fpu}}] |
| 60 |
\pgfkeys{/pgf/fpu} |
| 61 |
\pgfmathparse{1+1}\pgfmathresult |
| 62 |
\end{codeexample} |
| 63 |
% |
| 64 |
\noindent The FPU uses a low-level number representation consisting of |
| 65 |
flags, mantissa and exponent% |
| 66 |
\footnote{Users should \emph{always} use high |
| 67 |
level routines to manipulate floating point numbers as the format may |
| 68 |
change in a future release.}.% |
| 69 |
To avoid unnecessary format conversions, |\pgfmathresult| will usually |
| 70 |
contain such a cryptic number. Depending on the context, the result may |
| 71 |
need to be converted into something which is suitable for \pgfname\ |
| 72 |
processing (like coordinates) or may need to be typeset. The FPU provides |
| 73 |
such methods as well. |
| 74 |
|
| 75 |
%-------------------------------------------------- |
| 76 |
% TODOsp: codeexamples: Why is this example commented? |
| 77 |
% \begin{codeexample}[preamble={\usepgflibrary{fpu}}] |
| 78 |
% \begin{tikzpicture} |
| 79 |
% \fill[red,fpu,/pgf/fpu/scale results=1e-10] (*1.234e10,*1e10) -- (*2e10,*2e10); |
| 80 |
% \end{tikzpicture} |
| 81 |
% \end{codeexample} |
| 82 |
%-------------------------------------------------- |
| 83 |
|
| 84 |
Use |fpu=false| to deactivate the FPU. This will restore any change. Please |
| 85 |
note that this is not necessary if the FPU is used inside of a \TeX\ group |
| 86 |
-- it will be deactivated afterwards anyway. |
| 87 |
|
| 88 |
It does not hurt to call |fpu=true| or |fpu=false| multiple times. |
| 89 |
|
| 90 |
Please note that if the |fixedpointarithmetic| library of \pgfname\ will |
| 91 |
be activated after the FPU, the FPU will be deactivated automatically. |
| 92 |
\end{key} |
| 93 |
|
| 94 |
\begin{key}{/pgf/fpu/output format=\mchoice{float,sci,fixed} (initially float)} |
| 95 |
This key allows to change the number format in which the FPU assigns |
| 96 |
|\pgfmathresult|. |
| 97 |
|
| 98 |
The predefined choice |float| uses the low-level format used by the FPU. |
| 99 |
This is useful for further processing inside of any library. |
| 100 |
% |
| 101 |
\begin{codeexample}[preamble={\usepgflibrary{fpu}}] |
| 102 |
\pgfkeys{/pgf/fpu,/pgf/fpu/output format=float} |
| 103 |
\pgfmathparse{exp(50)*42}\pgfmathresult |
| 104 |
\end{codeexample} |
| 105 |
|
| 106 |
The choice |sci| returns numbers in the format |
| 107 |
\meta{mantissa}|e|\meta{exponent}. It provides almost no computational |
| 108 |
overhead. |
| 109 |
% |
| 110 |
\begin{codeexample}[preamble={\usepgflibrary{fpu}}] |
| 111 |
\pgfkeys{/pgf/fpu,/pgf/fpu/output format=sci} |
| 112 |
\pgfmathparse{4.22e-8^-2}\pgfmathresult |
| 113 |
\end{codeexample} |
| 114 |
|
| 115 |
The choice |fixed| returns normal fixed point numbers and provides the |
| 116 |
highest compatibility with the \pgfname\ engine. It is activated |
| 117 |
automatically in case the FPU scales results. |
| 118 |
% |
| 119 |
\begin{codeexample}[preamble={\usepgflibrary{fpu}}] |
| 120 |
\pgfkeys{/pgf/fpu,/pgf/fpu/output format=fixed} |
| 121 |
\pgfmathparse{sqrt(1e-12)}\pgfmathresult |
| 122 |
\end{codeexample} |
| 123 |
% |
| 124 |
\end{key} |
| 125 |
|
| 126 |
\begin{key}{/pgf/fpu/scale results=\marg{scale}} |
| 127 |
A feature which allows semi-automatic result scaling. Setting this key has |
| 128 |
two effects: first, the output format for \emph{any} computation will be |
| 129 |
set to |fixed| (assuming results will be processed by \pgfname's kernel). |
| 130 |
Second, any expression which starts with a star, |*|, will be multiplied |
| 131 |
with \meta{scale}. |
| 132 |
\end{key} |
| 133 |
|
| 134 |
\begin{keylist}{ |
| 135 |
/pgf/fpu/scale file plot x=\marg{scale},% |
| 136 |
/pgf/fpu/scale file plot y=\marg{scale},% |
| 137 |
/pgf/fpu/scale file plot z=\marg{scale}% |
| 138 |
} |
| 139 |
These keys will patch \pgfname's |plot file| command to automatically scale |
| 140 |
single coordinates by \meta{scale}. |
| 141 |
|
| 142 |
The initial setting does not scale |plot file|. |
| 143 |
\end{keylist} |
| 144 |
|
| 145 |
\begin{command}{\pgflibraryfpuifactive\marg{true-code}\marg{false-code}} |
| 146 |
This command can be used to execute either \meta{true-code} or |
| 147 |
\meta{false-code}, depending on whether the FPU has been activated or not. |
| 148 |
\end{command} |
| 149 |
|
| 150 |
\begin{key}{/pgf/fpu/install only=\marg{list of names}} |
| 151 |
\label{fpu-install-only} |
| 152 |
Unfortunately, the FPU is currently incompatible with drawing operations. |
| 153 |
However, it can still be useful to replace single definitions with FPU |
| 154 |
counterparts to avoid errors of the kind |Dimension too large| which tend |
| 155 |
to happen when transformation matrices are inverted. |
| 156 |
|
| 157 |
This key allows to specify a list of definitions to be pulled into the |
| 158 |
current scope. \emph{Note that there is no reverse operation to uninstall |
| 159 |
these definitions at the moment}, so it is advisable to do this in a group. |
| 160 |
Conveniently, \tikzname{} paths form an implicit group, so you can use this |
| 161 |
key on a path as well. |
| 162 |
|
| 163 |
You have to be aware of the limitations that the FPU imposes. It will not |
| 164 |
magically give \TeX{} better precision, but it will avoid overflow or |
| 165 |
underflow situations for large or small operands by rescaling them. In the |
| 166 |
following example, in the first case the FPU variant performs much better |
| 167 |
than the normal variant, however, in the second case where a rescaling |
| 168 |
would not in fact be needed the rescaling introduces a small round-off |
| 169 |
error. |
| 170 |
% |
| 171 |
\begin{codeexample}[ |
| 172 |
preamble={\usepgflibrary{fpu}}, |
| 173 |
pre={\pgfkeys{/pgf/fpu=false}}, |
| 174 |
] |
| 175 |
\begingroup |
| 176 |
\pgfkeys{/pgf/fpu/install only={divide}} |
| 177 |
\pgfmathparse{12.34/0.001234}\pgfmathresult (good) |
| 178 |
\pgfmathparse{12/4}\pgfmathresult (bad) |
| 179 |
\endgroup |
| 180 |
\end{codeexample} |
| 181 |
% |
| 182 |
This key is introduced in \pgfname v3.1.6 and marked stable since \pgfname |
| 183 |
v3.1.8. |
| 184 |
\end{key} |
| 185 |
|
| 186 |
|
| 187 |
\subsection{Comparison to the fixed point arithmetic library} |
| 188 |
|
| 189 |
There are other ways to increase the data range and/or the precision of |
| 190 |
\pgfname's math parser. One of them is the |fp| package, preferable combined |
| 191 |
with \pgfname's |fixedpointarithmetic| library. The differences between the FPU |
| 192 |
and |fp| are: |
| 193 |
% |
| 194 |
\begin{itemize} |
| 195 |
\item The FPU supports at least the complete IEEE double precision number |
| 196 |
range, while |fp| covers only numbers of magnitude |
| 197 |
$\pm\pgfmathprintnumber{1e17}$. |
| 198 |
\item The FPU has a uniform relative precision of about 4--5 correct |
| 199 |
digits. The fixed point library has an absolute precision which may |
| 200 |
perform good in many cases -- but will fail at the ends of the data |
| 201 |
range (as every fixed point routines does). |
| 202 |
\item The FPU has potential to be faster than |fp| as it has access to fast |
| 203 |
mantissa operations using \pgfname's math capabilities (which use \TeX\ |
| 204 |
registers). |
| 205 |
\end{itemize} |
| 206 |
|
| 207 |
|
| 208 |
\subsection{Command Reference and Programmer's Manual} |
| 209 |
|
| 210 |
\subsubsection{Creating and Converting Floats} |
| 211 |
|
| 212 |
\begin{command}{\pgfmathfloatparsenumber\marg{x}} |
| 213 |
Reads a number of arbitrary magnitude and precision and stores its result |
| 214 |
into |\pgfmathresult| as floating point number $m \cdot 10^e$ with mantissa |
| 215 |
and exponent base~$10$. |
| 216 |
|
| 217 |
The algorithm and the storage format is purely text-based. The number is |
| 218 |
stored as a triple of flags, a positive mantissa and an exponent, such as |
| 219 |
% |
| 220 |
\begin{codeexample}[] |
| 221 |
\pgfmathfloatparsenumber{2} |
| 222 |
\pgfmathresult |
| 223 |
\end{codeexample} |
| 224 |
% |
| 225 |
Please do not rely on the low-level representation here, use |
| 226 |
|\pgfmathfloattomacro| (and its variants) and |\pgfmathfloatcreate| if you |
| 227 |
want to work with these components. |
| 228 |
|
| 229 |
The flags encoded in |\pgfmathresult| are represented as a digit where |
| 230 |
`$0$' stands for the number $\pm 0\cdot 10^0$, `$1$' stands for a positive |
| 231 |
sign, `$2$' means a negative sign, `$3$' stands for `not a number', `$4$' |
| 232 |
means $+\infty$ and `$5$' stands for $-\infty$. |
| 233 |
|
| 234 |
The mantissa is a normalized real number $m \in \mathbb{R}$, $1 \le m < |
| 235 |
10$. It always contains a period and at least one digit after the period. |
| 236 |
The exponent is an integer. |
| 237 |
|
| 238 |
Examples: |
| 239 |
% |
| 240 |
\begin{codeexample}[] |
| 241 |
\pgfmathfloatparsenumber{0} |
| 242 |
\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} |
| 243 |
Flags: \F; Mantissa \M; Exponent \E. |
| 244 |
\end{codeexample} |
| 245 |
|
| 246 |
\begin{codeexample}[] |
| 247 |
\pgfmathfloatparsenumber{0.2} |
| 248 |
\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} |
| 249 |
Flags: \F; Mantissa \M; Exponent \E. |
| 250 |
\end{codeexample} |
| 251 |
|
| 252 |
\begin{codeexample}[] |
| 253 |
\pgfmathfloatparsenumber{42} |
| 254 |
\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} |
| 255 |
Flags: \F; Mantissa \M; Exponent \E. |
| 256 |
\end{codeexample} |
| 257 |
|
| 258 |
\begin{codeexample}[] |
| 259 |
\pgfmathfloatparsenumber{20.5E+2} |
| 260 |
\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} |
| 261 |
Flags: \F; Mantissa \M; Exponent \E. |
| 262 |
\end{codeexample} |
| 263 |
|
| 264 |
\begin{codeexample}[] |
| 265 |
\pgfmathfloatparsenumber{1e6} |
| 266 |
\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} |
| 267 |
Flags: \F; Mantissa \M; Exponent \E. |
| 268 |
\end{codeexample} |
| 269 |
|
| 270 |
\begin{codeexample}[] |
| 271 |
\pgfmathfloatparsenumber{5.21513e-11} |
| 272 |
\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} |
| 273 |
Flags: \F; Mantissa \M; Exponent \E. |
| 274 |
\end{codeexample} |
| 275 |
% |
| 276 |
The argument \meta{x} may be given in fixed point format or the scientific |
| 277 |
``e'' (or ``E'') notation. The scientific notation does not necessarily |
| 278 |
need to be normalized. The supported exponent range is (currently) only |
| 279 |
limited by the \TeX-integer range (which uses 31 bit integer numbers). |
| 280 |
\end{command} |
| 281 |
|
| 282 |
\begin{key}{/pgf/fpu/handlers/empty number=\marg{input}\marg{unreadable part}} |
| 283 |
This command key is invoked in case an empty string is parsed inside of |
| 284 |
|\pgfmathfloatparsenumber|. You can overwrite it to assign a replacement |
| 285 |
|\pgfmathresult| (in float!). |
| 286 |
|
| 287 |
The initial setting is to invoke |invalid number|, see below. |
| 288 |
\end{key} |
| 289 |
|
| 290 |
\begin{key}{/pgf/fpu/handlers/invalid number=\marg{input}\marg{unreadable part}} |
| 291 |
This command key is invoked in case an invalid string is parsed inside of |
| 292 |
|\pgfmathfloatparsenumber|. You can overwrite it to assign a replacement |
| 293 |
|\pgfmathresult| (in float!). |
| 294 |
|
| 295 |
The initial setting is to generate an error message. |
| 296 |
\end{key} |
| 297 |
|
| 298 |
\begin{key}{/pgf/fpu/handlers/wrong lowlevel format=\marg{input}\marg{unreadable part}} |
| 299 |
This command key is invoked whenever |\pgfmathfloattoregisters| or its |
| 300 |
variants encounter something which is not a properly formatted low-level |
| 301 |
floating point number. As for |invalid number|, this key may assign a new |
| 302 |
|\pgfmathresult| (in floating point) which will be used instead of the |
| 303 |
offending \meta{input}. |
| 304 |
|
| 305 |
The initial setting is to generate an error message. |
| 306 |
\end{key} |
| 307 |
|
| 308 |
\begin{command}{\pgfmathfloatqparsenumber\marg{x}} |
| 309 |
The same as |\pgfmathfloatparsenumber|, but does not perform sanity checking. |
| 310 |
\end{command} |
| 311 |
|
| 312 |
\begin{command}{\pgfmathfloattofixed{\marg{x}}} |
| 313 |
Converts a number in floating point representation to a fixed point number. |
| 314 |
It is a counterpart to |\pgfmathfloatparsenumber|. The algorithm is purely |
| 315 |
text based and defines |\pgfmathresult| as a string sequence which |
| 316 |
represents the floating point number \meta{x} as a fixed point number (of |
| 317 |
arbitrary precision). |
| 318 |
% |
| 319 |
\begin{codeexample}[] |
| 320 |
\pgfmathfloatparsenumber{0.00052} |
| 321 |
\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} |
| 322 |
Flags: \F; Mantissa \M; Exponent \E |
| 323 |
$\to$ |
| 324 |
\pgfmathfloattofixed{\pgfmathresult} |
| 325 |
\pgfmathresult |
| 326 |
\end{codeexample} |
| 327 |
|
| 328 |
\begin{codeexample}[] |
| 329 |
\pgfmathfloatparsenumber{123.456e4} |
| 330 |
\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} |
| 331 |
Flags: \F; Mantissa \M; Exponent \E |
| 332 |
$\to$ |
| 333 |
\pgfmathfloattofixed{\pgfmathresult} |
| 334 |
\pgfmathresult |
| 335 |
\end{codeexample} |
| 336 |
% |
| 337 |
\end{command} |
| 338 |
|
| 339 |
\begin{command}{\pgfmathfloattoint\marg{x}} |
| 340 |
Converts a number from low-level floating point representation to an |
| 341 |
integer (by truncating the fractional part). |
| 342 |
% |
| 343 |
\begin{codeexample}[] |
| 344 |
\pgfmathfloatparsenumber{123456} |
| 345 |
\pgfmathfloattoint{\pgfmathresult} |
| 346 |
\pgfmathresult |
| 347 |
\end{codeexample} |
| 348 |
|
| 349 |
See also |\pgfmathfloatint| which returns the result as float. |
| 350 |
\end{command} |
| 351 |
|
| 352 |
\begin{command}{\pgfmathfloattosci\marg{float}} |
| 353 |
Converts a number from low-level floating point representation to |
| 354 |
scientific format, $1.234e4$. The result will be assigned to the macro |
| 355 |
|\pgfmathresult|. |
| 356 |
\end{command} |
| 357 |
|
| 358 |
\begin{command}{\pgfmathfloatvalueof\marg{float}} |
| 359 |
Expands a number from low-level floating point representation to scientific |
| 360 |
format, $1.234e4$. |
| 361 |
|
| 362 |
Use |\pgfmathfloatvalueof| in contexts where only expandable macros are |
| 363 |
allowed. |
| 364 |
\end{command} |
| 365 |
|
| 366 |
\begin{command}{\pgfmathfloatcreate{\marg{flags}}{\marg{mantissa}}{\marg{exponent}}} |
| 367 |
Defines |\pgfmathresult| as the floating point number encoded by |
| 368 |
\meta{flags}, \meta{mantissa} and \meta{exponent}. |
| 369 |
|
| 370 |
All arguments are characters and will be expanded using |\edef|. |
| 371 |
% |
| 372 |
\begin{codeexample}[] |
| 373 |
\pgfmathfloatcreate{1}{1.0}{327} |
| 374 |
\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} |
| 375 |
Flags: \F; Mantissa \M; Exponent \E |
| 376 |
\end{codeexample} |
| 377 |
% |
| 378 |
\end{command} |
| 379 |
|
| 380 |
\begin{command}{\pgfmathfloatifflags\marg{floating point number}\marg{flag}\marg{true-code}\marg{false-code}} |
| 381 |
Invokes \meta{true-code} if the flag of \meta{floating point number} equals |
| 382 |
\meta{flag} and \meta{false-code} otherwise. |
| 383 |
|
| 384 |
The argument \meta{flag} can be one of |
| 385 |
% |
| 386 |
\begin{description} |
| 387 |
\item[0] to test for zero, |
| 388 |
\item[1] to test for positive numbers, |
| 389 |
\item[+] to test for positive numbers, |
| 390 |
\item[2] to test for negative numbers, |
| 391 |
\item[-] to test for negative numbers, |
| 392 |
\item[3] for ``not-a-number'', |
| 393 |
\item[4] for $+\infty$, |
| 394 |
\item[5] for $-\infty$. |
| 395 |
\end{description} |
| 396 |
% |
| 397 |
\begin{codeexample}[preamble={\usetikzlibrary{fpu}}] |
| 398 |
\pgfmathfloatparsenumber{42} |
| 399 |
\pgfmathfloatifflags{\pgfmathresult}{0}{It's zero!}{It's not zero!} |
| 400 |
\pgfmathfloatifflags{\pgfmathresult}{1}{It's positive!}{It's not positive!} |
| 401 |
\pgfmathfloatifflags{\pgfmathresult}{2}{It's negative!}{It's not negative!} |
| 402 |
|
| 403 |
% or, equivalently |
| 404 |
\pgfmathfloatifflags{\pgfmathresult}{+}{It's positive!}{It's not positive!} |
| 405 |
\pgfmathfloatifflags{\pgfmathresult}{-}{It's negative!}{It's not negative!} |
| 406 |
\end{codeexample} |
| 407 |
% |
| 408 |
\end{command} |
| 409 |
|
| 410 |
\begin{command}{\pgfmathfloattomacro{\marg{x}}{\marg{flagsmacro}}{\marg{mantissamacro}}{\marg{exponentmacro}}} |
| 411 |
Extracts the flags of a floating point number \meta{x} to |
| 412 |
\meta{flagsmacro}, the mantissa to \meta{mantissamacro} and the exponent to |
| 413 |
\meta{exponentmacro}. |
| 414 |
\end{command} |
| 415 |
|
| 416 |
\begin{command}{\pgfmathfloattoregisters{\marg{x}}{\marg{flagscount}}{\marg{mantissadimen}}{\marg{exponentcount}}} |
| 417 |
Takes a floating point number \meta{x} as input and writes flags to count |
| 418 |
register \meta{flagscount}, mantissa to dimen register \meta{mantissadimen} |
| 419 |
and exponent to count register \meta{exponentcount}. |
| 420 |
|
| 421 |
Please note that this method rounds the mantissa to \TeX-precision. |
| 422 |
\end{command} |
| 423 |
|
| 424 |
\begin{command}{\pgfmathfloattoregisterstok{\marg{x}}{\marg{flagscount}}{\marg{mantissatoks}}{\marg{exponentcount}}} |
| 425 |
A variant of |\pgfmathfloattoregisters| which writes the mantissa into a |
| 426 |
token register. It maintains the full input precision. |
| 427 |
\end{command} |
| 428 |
|
| 429 |
\begin{command}{\pgfmathfloatgetflags{\marg{x}}{\marg{flagscount}}} |
| 430 |
Extracts the flags of \meta{x} into the count register \meta{flagscount}. |
| 431 |
\end{command} |
| 432 |
|
| 433 |
\begin{command}{\pgfmathfloatgetflagstomacro{\marg{x}}{\marg{macro}}} |
| 434 |
Extracts the flags of \meta{x} into the macro \meta{macro}. |
| 435 |
\end{command} |
| 436 |
|
| 437 |
\begin{command}{\pgfmathfloatgetmantissa{\marg{x}}{\marg{mantissadimen}}} |
| 438 |
Extracts the mantissa of \meta{x} into the dimen register |
| 439 |
\meta{mantissadimen}. |
| 440 |
\end{command} |
| 441 |
|
| 442 |
\begin{command}{\pgfmathfloatgetmantissatok{\marg{x}}{\marg{mantissatoks}}} |
| 443 |
Extracts the mantissa of \meta{x} into the token register |
| 444 |
\meta{mantissatoks}. |
| 445 |
\end{command} |
| 446 |
|
| 447 |
\begin{command}{\pgfmathfloatgetexponent{\marg{x}}{\marg{exponentcount}}} |
| 448 |
Extracts the exponent of \meta{x} into the count register |
| 449 |
\meta{exponentcount}. |
| 450 |
\end{command} |
| 451 |
|
| 452 |
|
| 453 |
\subsubsection{Symbolic Rounding Operations} |
| 454 |
|
| 455 |
Commands in this section constitute the basic level implementations of the |
| 456 |
rounding routines. They work symbolically, i.e.\ they operate on text, not on |
| 457 |
numbers and allow arbitrarily large numbers. |
| 458 |
|
| 459 |
\begin{command}{\pgfmathroundto{\marg{x}}} |
| 460 |
Rounds a fixed point number to prescribed precision and writes the result |
| 461 |
to |\pgfmathresult|. |
| 462 |
|
| 463 |
The desired precision can be configured with |
| 464 |
|/pgf/number format/precision|, see section~\ref{pgfmath-numberprinting}. |
| 465 |
This section does also contain application examples. |
| 466 |
|
| 467 |
Any trailing zeros after the period are discarded. The algorithm is purely |
| 468 |
text based and allows to deal with precisions beyond \TeX's fixed point |
| 469 |
support. |
| 470 |
|
| 471 |
As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod| will |
| 472 |
be set to true if and only if the resulting mantissa has a period. |
| 473 |
Furthermore, |\ifpgfmathfloatroundmayneedrenormalize| will be set to true |
| 474 |
if and only if the rounding result's floating point representation would |
| 475 |
have a larger exponent than \meta{x}. |
| 476 |
% |
| 477 |
\begin{codeexample}[] |
| 478 |
\pgfmathroundto{1} |
| 479 |
\pgfmathresult |
| 480 |
\end{codeexample} |
| 481 |
% |
| 482 |
\begin{codeexample}[] |
| 483 |
\pgfmathroundto{4.685} |
| 484 |
\pgfmathresult |
| 485 |
\end{codeexample} |
| 486 |
% |
| 487 |
\begin{codeexample}[] |
| 488 |
\pgfmathroundto{19999.9996} |
| 489 |
\pgfmathresult |
| 490 |
\end{codeexample} |
| 491 |
% |
| 492 |
\end{command} |
| 493 |
|
| 494 |
\begin{command}{\pgfmathroundtozerofill{\marg{x}}} |
| 495 |
A variant of |\pgfmathroundto| which always uses a fixed number of digits |
| 496 |
behind the period. It fills missing digits with zeros. |
| 497 |
% |
| 498 |
\begin{codeexample}[] |
| 499 |
\pgfmathroundtozerofill{1} |
| 500 |
\pgfmathresult |
| 501 |
\end{codeexample} |
| 502 |
% |
| 503 |
\begin{codeexample}[] |
| 504 |
\pgfmathroundto{4.685} |
| 505 |
\pgfmathresult |
| 506 |
\end{codeexample} |
| 507 |
% |
| 508 |
\begin{codeexample}[] |
| 509 |
\pgfmathroundtozerofill{19999.9996} |
| 510 |
\pgfmathresult |
| 511 |
\end{codeexample} |
| 512 |
% |
| 513 |
\end{command} |
| 514 |
|
| 515 |
\begin{command}{\pgfmathfloatround{\marg{x}}} |
| 516 |
Rounds a normalized floating point number to a prescribed precision and |
| 517 |
writes the result to |\pgfmathresult|. |
| 518 |
|
| 519 |
The desired precision can be configured with |
| 520 |
|/pgf/number format/precision|, see section~\ref{pgfmath-numberprinting}. |
| 521 |
|
| 522 |
This method employs |\pgfmathroundto| to round the mantissa and applies |
| 523 |
renormalization if necessary. |
| 524 |
|
| 525 |
As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod| will |
| 526 |
be set to true if and only if the resulting mantissa has a period. |
| 527 |
% |
| 528 |
\begin{codeexample}[] |
| 529 |
\pgfmathfloatparsenumber{52.5864} |
| 530 |
\pgfmathfloatround{\pgfmathresult} |
| 531 |
\pgfmathfloattosci{\pgfmathresult} |
| 532 |
\pgfmathresult |
| 533 |
\end{codeexample} |
| 534 |
% |
| 535 |
\begin{codeexample}[] |
| 536 |
\pgfmathfloatparsenumber{9.995} |
| 537 |
\pgfmathfloatround{\pgfmathresult} |
| 538 |
\pgfmathfloattosci{\pgfmathresult} |
| 539 |
\pgfmathresult |
| 540 |
\end{codeexample} |
| 541 |
% |
| 542 |
\end{command} |
| 543 |
|
| 544 |
\begin{command}{\pgfmathfloatroundzerofill{\marg{x}}} |
| 545 |
A variant of |\pgfmathfloatround| produces always the same number of digits |
| 546 |
after the period (it includes zeros if necessary). |
| 547 |
% |
| 548 |
\begin{codeexample}[] |
| 549 |
\pgfmathfloatparsenumber{52.5864} |
| 550 |
\pgfmathfloatroundzerofill{\pgfmathresult} |
| 551 |
\pgfmathfloattosci{\pgfmathresult} |
| 552 |
\pgfmathresult |
| 553 |
\end{codeexample} |
| 554 |
% |
| 555 |
\begin{codeexample}[] |
| 556 |
\pgfmathfloatparsenumber{9.995} |
| 557 |
\pgfmathfloatroundzerofill{\pgfmathresult} |
| 558 |
\pgfmathfloattosci{\pgfmathresult} |
| 559 |
\pgfmathresult |
| 560 |
\end{codeexample} |
| 561 |
% |
| 562 |
\end{command} |
| 563 |
|
| 564 |
|
| 565 |
\subsubsection{Math Operations Commands} |
| 566 |
|
| 567 |
This section describes some of the replacement commands in more detail. |
| 568 |
|
| 569 |
Please note that these commands can be used even if the |fpu| as such has not |
| 570 |
been activated -- it is sufficient to load the library. |
| 571 |
|
| 572 |
\begin{command}{\pgfmathfloat\meta{op}} |
| 573 |
Methods of this form constitute the replacement operations where \meta{op} |
| 574 |
can be any of the well-known math operations. |
| 575 |
|
| 576 |
Thus, \declareandlabel{\pgfmathfloatadd} is the counterpart for |
| 577 |
|\pgfmathadd| and so on. The semantics and number of arguments is the same, |
| 578 |
but all input and output arguments are \emph{expected} to be floating point |
| 579 |
numbers. |
| 580 |
\end{command} |
| 581 |
|
| 582 |
\begin{command}{\pgfmathfloattoextentedprecision{\marg{x}}} |
| 583 |
Renormalizes \meta{x} to extended precision mantissa, meaning $100 \le m < |
| 584 |
1000$ instead of $1 \le m < 10$. |
| 585 |
|
| 586 |
The ``extended precision'' means we have higher accuracy when we apply |
| 587 |
pgfmath operations to mantissas. |
| 588 |
|
| 589 |
The input argument is expected to be a normalized floating point number; |
| 590 |
the output argument is a non-normalized floating point number (well, |
| 591 |
normalized to extended precision). |
| 592 |
|
| 593 |
The operation is supposed to be very fast. |
| 594 |
\end{command} |
| 595 |
|
| 596 |
\begin{command}{\pgfmathfloatsetextprecision\marg{shift}} |
| 597 |
Sets the precision used inside of |\pgfmathfloattoextentedprecision| to |
| 598 |
\meta{shift}. |
| 599 |
|
| 600 |
The different choices are |
| 601 |
|
| 602 |
\begin{tabular}{llrll} |
| 603 |
0 & normalization to & $0$ & $\le m < 1$ & (disable extended precision) \\ |
| 604 |
1 & normalization to & $10$ & $\le m < 100$ & \\ |
| 605 |
2 & normalization to & $100$ & $\le m < 1000$ & (default of |\pgfmathfloattoextentedprecision|) \\ |
| 606 |
3 & normalization to & $1000$ & $\le m < 10000$ & \\ |
| 607 |
\end{tabular} |
| 608 |
\end{command} |
| 609 |
|
| 610 |
\begin{command}{\pgfmathfloatlessthan{\marg{x}}{\marg{y}}} |
| 611 |
Defines |\pgfmathresult| as $1.0$ if $\meta{x} < \meta{y}$, but $0.0$ |
| 612 |
otherwise. It also sets the global \TeX-boolean |\pgfmathfloatcomparison| |
| 613 |
accordingly. The arguments \meta{x} and \meta{y} are expected to be numbers |
| 614 |
which have already been processed by |\pgfmathfloatparsenumber|. Arithmetic |
| 615 |
is carried out using \TeX-registers for exponent- and mantissa comparison. |
| 616 |
\end{command} |
| 617 |
|
| 618 |
\begin{command}{\pgfmathfloatmultiplyfixed\marg{float}\marg{fixed}} |
| 619 |
Defines |\pgfmathresult| to be $\meta{float} \cdot \meta{fixed}$ where |
| 620 |
\meta{float} is a floating point number and \meta{fixed} is a fixed point |
| 621 |
number. The computation is performed in floating point arithmetic, that |
| 622 |
means we compute $m \cdot \meta{fixed}$ and renormalize the result where |
| 623 |
$m$ is the mantissa of \meta{float}. |
| 624 |
|
| 625 |
This operation renormalizes \meta{float} with |
| 626 |
|\pgfmathfloattoextentedprecision| before the operation, that means it is |
| 627 |
intended for relatively small arguments of \meta{fixed}. The result is a |
| 628 |
floating point number. |
| 629 |
\end{command} |
| 630 |
|
| 631 |
\begin{command}{\pgfmathfloatifapproxequalrel\marg{a}\marg{b}\marg{true-code}\marg{false-code}} |
| 632 |
Computes the relative error between \meta{a} and \meta{b} (assuming |
| 633 |
\meta{b}$\neq 0$) and invokes \meta{true-code} if the relative error is |
| 634 |
below |/pgf/fpu/rel thresh| and \meta{false-code} if that is not the case. |
| 635 |
|
| 636 |
The input arguments will be parsed with |\pgfmathfloatparsenumber|. |
| 637 |
|
| 638 |
\begin{key}{/pgf/fpu/rel thresh=\marg{number} (initially 1e-4)} |
| 639 |
A threshold used by |\pgfmathfloatifapproxequalrel| to decide whether |
| 640 |
numbers are approximately equal. |
| 641 |
\end{key} |
| 642 |
\end{command} |
| 643 |
|
| 644 |
\begin{command}{\pgfmathfloatshift{\marg{x}}{\marg{num}}} |
| 645 |
Defines |\pgfmathresult| to be $\meta{x} \cdot 10^{\meta{num}}$. The |
| 646 |
operation is an arithmetic shift base ten and modifies only the exponent of |
| 647 |
\meta{x}. The argument \meta{num} is expected to be a (positive or |
| 648 |
negative) integer. |
| 649 |
\end{command} |
| 650 |
|
| 651 |
\begin{command}{\pgfmathfloatabserror\marg{x}\marg{y}} |
| 652 |
Defines |\pgfmathresult| to be the absolute error between two floating |
| 653 |
point numbers $x$ and $y$, $\lvert x - y\rvert $ and returns the result as |
| 654 |
floating point number. |
| 655 |
\end{command} |
| 656 |
|
| 657 |
\begin{command}{\pgfmathfloatrelerror\marg{x}\marg{y}} |
| 658 |
Defines |\pgfmathresult| to be the relative error between two floating |
| 659 |
point numbers $x$ and $y$, $\lvert x - y\rvert / \lvert y \rvert$ and |
| 660 |
returns the result as floating point number. |
| 661 |
\end{command} |
| 662 |
|
| 663 |
\begin{command}{\pgfmathfloatint\marg{x}} |
| 664 |
Returns the integer part of the floating point number \meta{x}, by |
| 665 |
truncating any digits after the period. This methods truncates the absolute |
| 666 |
value $\rvert x \lvert$ to the next smaller integer and restores the |
| 667 |
original sign afterwards. |
| 668 |
|
| 669 |
The result is returned as floating point number as well. |
| 670 |
|
| 671 |
See also |\pgfmathfloattoint| which returns the number in integer format. |
| 672 |
\end{command} |
| 673 |
|
| 674 |
\begin{command}{\pgfmathlog{\marg{x}}} |
| 675 |
Defines |\pgfmathresult| to be the natural logarithm of \meta{x}, |
| 676 |
$\ln(\meta{x})$. This method is logically the same as |\pgfmathln|, but it |
| 677 |
applies floating point arithmetic to read number \meta{x} and employs the |
| 678 |
logarithm identity \[ \ln(m \cdot 10^e) = \ln(m) + e \cdot \ln(10) \] to |
| 679 |
get the result. The factor $\ln(10)$ is a constant, so only $\ln(m)$ with |
| 680 |
$1 \le m < 10$ needs to be computed. This is done using standard pgf math |
| 681 |
operations. |
| 682 |
|
| 683 |
Please note that \meta{x} needs to be a number, expression parsing is not |
| 684 |
possible here. |
| 685 |
|
| 686 |
If \meta{x} is \emph{not} a bounded positive real number (for example |
| 687 |
$\meta{x} \le 0$), |\pgfmathresult| will be \emph{empty}, no error message |
| 688 |
will be generated. |
| 689 |
% |
| 690 |
\begin{codeexample}[preamble={\usetikzlibrary{fpu}}] |
| 691 |
\pgfmathlog{1.452e-7} |
| 692 |
\pgfmathresult |
| 693 |
\end{codeexample} |
| 694 |
% |
| 695 |
\begin{codeexample}[preamble={\usetikzlibrary{fpu}}] |
| 696 |
\pgfmathlog{6.426e+8} |
| 697 |
\pgfmathresult |
| 698 |
\end{codeexample} |
| 699 |
% |
| 700 |
\end{command} |
| 701 |
|
| 702 |
|
| 703 |
\subsubsection{Accessing the Original Math Routines for Programmers} |
| 704 |
|
| 705 |
As soon as the library is loaded, every private math routine will be copied to |
| 706 |
a new name. This allows library and package authors to access the \TeX-register |
| 707 |
based math routines even if the FPU is activated. And, of course, it allows the |
| 708 |
FPU as such to perform its own mantissa computations. |
| 709 |
|
| 710 |
The private implementations of \pgfname\ math commands, which are of the form |
| 711 |
|\pgfmath|\meta{name}|@|, will be available as|\pgfmath@basic@|\meta{name}|@| |
| 712 |
as soon as the library is loaded. |
| 713 |
|
| 714 |
\endgroup |