PDL::Complex(3pm)

1Complex(3)            User Contributed Perl Documentation           Complex(3)
2
3
4

NAME

6       PDL::Complex - handle complex numbers (DEPRECATED - use native complex)
7

SYNOPSIS

9         use PDL;
10         use PDL::Complex;
11

DESCRIPTION

13       This module is deprecated in favour of using "native complex" data
14       types, e.g.:
15
16         use PDL;
17         my $complex_pdl = cdouble('[1+3i]');
18         print $complex_pdl * pdl('i'); # [-3+i]
19
20       This module features a growing number of functions manipulating complex
21       numbers. These are usually represented as a pair "[ real imag ]" or "[
22       magnitude phase ]". If not explicitly mentioned, the functions can work
23       inplace (not yet implemented!!!) and require rectangular form.
24
25       While there is a procedural interface available ("$x/$y*$c <=> Cmul
26       (Cdiv ($x, $y), $c)"), you can also opt to cast your pdl's into the
27       "PDL::Complex" datatype, which works just like your normal ndarrays,
28       but with all the normal perl operators overloaded.
29
30       The latter means that "sin($x) + $y/$c" will be evaluated using the
31       normal rules of complex numbers, while other pdl functions (like "max")
32       just treat the ndarray as a real-valued ndarray with a lowest dimension
33       of size 2, so "max" will return the maximum of all real and imaginary
34       parts, not the "highest" (for some definition)
35
36   Native complex support
37       2.027 added changes in complex number handling, with support for C99
38       complex floating-point types, and most functions and modules in the
39       core distribution support these as well.
40
41       PDL can now handle complex numbers natively as scalars. This has the
42       advantage that real and complex valued ndarrays have the same
43       dimensions. Consider this when writing code in the future.
44
45       See "re" in PDL::Ops, "im" in PDL::Ops, "abs" in PDL::Ops, "carg" in
46       PDL::Ops, "conj" in PDL::Ops for more.
47

TIPS, TRICKS & CAVEATS

49       •   "i" is a function (not, as of 2.047, a constant) exported by this
50           module, which represents "-1**0.5", i.e. the imaginary unit. it can
51           be used to quickly and conveniently write complex constants like
52           this: "4+3*i".
53
54           NB This will override the PDL::Core function of the same name,
55           which returns a native complex value.
56
57       •   Use "r2C(real-values)" to convert from real to complex, as in "$r =
58           Cpow $cplx, r2C 2". The overloaded operators automatically do that
59           for you, all the other functions, do not. So "Croots 1, 5" will
60           return all the fifths roots of 1+1*i (due to broadcasting).
61
62       •   use "cplx(real-valued-ndarray)" to cast from normal ndarrays into
63           the complex datatype. Use "real(complex-valued-ndarray)" to cast
64           back. This requires a copy, though.
65

EXAMPLE WALK-THROUGH

67       The complex constant five is equal to "pdl(1,0)":
68
69          pdl> p $x = r2C 5
70          5 +0i
71
72       Now calculate the three cubic roots of five:
73
74          pdl> p $r = Croots $x, 3
75          [1.70998 +0i  -0.854988 +1.48088i  -0.854988 -1.48088i]
76
77       Check that these really are the roots:
78
79          pdl> p $r ** 3
80          [5 +0i  5 -1.22465e-15i  5 -7.65714e-15i]
81
82       Duh! Could be better. Now try by multiplying $r three times with
83       itself:
84
85          pdl> p $r*$r*$r
86          [5 +0i  5 -4.72647e-15i  5 -7.53694e-15i]
87
88       Well... maybe "Cpow" (which is used by the "**" operator) isn't as bad
89       as I thought. Now multiply by "i" and negate, then take the complex
90       conjugate, which is just a very expensive way of swapping real and
91       imaginary parts.
92
93          pdl> p Cconj(-($r*i))
94          [0 +1.70998i  1.48088 -0.854988i  -1.48088 -0.854988i]
95
96       Now plot the magnitude of (part of) the complex sine. First generate
97       the coefficients:
98
99          pdl> $sin = i * zeroes(50)->xlinvals(2,4) + zeroes(50)->xlinvals(0,7)
100
101       Now plot the imaginary part, the real part and the magnitude of the
102       sine into the same diagram:
103
104          pdl> use PDL::Graphics::Gnuplot
105          pdl> gplot( with => 'lines',
106                     PDL::cat(im ( sin $sin ),
107                              re ( sin $sin ),
108                              abs( sin $sin ) ))
109
110       An ASCII version of this plot looks like this:
111
112         30 ++-----+------+------+------+------+------+------+------+------+-----++
113            +      +      +      +      +      +      +      +      +      +      +
114            |                                                                   $$|
115            |                                                                  $  |
116         25 ++                                                               $$  ++
117            |                                                              ***    |
118            |                                                            **   *** |
119            |                                                         $$*        *|
120         20 ++                                                       $**         ++
121            |                                                     $$$*           #|
122            |                                                  $$$   *          # |
123            |                                                $$     *           # |
124         15 ++                                            $$$       *          # ++
125            |                                          $$$        **           #  |
126            |                                      $$$$          *            #   |
127            |                                  $$$$              *            #   |
128         10 ++                            $$$$$                 *            #   ++
129            |                        $$$$$                     *             #    |
130            |                 $$$$$$$                         *             #     |
131          5 ++       $$$############                          *             #    ++
132            |*****$$$###            ###                      *             #      |
133            *    #*****                #                     *             #      |
134            | ###      ***              ###                **              #      |
135          0 ##            ***              #              *               #      ++
136            |                *              #             *              #        |
137            |                 ***            #          **               #        |
138            |                    *            #        *                #         |
139         -5 ++                    **           #      *                 #        ++
140            |                       ***         ##  **                 #          |
141            |                          *          #*                  #           |
142            |                           ****    ***##                #            |
143        -10 ++                              ****     #              #            ++
144            |                                         #             #             |
145            |                                          ##         ##              |
146            +      +      +      +      +      +      +  ### + ###  +      +      +
147        -15 ++-----+------+------+------+------+------+-----###-----+------+-----++
148            0      5      10     15     20     25     30     35     40     45     50
149

OPERATORS

151       The following operators are overloaded:
152
153       +, += (addition)
154       -, -= (subtraction)
155       *, *= (multiplication; "Cmul")
156       /, /= (division; "Cdiv")
157       **, **= (exponentiation; "Cpow")
158       atan2 (4-quadrant arc tangent)
159       sin ("Csin")
160       cos ("Ccos")
161       exp ("Cexp")
162       abs ("Cabs")
163       log ("Clog")
164       sqrt ("Csqrt")
165       ++, -- (increment, decrement; they affect the real part of the complex
166       number only)
167       "" (stringification)
168
169       Comparing complex numbers other than for equality is a fatal error.
170

FUNCTIONS

172   from_native
173       Class method to convert a native-complex ndarray to a PDL::Complex
174       object.
175
176        PDL::Complex->from_native($native_complex_ndarray)
177
178   as_native
179       Object method to convert a PDL::Complex object to a native-complex
180       ndarray.
181
182        $pdl_complex_obj->as_native
183
184   cplx
185       Cast a real-valued ndarray to the complex datatype.
186
187       The first dimension of the ndarray must be of size 2. After this the
188       usual (complex) arithmetic operators are applied to this pdl, rather
189       than the normal elementwise pdl operators.  Dataflow to the complex
190       parent works. Use "sever" on the result if you don't want this.
191
192        cplx($real_valued_pdl)
193
194   complex
195       Cast a real-valued ndarray to the complex datatype without dataflow and
196       inplace.
197
198       Achieved by merely reblessing an ndarray. The first dimension of the
199       ndarray must be of size 2.
200
201        complex($real_valued_pdl)
202
203   real
204       Cast a complex valued pdl back to the "normal" pdl datatype.
205
206       Afterwards the normal elementwise pdl operators are used in operations.
207       Dataflow to the real parent works. Use "sever" on the result if you
208       don't want this.
209
210        real($cplx_valued_pdl)
211
212   r2C
213         Signature: (r(); [o]c(m=2))
214
215       convert real to complex, assuming an imaginary part of zero
216
217       r2C does not process bad values.  It will set the bad-value flag of all
218       output ndarrays if the flag is set for any of the input ndarrays.
219
220   i2C
221         Signature: (r(); [o]c(m=2))
222
223       convert imaginary to complex, assuming a real part of zero
224
225       i2C does not process bad values.  It will set the bad-value flag of all
226       output ndarrays if the flag is set for any of the input ndarrays.
227
228   Cr2p
229         Signature: (r(m=2); float+ [o]p(m=2))
230
231       convert complex numbers in rectangular form to polar (mod,arg) form.
232       Works inplace
233
234       Cr2p does not process bad values.  It will set the bad-value flag of
235       all output ndarrays if the flag is set for any of the input ndarrays.
236
237   Cp2r
238         Signature: (r(m=2); [o]p(m=2))
239
240       convert complex numbers in polar (mod,arg) form to rectangular form.
241       Works inplace
242
243       Cp2r does not process bad values.  It will set the bad-value flag of
244       all output ndarrays if the flag is set for any of the input ndarrays.
245
246   Cmul
247         Signature: (a(m=2); b(m=2); [o]c(m=2))
248
249       complex multiplication
250
251       Cmul does not process bad values.  It will set the bad-value flag of
252       all output ndarrays if the flag is set for any of the input ndarrays.
253
254   Cprodover
255         Signature: (a(m=2,n); [o]c(m=2))
256
257       Project via product to N-1 dimension
258
259       Cprodover does not process bad values.  It will set the bad-value flag
260       of all output ndarrays if the flag is set for any of the input
261       ndarrays.
262
263   Cscale
264         Signature: (a(m=2); b(); [o]c(m=2))
265
266       mixed complex/real multiplication
267
268       Cscale does not process bad values.  It will set the bad-value flag of
269       all output ndarrays if the flag is set for any of the input ndarrays.
270
271   Cdiv
272         Signature: (a(m=2); b(m=2); [o]c(m=2))
273
274       complex division
275
276       Cdiv does not process bad values.  It will set the bad-value flag of
277       all output ndarrays if the flag is set for any of the input ndarrays.
278
279   Ceq
280         Signature: (a(m=2); b(m=2); [o]c())
281
282       Complex equality operator.
283
284       Ceq does not process bad values.  It will set the bad-value flag of all
285       output ndarrays if the flag is set for any of the input ndarrays.
286
287   Cconj
288         Signature: (a(m=2); [o]c(m=2))
289
290       complex conjugation. Works inplace
291
292       Cconj does not process bad values.  It will set the bad-value flag of
293       all output ndarrays if the flag is set for any of the input ndarrays.
294
295   Cabs
296         Signature: (a(m=2); [o]c())
297
298       complex "abs()" (also known as modulus)
299
300       Cabs does not process bad values.  It will set the bad-value flag of
301       all output ndarrays if the flag is set for any of the input ndarrays.
302
303   Cabs2
304         Signature: (a(m=2); [o]c())
305
306       complex squared "abs()" (also known squared modulus)
307
308       Cabs2 does not process bad values.  It will set the bad-value flag of
309       all output ndarrays if the flag is set for any of the input ndarrays.
310
311   Carg
312         Signature: (a(m=2); [o]c())
313
314       complex argument function ("angle")
315
316       Carg does not process bad values.  It will set the bad-value flag of
317       all output ndarrays if the flag is set for any of the input ndarrays.
318
319   Csin
320         Signature: (a(m=2); [o]c(m=2))
321
322         sin (a) = 1/(2*i) * (exp (a*i) - exp (-a*i)). Works inplace
323
324       Csin does not process bad values.  It will set the bad-value flag of
325       all output ndarrays if the flag is set for any of the input ndarrays.
326
327   Ccos
328         Signature: (a(m=2); [o]c(m=2))
329
330         cos (a) = 1/2 * (exp (a*i) + exp (-a*i)). Works inplace
331
332       Ccos does not process bad values.  It will set the bad-value flag of
333       all output ndarrays if the flag is set for any of the input ndarrays.
334
335   Ctan
336       Complex tangent
337
338         tan (a) = -i * (exp (a*i) - exp (-a*i)) / (exp (a*i) + exp (-a*i))
339
340       Does not work inplace.
341
342   Cexp
343         Signature: (a(m=2); [o]c(m=2))
344
345         exp (a) = exp (real (a)) * (cos (imag (a)) + i * sin (imag (a))). Works inplace
346
347       Cexp does not process bad values.  It will set the bad-value flag of
348       all output ndarrays if the flag is set for any of the input ndarrays.
349
350   Clog
351         Signature: (a(m=2); [o]c(m=2))
352
353         log (a) = log (cabs (a)) + i * carg (a). Works inplace
354
355       Clog does not process bad values.  It will set the bad-value flag of
356       all output ndarrays if the flag is set for any of the input ndarrays.
357
358   Cpow
359         Signature: (a(m=2); b(m=2); [o]c(m=2))
360
361       complex "pow()" ("**"-operator)
362
363       Cpow does not process bad values.  It will set the bad-value flag of
364       all output ndarrays if the flag is set for any of the input ndarrays.
365
366   Csqrt
367         Signature: (a(m=2); [o]c(m=2))
368
369       Works inplace
370
371       Csqrt does not process bad values.  It will set the bad-value flag of
372       all output ndarrays if the flag is set for any of the input ndarrays.
373
374   Casin
375         Signature: (a(m=2); [o]c(m=2))
376
377       Works inplace
378
379       Casin does not process bad values.  It will set the bad-value flag of
380       all output ndarrays if the flag is set for any of the input ndarrays.
381
382   Cacos
383         Signature: (a(m=2); [o]c(m=2))
384
385       Works inplace
386
387       Cacos does not process bad values.  It will set the bad-value flag of
388       all output ndarrays if the flag is set for any of the input ndarrays.
389
390   Catan
391       Return the complex "atan()".
392
393       Does not work inplace.
394
395   Csinh
396         Signature: (a(m=2); [o]c(m=2))
397
398         sinh (a) = (exp (a) - exp (-a)) / 2. Works inplace
399
400       Csinh does not process bad values.  It will set the bad-value flag of
401       all output ndarrays if the flag is set for any of the input ndarrays.
402
403   Ccosh
404         Signature: (a(m=2); [o]c(m=2))
405
406         cosh (a) = (exp (a) + exp (-a)) / 2. Works inplace
407
408       Ccosh does not process bad values.  It will set the bad-value flag of
409       all output ndarrays if the flag is set for any of the input ndarrays.
410
411   Ctanh
412         Signature: (a(m=2); [o]c(m=2))
413
414       Works inplace
415
416       Ctanh does not process bad values.  It will set the bad-value flag of
417       all output ndarrays if the flag is set for any of the input ndarrays.
418
419   Casinh
420         Signature: (a(m=2); [o]c(m=2))
421
422       Works inplace
423
424       Casinh does not process bad values.  It will set the bad-value flag of
425       all output ndarrays if the flag is set for any of the input ndarrays.
426
427   Cacosh
428         Signature: (a(m=2); [o]c(m=2))
429
430       Works inplace
431
432       Cacosh does not process bad values.  It will set the bad-value flag of
433       all output ndarrays if the flag is set for any of the input ndarrays.
434
435   Catanh
436         Signature: (a(m=2); [o]c(m=2))
437
438       Works inplace
439
440       Catanh does not process bad values.  It will set the bad-value flag of
441       all output ndarrays if the flag is set for any of the input ndarrays.
442
443   Cproj
444         Signature: (a(m=2); [o]c(m=2))
445
446       compute the projection of a complex number to the riemann sphere. Works
447       inplace
448
449       Cproj does not process bad values.  It will set the bad-value flag of
450       all output ndarrays if the flag is set for any of the input ndarrays.
451
452   Croots
453         Signature: (a(m=2); [o]c(m=2,n); int n => n)
454
455       Compute the "n" roots of "a". "n" must be a positive integer. The
456       result will always be a complex type!
457
458       Croots does not process bad values.  It will set the bad-value flag of
459       all output ndarrays if the flag is set for any of the input ndarrays.
460
461   re, im
462       Return the real or imaginary part of the complex number(s) given.
463
464       These are slicing operators, so data flow works. The real and imaginary
465       parts are returned as ndarrays (ref eq PDL).
466
467   rCpolynomial
468         Signature: (coeffs(n); x(c=2,m); [o]out(c=2,m))
469
470       evaluate the polynomial with (real) coefficients "coeffs" at the
471       (complex) position(s) "x". "coeffs[0]" is the constant term.
472
473       rCpolynomial does not process bad values.  It will set the bad-value
474       flag of all output ndarrays if the flag is set for any of the input
475       ndarrays.
476

AUTHOR

478       Copyright (C) 2000 Marc Lehmann <pcg@goof.com>.  All rights reserved.
479       There is no warranty. You are allowed to redistribute this software /
480       documentation as described in the file COPYING in the PDL distribution.
481