PDL::Complex(3pm)

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

NAME

6       PDL::Complex - handle complex numbers
7

SYNOPSIS

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

DESCRIPTION

13       This module features a growing number of functions manipulating complex
14       numbers. These are usually represented as a pair "[ real imag ]" or "[
15       magnitude phase ]". If not explicitly mentioned, the functions can work
16       inplace (not yet implemented!!!) and require rectangular form.
17
18       While there is a procedural interface available ("$x/$y*$c <=> Cmul
19       (Cdiv ($x, $y), $c)"), you can also opt to cast your pdl's into the
20       "PDL::Complex" datatype, which works just like your normal piddles, but
21       with all the normal perl operators overloaded.
22
23       The latter means that "sin($x) + $y/$c" will be evaluated using the
24       normal rules of complex numbers, while other pdl functions (like "max")
25       just treat the piddle as a real-valued piddle with a lowest dimension
26       of size 2, so "max" will return the maximum of all real and imaginary
27       parts, not the "highest" (for some definition)
28

TIPS, TRICKS & CAVEATS

30       ·   "i" is a constant exported by this module, which represents
31           "-1**0.5", i.e. the imaginary unit. it can be used to quickly and
32           conveniently write complex constants like this: "4+3*i".
33
34       ·   Use "r2C(real-values)" to convert from real to complex, as in "$r =
35           Cpow $cplx, r2C 2". The overloaded operators automatically do that
36           for you, all the other functions, do not. So "Croots 1, 5" will
37           return all the fifths roots of 1+1*i (due to threading).
38
39       ·   use "cplx(real-valued-piddle)" to cast from normal piddles into the
40           complex datatype. Use "real(complex-valued-piddle)" to cast back.
41           This requires a copy, though.
42
43       ·   This module has received some testing by Vanuxem Grégory (g.vanuxem
44           at wanadoo dot fr). Please report any other errors you come across!
45

EXAMPLE WALK-THROUGH

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

OPERATORS

130       The following operators are overloaded:
131
132       +, += (addition)
133       -, -= (subtraction)
134       *, *= (multiplication; Cmul)
135       /, /= (division; Cdiv)
136       **, **= (exponentiation; Cpow)
137       atan2 (4-quadrant arc tangent)
138       <=> (nonsensical comparison operator; Ccmp)
139       sin (Csin)
140       cos (Ccos)
141       exp (Cexp)
142       abs (Cabs)
143       log (Clog)
144       sqrt (Csqrt)
145       <, <=, ==, !=, >=, > (just as nonsensical as Ccmp)
146       ++, -- (increment, decrement; they affect the real part of the complex
147       number only)
148       "" (stringification)
149

FUNCTIONS

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

AUTHOR

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