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
66       •   This module has received some testing by Vanuxem Grégory (g.vanuxem
67           at wanadoo dot fr). Please report any other errors you come across!
68

EXAMPLE WALK-THROUGH

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

OPERATORS

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

FUNCTIONS

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

AUTHOR

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