1Complex(3) User Contributed Perl Documentation Complex(3)
2
3
4
6 PDL::Complex - handle complex numbers (DEPRECATED - use native complex)
7
9 use PDL;
10 use PDL::Complex;
11
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
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 the
63 complex datatype. Use real(complex-valued-ndarray) to cast back.
64 This requires a copy, though.
65
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
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
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
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
483 perl(1), PDL.
484
485
486
487perl v5.36.0 2023-01-20 Complex(3)