1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2%%
3%%  bigcomplex.tex       LiDIA documentation
4%%
5%%  This file contains the documentation of the class bigcomplex
6%%
7%%  Copyright   (c)   1995   by  LiDIA-Group
8%%
9%%  Authors: Thomas Papanikolaou
10%%
11
12\newcommand{\real}{\mathit{re}}
13\newcommand{\imag}{\mathit{im}}
14
15
16%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17
18\NAME
19
20\CLASS{bigcomplex} \dotfill multiprecision complex floating-point arithmetic
21
22
23%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
24
25\ABSTRACT
26
27\code{bigcomplex} is a class for doing multiprecision complex floating point arithmetic.  It
28supports for example arithmetic operations, comparisons and basic triginometric functions.
29
30
31%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
32
33\DESCRIPTION
34
35A \code{bigcomplex} is a pair of two \code{bigfloat}s $(\real, \imag)$, where $\real$ is called
36the \emph{real part} and $\imag$ the \emph{imaginary part}.  This pair represents the complex
37number $\real + \imag \cdot i$, where $i$ is the imaginary unit.  Before declaring a
38\code{bigcomplex} it is possible to set the decimal precision of the \code{bigfloat}s $(\real,
39\imag)$ to $p$ by \code{bigcomplex::precision($p$)} or by \code{bigfloat::precision($p$)}.  Both
40calls have the same effect and set the \code{bigfloat} precision to $p$ (compare class
41\code{bigfloat}, page \pageref{class:bigfloat}).
42
43If the precision has not been set, a default precision of $t = 5$ \code{bigint} base digits is
44used.
45
46
47%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
48
49\CONS
50
51\begin{fcode}{ct}{bigcomplex}{}
52  Initializes with $0$.
53\end{fcode}
54
55\begin{fcode}{ct}{bigcomplex}{const bigfloat & $x$}
56  initializes the real part with $x$, the imaginary part with $0$.
57\end{fcode}
58
59\begin{fcode}{ct}{bigcomplex}{const bigcomplex & $z$}
60  initializes with $z$.
61\end{fcode}
62
63\begin{fcode}{ct}{bigcomplex}{const bigfloat & $\real$, const bigfloat & $\imag$}
64  initializes the real with $\real$ and the imaginary part with $\imag$.
65\end{fcode}
66
67\begin{fcode}{dt}{~bigcomplex}{}
68\end{fcode}
69
70
71%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
72
73\INIT
74
75\begin{fcode}{static void}{precision}{long $p$}
76  sets the global decimal precision of the \code{bigfloat}s $\real, \imag$ to $p$
77  decimal places (compare \code{bigfloat}).  Note that the \code{bigfloat} precision is set
78  globally to $p$ by this call.  Whenever necessary internal computations are done with a higher
79  precision.
80\end{fcode}
81
82\begin{fcode}{static void}{mode}{int $m$}
83  sets the rounding mode for the normalization routine according to the IEEE standard (see
84  \cite{IEEE:754}).  The following modes are available:
85  \begin{itemize}
86  \item \code{MP_TRUNC}: round to zero.
87  \item \code{MP_RND}: round to nearest.  If there are two possibilities to do this, round to even.
88  \item \code{MP_RND_UP} round to $+\infty$.
89  \item \code{MP_RND_DOWN} round to $-\infty$.
90  \end{itemize}
91\end{fcode}
92
93
94%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
95
96\TYPE
97
98Before assigning a \code{bigcomplex} to a \code{bigfloat} it is often useful to check whether
99the assignment can be done without error, i.e. whether the imaginary part $\imag$ is zero.
100
101
102\begin{fcode}{bool}{is_bigfloat}{const bigcomplex &}
103  returns \TRUE if the imaginary part is zero, \FALSE otherwise.
104\end{fcode}
105
106% \begin{fcode}{bool}{is_double}{const bigcomplex &}%
107%   returns \TRUE, if the imaginary part is zero and the real part is not to
108%   large to be stored in a double variable, \FALSE otherwise.
109% \end{fcode}
110
111
112%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
113
114\ASGN
115
116Let $x$ be of type \code{bigcomplex}.  The operator \code{=} is overloaded.  The user may also
117use the following object methods for assignment:
118
119\begin{fcode}{void}{$x$.assign_zero}{}
120  $x \assign 0$.
121\end{fcode}
122
123\begin{fcode}{void}{$x$.assign_one}{}
124  $x \assign 1$.
125\end{fcode}
126
127\begin{fcode}{void}{$x$.assign}{const bigfloat & $y$}
128  $x \assign y$.
129\end{fcode}
130
131\begin{fcode}{void}{$x$.assign}{const bigfloat & $y$, const bigfloat & $z$}
132  $x \assign y + z \cdot i$.
133\end{fcode}
134
135\begin{fcode}{void}{$x$.assign}{const bigcomplex & $y$}
136  $x \assign y$.
137\end{fcode}
138
139
140%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
141
142\ACCS
143
144Let $x$ be of type \code{bigcomplex}.
145
146\begin{cfcode}{const bigfloat &}{$x$.real}{}\end{cfcode}
147\begin{fcode}{const bigfloat &}{real}{const bigcomplex & $x$}
148  returns the real part of $x$.
149\end{fcode}
150
151\begin{cfcode}{const bigfloat &}{$x$.imag}{}\end{cfcode}
152\begin{fcode}{const bigfloat &}{imag}{const bigcomplex & $x$}
153  returns the imaginary part of $x$.
154\end{fcode}
155
156
157%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
158
159\MODF
160
161\begin{fcode}{void}{$x$.negate}{}
162  $x \assign -x$.
163\end{fcode}
164
165\begin{fcode}{void}{$x$.invert}{}
166  $x \assign 1 / x$ if $x \neq 0$.  Otherwise the \LEH will be invoked.
167\end{fcode}
168
169
170%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
171
172\ARTH
173
174The following operators are overloaded and can be used in exactly the same way as in C++:
175
176\begin{center}
177  \code{(unary) -}\\
178  \code{(binary) +, -, *, /}\\
179  \code{(binary with assignment) +=, -=, *=, /=}
180\end{center}
181
182\begin{fcode}{void}{negate}{bigcomplex & $x$, const bigcomplex & $y$}
183  $x \assign -y$.
184\end{fcode}
185
186\begin{fcode}{void}{add}{bigcomplex & $x$, const bigcomplex & $y$, const bigcomplex & $z$}\end{fcode}
187\begin{fcode}{void}{add}{bigcomplex & $x$, const bigcomplex & $y$, const bigfloat & $z$}\end{fcode}
188\begin{fcode}{void}{add}{bigcomplex & $x$, const bigfloat & $y$, const bigcomplex & $z$}
189  $x \assign y + z$.
190\end{fcode}
191
192\begin{fcode}{void}{subtract}{bigcomplex & $x$, const bigcomplex & $y$, const bigcomplex & $z$}\end{fcode}
193\begin{fcode}{void}{subtract}{bigcomplex & $x$, const bigcomplex & $y$, const bigfloat & $z$}\end{fcode}
194\begin{fcode}{void}{subtract}{bigcomplex & $x$, const bigfloat & $y$, const bigcomplex & $z$}
195  $x \assign y - z$.
196\end{fcode}
197
198\begin{fcode}{void}{multiply}{bigcomplex & $x$, const bigcomplex & $y$, const bigcomplex & $z$}\end{fcode}
199\begin{fcode}{void}{multiply}{bigcomplex & $x$, const bigcomplex & $y$, const bigfloat & $z$}\end{fcode}
200\begin{fcode}{void}{multiply}{bigcomplex & $x$, const bigfloat & $y$, const bigcomplex & $z$}
201  $x \assign y \cdot z$.
202\end{fcode}
203
204\begin{fcode}{void}{square}{bigcomplex & $x$, const bigcomplex & $y$}
205  $x \assign y^2$.
206\end{fcode}
207
208\begin{fcode}{bigcomplex}{square}{const bigcomplex & $x$}
209  returns $x^2$.
210\end{fcode}
211
212\begin{fcode}{void}{divide}{bigcomplex & $x$, const bigcomplex & $y$, const bigcomplex & $z$}\end{fcode}
213\begin{fcode}{void}{divide}{bigcomplex & $x$, const bigcomplex & $y$, const bigfloat & $z$}\end{fcode}
214\begin{fcode}{void}{divide}{bigcomplex & $x$, const bigfloat & $y$, const bigcomplex & $z$}
215  $x \assign y / z$ if $z \neq 0$.  Otherwise the \LEH will be invoked.
216\end{fcode}
217
218\begin{fcode}{void}{invert}{bigcomplex & $x$, const bigcomplex & $y$}
219  $x \assign 1 / y$ if $y \neq 0$.  Otherwise the \LEH will be invoked.
220\end{fcode}
221
222\begin{fcode}{bigcomplex}{inverse}{const bigcomplex & $x$}
223  returns $1 / x$ if $x \neq 0$.  Otherwise the \LEH will be invoked.
224\end{fcode}
225
226\begin{fcode}{void}{sqrt}{bigcomplex & $x$, const bigcomplex & $y$}
227  $x \assign \sqrt{y}$.
228\end{fcode}
229
230\begin{fcode}{bigcomplex}{sqrt}{const bigcomplex & $x$}
231  returns $\sqrt{x}$.
232\end{fcode}
233
234\begin{fcode}{void}{power}{bigcomplex & $x$, const bigcomplex & $y$, const bigcomplex & $z$}\end{fcode}
235\begin{fcode}{void}{power}{bigcomplex & $x$, const bigcomplex & $y$, const bigfloat & $z$}
236  sets $x \assign y^z$.
237\end{fcode}
238
239\begin{fcode}{void}{power}{bigcomplex & $x$, const bigcomplex & $y$, long $i$}
240  sets $x \assign y^i$.
241\end{fcode}
242
243\begin{fcode}{bigcomplex}{power}{const bigcomplex & $y$, const bigcomplex & $z$}\end{fcode}
244\begin{fcode}{bigcomplex}{power}{const bigcomplex & $y$, const bigfloat & $z$}
245  returns $y^z$.
246\end{fcode}
247
248\begin{fcode}{bigcomplex}{power}{const bigcomplex & $y$, long $i$}
249  returns $y^i$.
250\end{fcode}
251
252
253%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
254
255\COMP
256
257\code{bigcomplex} supports the binary operators \code{==} and \code{!=}.  Furthermore there
258exists the following function:
259
260\begin{cfcode}{bool}{$x$.is_zero}{}
261  returns \TRUE if $x$ is zero, \FALSE otherwise.
262\end{cfcode}
263
264\begin{cfcode}{bool}{$x$.is_one}{}
265  returns \TRUE if $x$ is $1$, \FALSE otherwise.
266\end{cfcode}
267
268\begin{cfcode}{bool}{$x$.is_approx_zero}{}
269  returns \TRUE if the real and the imaginary part of $x$ are approximately zero (compare class
270  \code{bigfloat}, \FALSE otherwise.
271\end{cfcode}
272
273\begin{cfcode}{bool}{$x$.is_real}{}
274  returns \TRUE if the imaginary part of $x$ is zero, \FALSE otherwise.
275\end{cfcode}
276
277\begin{cfcode}{bool}{$x$.is_approx_real}{}
278  returns \TRUE if the imaginary part of $x$ is approximately zero (compare class
279  \code{bigfloat}, \FALSE otherwise.
280\end{cfcode}
281
282\begin{cfcode}{bool}{$x$.is_imaginary}{}
283  returns \TRUE if the real part of $x$ is zero, \FALSE otherwise.
284\end{cfcode}
285
286\begin{cfcode}{bool}{$x$.is_approx_imaginary}{}
287  returns \TRUE if the real part of $x$ is approximately zero (compare class \code{bigfloat},
288  \FALSE otherwise.
289\end{cfcode}
290
291\begin{cfcode}{bool}{$x$.is_equal}{const bigcomplex & $y$}
292  returns \TRUE if $x = y$, \FALSE otherwise.
293\end{cfcode}
294
295
296%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
297
298\BASIC
299
300\begin{fcode}{void}{conj}{bigcomplex & $x$, const bigcomplex & $y$}
301  returns $x$ as the complex conjugate of $y$.
302\end{fcode}
303
304\begin{fcode}{bigcomplex}{conj}{const bigcomplex & $x$}
305  returns the complex conjugate of $x$.
306\end{fcode}
307
308\begin{fcode}{void}{exp}{bigcomplex & $x$, const bigcomplex & $y$}
309  $x \assign \exp(x) = e^y$ ($e \approx 2.71828\dots$).
310\end{fcode}
311
312\begin{fcode}{bigcomplex}{exp}{const bigcomplex & $x$}
313  returns $e^x$.
314\end{fcode}
315
316\begin{fcode}{void}{log}{bigcomplex & $x$, const bigcomplex & $y$}
317  $x \assign \log(y)$ (natural logarithm to base $e \approx 2.71828\dots$).
318\end{fcode}
319
320\begin{fcode}{bigcomplex}{log}{const bigcomplex & $x$}
321  returns $ \log(x)$.
322\end{fcode}
323
324\begin{fcode}{void}{polar}{bigcomplex & $x$, const bigfloat & $r$, const bigfloat & $t$}
325  $x \assign r \cdot \cos(t) + r \cdot \sin(t) \cdot i$.
326\end{fcode}
327
328\begin{fcode}{bigcomplex}{polar}{const bigfloat & $r$, const bigfloat & $t$}
329  returns the complex number $r \cdot \cos(t) + r \cdot \sin(t) \cdot i$.
330\end{fcode}
331
332\begin{fcode}{bigfloat}{abs}{const bigcomplex & $x$}
333  returns $\sqrt{\Re^2 x + \Im^2 x}$.
334\end{fcode}
335
336\begin{fcode}{bigfloat}{hypot}{const bigcomplex & $x$}
337  returns $|x|$.
338\end{fcode}
339
340\begin{fcode}{bigfloat}{arg}{const bigcomplex & $x$}
341  returns $\arctan(\Im x / \Re x)$.
342\end{fcode}
343
344\begin{fcode}{bigfloat}{norm}{const bigcomplex & $x$}
345  returns the norm of $x$.
346\end{fcode}
347
348\begin{fcode}{void}{swap}{bigcomplex & $x$, bigcomplex & $y$}
349  exchanges the values of $x$ and $y$.
350\end{fcode}
351
352
353%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
354
355\STITLE{(Inverse) Trigonometric Functions}
356
357\begin{fcode}{void}{sin}{bigcomplex & $x$, const bigcomplex & $y$}
358  $x \assign \sin(y)$.
359\end{fcode}
360
361\begin{fcode}{bigcomplex}{sin}{const bigcomplex & $x$}
362  returns $\sin(x)$.
363\end{fcode}
364
365\begin{fcode}{void}{cos}{bigcomplex & $x$, const bigcomplex & $y$}
366  $x \assign \cos(y)$.
367\end{fcode}
368
369\begin{fcode}{bigcomplex}{cos}{const bigcomplex & $x$}
370  returns $\cos(x)$.
371\end{fcode}
372
373
374%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
375
376\STITLE{(Inverse) Hyperbolic Trigonometric Functions}
377
378\begin{fcode}{void}{sinh}{bigcomplex & $x$, const bigcomplex & $y$}
379  $x \assign \sinh(y)$.
380\end{fcode}
381
382\begin{fcode}{bigcomplex}{sinh}{const bigcomplex & $x$}
383  returns $\sinh(x)$.
384\end{fcode}
385
386\begin{fcode}{void}{cosh}{bigcomplex & $x$, const bigcomplex & $x$}
387  $x \assign \cosh(y)$.
388\end{fcode}
389
390\begin{fcode}{bigcomplex}{cosh}{const bigcomplex & $x$}
391  returns $\cosh(x)$.
392\end{fcode}
393
394
395%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
396
397\IO
398
399\code{istream} operator \code{>>} and \code{ostream} operator \code{<<} are overloaded and can
400be used in the same way as in C++.  If the imaginary part of the \code{bigcomplex} is zero, then
401input and output of a \code{bigcomplex} may be in one of the following formats:
402\begin{displaymath}
403  \real \text{ or } (\real,0) \enspace,
404\end{displaymath}
405where $\real$ is a \code{bigfloat} in the appropriate format described in the \code{bigfloat}
406class description.  If the imaginary part of the \code{bigfloat} is not zero, then input and
407output have the format
408\begin{displaymath}
409  (\real, \imag)
410\end{displaymath}
411where $\real$ and $\imag$ are \code{bigfloat}s in the appropriate format described in the
412\code{bigfloat} class description.
413
414Note that you have to manage by yourself that successive \code{bigcomplex} numbers have to be
415separated by blanks.
416
417
418%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
419
420\SEEALSO
421
422\SEE{bigfloat}
423
424
425%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
426
427\NOTES
428
429The structure of \code{bigcomplex} is strongly based on AT\&T's and GNU's complex class.
430\code{bigcomplex} is not yet complete.  Further methods will be incorporated in the next
431release.
432
433
434%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
435
436\EXAMPLES
437
438\begin{quote}
439\begin{verbatim}
440#include <LiDIA/bigcomplex.h>
441
442int main()
443{
444    bigcomplex::precision(100);
445
446    bigcomplex a, b, c;
447
448    cout << "Please enter a : "; cin >> a ;
449    cout << "Please enter b : "; cin >> b ;
450    cout << endl;
451    c = a + b;
452    cout << "a + b = " << c << endl;
453}
454\end{verbatim}
455\end{quote}
456
457For further reference please refer to \path{LiDIA/src/simple_classes/bigcomplex_appl.cc}
458
459
460%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
461
462\AUTHOR
463
464Ingrid Biehl, Thomas Papanikolaou
465