1Math::Complex(3pm) Perl Programmers Reference Guide Math::Complex(3pm)
2
6 Math::Complex - complex numbers and associated mathematical functions
7
9 use Math::Complex;
10 $z = Math::Complex->make(5, 6);
12 $t = 4 - 3*i + $z;
13 $j = cplxe(1, 2*pi/3);
14
16 This package lets you create and manipulate complex numbers. By
17 default, Perl limits itself to real numbers, but an extra "use"
18 statement brings full complex support, along with a full set of
19 mathematical functions typically associated with and/or extended to
20 complex numbers.
21 If you wonder what complex numbers are, they were invented to be able
23 to solve the following equation:
24 x*x = -1
26 and by definition, the solution is noted i (engineers use j instead
28 since i usually denotes an intensity, but the name does not matter).
29 The number i is a pure imaginary number.
30 The arithmetics with pure imaginary numbers works just like you would
32 expect it with real numbers... you just have to remember that
33 i*i = -1
35 so you have:
37 5i + 7i = i * (5 + 7) = 12i
39 4i - 3i = i * (4 - 3) = i
40 4i * 2i = -8
41 6i / 2i = 3
42 1 / i = -i
43 Complex numbers are numbers that have both a real part and an imaginary
45 part, and are usually noted:
46 a + bi
48 where "a" is the real part and "b" is the imaginary part. The
50 arithmetic with complex numbers is straightforward. You have to keep
51 track of the real and the imaginary parts, but otherwise the rules used
52 for real numbers just apply:
53 (4 + 3i) + (5 - 2i) = (4 + 5) + i(3 - 2) = 9 + i
55 (2 + i) * (4 - i) = 2*4 + 4i -2i -i*i = 8 + 2i + 1 = 9 + 2i
56 A graphical representation of complex numbers is possible in a plane
58 (also called the complex plane, but it's really a 2D plane). The
59 number
60 z = a + bi
62 is the point whose coordinates are (a, b). Actually, it would be the
64 vector originating from (0, 0) to (a, b). It follows that the addition
65 of two complex numbers is a vectorial addition.
66 Since there is a bijection between a point in the 2D plane and a
68 complex number (i.e. the mapping is unique and reciprocal), a complex
69 number can also be uniquely identified with polar coordinates:
70 [rho, theta]
72 where "rho" is the distance to the origin, and "theta" the angle
74 between the vector and the x axis. There is a notation for this using
75 the exponential form, which is:
76 rho * exp(i * theta)
78 where i is the famous imaginary number introduced above. Conversion
80 between this form and the cartesian form "a + bi" is immediate:
81 a = rho * cos(theta)
83 b = rho * sin(theta)
84 which is also expressed by this formula:
86 z = rho * exp(i * theta) = rho * (cos theta + i * sin theta)
88 In other words, it's the projection of the vector onto the x and y
90 axes. Mathematicians call rho the norm or modulus and theta the
91 argument of the complex number. The norm of "z" is marked here as
92 abs(z).
93 The polar notation (also known as the trigonometric representation) is
95 much more handy for performing multiplications and divisions of complex
96 numbers, whilst the cartesian notation is better suited for additions
97 and subtractions. Real numbers are on the x axis, and therefore y or
98 theta is zero or pi.
99 All the common operations that can be performed on a real number have
101 been defined to work on complex numbers as well, and are merely
102 extensions of the operations defined on real numbers. This means they
103 keep their natural meaning when there is no imaginary part, provided
104 the number is within their definition set.
105 For instance, the "sqrt" routine which computes the square root of its
107 argument is only defined for non-negative real numbers and yields a
108 non-negative real number (it is an application from R+ to R+). If we
109 allow it to return a complex number, then it can be extended to
110 negative real numbers to become an application from R to C (the set of
111 complex numbers):
112 sqrt(x) = x >= 0 ? sqrt(x) : sqrt(-x)*i
114 It can also be extended to be an application from C to C, whilst its
116 restriction to R behaves as defined above by using the following
117 definition:
118 sqrt(z = [r,t]) = sqrt(r) * exp(i * t/2)
120 Indeed, a negative real number can be noted "[x,pi]" (the modulus x is
122 always non-negative, so "[x,pi]" is really "-x", a negative number) and
123 the above definition states that
124 sqrt([x,pi]) = sqrt(x) * exp(i*pi/2) = [sqrt(x),pi/2] = sqrt(x)*i
126 which is exactly what we had defined for negative real numbers above.
128 The "sqrt" returns only one of the solutions: if you want the both, use
129 the "root" function.
130 All the common mathematical functions defined on real numbers that are
132 extended to complex numbers share that same property of working as
133 usual when the imaginary part is zero (otherwise, it would not be
134 called an extension, would it?).
135 A new operation possible on a complex number that is the identity for
137 real numbers is called the conjugate, and is noted with a horizontal
138 bar above the number, or "~z" here.
139 z = a + bi
141 ~z = a - bi
142 Simple... Now look:
144 z * ~z = (a + bi) * (a - bi) = a*a + b*b
146 We saw that the norm of "z" was noted abs(z) and was defined as the
148 distance to the origin, also known as:
149 rho = abs(z) = sqrt(a*a + b*b)
151 so
153 z * ~z = abs(z) ** 2
155 If z is a pure real number (i.e. "b == 0"), then the above yields:
157 a * a = abs(a) ** 2
159 which is true ("abs" has the regular meaning for real number, i.e.
161 stands for the absolute value). This example explains why the norm of
162 "z" is noted abs(z): it extends the "abs" function to complex numbers,
163 yet is the regular "abs" we know when the complex number actually has
164 no imaginary part... This justifies a posteriori our use of the "abs"
165 notation for the norm.
166
168 Given the following notations:
169 z1 = a + bi = r1 * exp(i * t1)
171 z2 = c + di = r2 * exp(i * t2)
172 z = <any complex or real number>
173 the following (overloaded) operations are supported on complex numbers:
175 z1 + z2 = (a + c) + i(b + d)
177 z1 - z2 = (a - c) + i(b - d)
178 z1 * z2 = (r1 * r2) * exp(i * (t1 + t2))
179 z1 / z2 = (r1 / r2) * exp(i * (t1 - t2))
180 z1 ** z2 = exp(z2 * log z1)
181 ~z = a - bi
182 abs(z) = r1 = sqrt(a*a + b*b)
183 sqrt(z) = sqrt(r1) * exp(i * t/2)
184 exp(z) = exp(a) * exp(i * b)
185 log(z) = log(r1) + i*t
186 sin(z) = 1/2i (exp(i * z1) - exp(-i * z))
187 cos(z) = 1/2 (exp(i * z1) + exp(-i * z))
188 atan2(y, x) = atan(y / x) # Minding the right quadrant, note the order.
189 The definition used for complex arguments of atan2() is
191 -i log((x + iy)/sqrt(x*x+y*y))
193 Note that atan2(0, 0) is not well-defined.
195 The following extra operations are supported on both real and complex
197 numbers:
198 Re(z) = a
200 Im(z) = b
201 arg(z) = t
202 abs(z) = r
203 cbrt(z) = z ** (1/3)
205 log10(z) = log(z) / log(10)
206 logn(z, n) = log(z) / log(n)
207 tan(z) = sin(z) / cos(z)
209 csc(z) = 1 / sin(z)
211 sec(z) = 1 / cos(z)
212 cot(z) = 1 / tan(z)
213 asin(z) = -i * log(i*z + sqrt(1-z*z))
215 acos(z) = -i * log(z + i*sqrt(1-z*z))
216 atan(z) = i/2 * log((i+z) / (i-z))
217 acsc(z) = asin(1 / z)
219 asec(z) = acos(1 / z)
220 acot(z) = atan(1 / z) = -i/2 * log((i+z) / (z-i))
221 sinh(z) = 1/2 (exp(z) - exp(-z))
223 cosh(z) = 1/2 (exp(z) + exp(-z))
224 tanh(z) = sinh(z) / cosh(z) = (exp(z) - exp(-z)) / (exp(z) + exp(-z))
225 csch(z) = 1 / sinh(z)
227 sech(z) = 1 / cosh(z)
228 coth(z) = 1 / tanh(z)
229 asinh(z) = log(z + sqrt(z*z+1))
231 acosh(z) = log(z + sqrt(z*z-1))
232 atanh(z) = 1/2 * log((1+z) / (1-z))
233 acsch(z) = asinh(1 / z)
235 asech(z) = acosh(1 / z)
236 acoth(z) = atanh(1 / z) = 1/2 * log((1+z) / (z-1))
237 arg, abs, log, csc, cot, acsc, acot, csch, coth, acosech, acotanh, have
239 aliases rho, theta, ln, cosec, cotan, acosec, acotan, cosech, cotanh,
240 acosech, acotanh, respectively. "Re", "Im", "arg", "abs", "rho", and
241 "theta" can be used also as mutators. The "cbrt" returns only one of
242 the solutions: if you want all three, use the "root" function.
243 The root function is available to compute all the n roots of some
245 complex, where n is a strictly positive integer. There are exactly n
246 such roots, returned as a list. Getting the number mathematicians call
247 "j" such that:
248 1 + j + j*j = 0;
250 is a simple matter of writing:
252 $j = ((root(1, 3))[1];
254 The kth root for "z = [r,t]" is given by:
256 (root(z, n))[k] = r**(1/n) * exp(i * (t + 2*k*pi)/n)
258 You can return the kth root directly by "root(z, n, k)", indexing
260 starting from zero and ending at n - 1.
261 The spaceship numeric comparison operator, <=>, is also defined. In
263 order to ensure its restriction to real numbers is conform to what you
264 would expect, the comparison is run on the real part of the complex
265 number first, and imaginary parts are compared only when the real parts
266 match.
267
269 To create a complex number, use either:
270 $z = Math::Complex->make(3, 4);
272 $z = cplx(3, 4);
273 if you know the cartesian form of the number, or
275 $z = 3 + 4*i;
277 if you like. To create a number using the polar form, use either:
279 $z = Math::Complex->emake(5, pi/3);
281 $x = cplxe(5, pi/3);
282 instead. The first argument is the modulus, the second is the angle (in
284 radians, the full circle is 2*pi). (Mnemonic: "e" is used as a
285 notation for complex numbers in the polar form).
286 It is possible to write:
288 $x = cplxe(-3, pi/4);
290 but that will be silently converted into "[3,-3pi/4]", since the
292 modulus must be non-negative (it represents the distance to the origin
293 in the complex plane).
294 It is also possible to have a complex number as either argument of the
296 "make", "emake", "cplx", and "cplxe": the appropriate component of the
297 argument will be used.
298 $z1 = cplx(-2, 1);
300 $z2 = cplx($z1, 4);
301 The "new", "make", "emake", "cplx", and "cplxe" will also understand a
303 single (string) argument of the forms
304 2-3i
306 -3i
307 [2,3]
308 [2,-3pi/4]
309 [2]
310 in which case the appropriate cartesian and exponential components will
312 be parsed from the string and used to create new complex numbers. The
313 imaginary component and the theta, respectively, will default to zero.
314 The "new", "make", "emake", "cplx", and "cplxe" will also understand
316 the case of no arguments: this means plain zero or (0, 0).
317
319 When printed, a complex number is usually shown under its cartesian
320 style a+bi, but there are legitimate cases where the polar style [r,t]
321 is more appropriate. The process of converting the complex number into
322 a string that can be displayed is known as stringification.
323 By calling the class method "Math::Complex::display_format" and
325 supplying either "polar" or "cartesian" as an argument, you override
326 the default display style, which is "cartesian". Not supplying any
327 argument returns the current settings.
328 This default can be overridden on a per-number basis by calling the
330 "display_format" method instead. As before, not supplying any argument
331 returns the current display style for this number. Otherwise whatever
332 you specify will be the new display style for this particular number.
333 For instance:
335 use Math::Complex;
337 Math::Complex::display_format('polar');
339 $j = (root(1, 3))[1];
340 print "j = $j\n"; # Prints "j = [1,2pi/3]"
341 $j->display_format('cartesian');
342 print "j = $j\n"; # Prints "j = -0.5+0.866025403784439i"
343 The polar style attempts to emphasize arguments like k*pi/n (where n is
345 a positive integer and k an integer within [-9, +9]), this is called
346 polar pretty-printing.
347 For the reverse of stringifying, see the "make" and "emake".
349 CHANGED IN PERL 5.6
351 The "display_format" class method and the corresponding
352 "display_format" object method can now be called using a parameter hash
353 instead of just a one parameter.
354 The old display format style, which can have values "cartesian" or
356 "polar", can be changed using the "style" parameter.
357 $j->display_format(style => "polar");
359 The one parameter calling convention also still works.
361 $j->display_format("polar");
363 There are two new display parameters.
365 The first one is "format", which is a sprintf()-style format string to
367 be used for both numeric parts of the complex number(s). The is
368 somewhat system-dependent but most often it corresponds to "%.15g".
369 You can revert to the default by setting the "format" to "undef".
370 # the $j from the above example
372 $j->display_format('format' => '%.5f');
374 print "j = $j\n"; # Prints "j = -0.50000+0.86603i"
375 $j->display_format('format' => undef);
376 print "j = $j\n"; # Prints "j = -0.5+0.86603i"
377 Notice that this affects also the return values of the "display_format"
379 methods: in list context the whole parameter hash will be returned, as
380 opposed to only the style parameter value. This is a potential
381 incompatibility with earlier versions if you have been calling the
382 "display_format" method in list context.
383 The second new display parameter is "polar_pretty_print", which can be
385 set to true or false, the default being true. See the previous section
386 for what this means.
387
389 Thanks to overloading, the handling of arithmetics with complex numbers
390 is simple and almost transparent.
391 Here are some examples:
393 use Math::Complex;
395 $j = cplxe(1, 2*pi/3); # $j ** 3 == 1
397 print "j = $j, j**3 = ", $j ** 3, "\n";
398 print "1 + j + j**2 = ", 1 + $j + $j**2, "\n";
399 $z = -16 + 0*i; # Force it to be a complex
401 print "sqrt($z) = ", sqrt($z), "\n";
402 $k = exp(i * 2*pi/3);
404 print "$j - $k = ", $j - $k, "\n";
405 $z->Re(3); # Re, Im, arg, abs,
407 $j->arg(2); # (the last two aka rho, theta)
408 # can be used also as mutators.
409
411 PI
412 The constant "pi" and some handy multiples of it (pi2, pi4, and pip2
413 (pi/2) and pip4 (pi/4)) are also available if separately exported:
414 use Math::Complex ':pi';
416 $third_of_circle = pi2 / 3;
417 Inf
419 The floating point infinity can be exported as a subroutine Inf():
420 use Math::Complex qw(Inf sinh);
422 my $AlsoInf = Inf() + 42;
423 my $AnotherInf = sinh(1e42);
424 print "$AlsoInf is $AnotherInf\n" if $AlsoInf == $AnotherInf;
425 Note that the stringified form of infinity varies between platforms: it
427 can be for example any of
428 inf
430 infinity
431 INF
432 1.#INF
433 or it can be something else.
435 Also note that in some platforms trying to use the infinity in
437 arithmetic operations may result in Perl crashing because using an
438 infinity causes SIGFPE or its moral equivalent to be sent. The way to
439 ignore this is
440 local $SIG{FPE} = sub { };
442
444 The division (/) and the following functions
445 log ln log10 logn
447 tan sec csc cot
448 atan asec acsc acot
449 tanh sech csch coth
450 atanh asech acsch acoth
451 cannot be computed for all arguments because that would mean dividing
453 by zero or taking logarithm of zero. These situations cause fatal
454 runtime errors looking like this
455 cot(0): Division by zero.
457 (Because in the definition of cot(0), the divisor sin(0) is 0)
458 Died at ...
459 or
461 atanh(-1): Logarithm of zero.
463 Died at...
464 For the "csc", "cot", "asec", "acsc", "acot", "csch", "coth", "asech",
466 "acsch", the argument cannot be 0 (zero). For the logarithmic
467 functions and the "atanh", "acoth", the argument cannot be 1 (one).
468 For the "atanh", "acoth", the argument cannot be "-1" (minus one). For
469 the "atan", "acot", the argument cannot be "i" (the imaginary unit).
470 For the "atan", "acoth", the argument cannot be "-i" (the negative
471 imaginary unit). For the "tan", "sec", "tanh", the argument cannot be
472 pi/2 + k * pi, where k is any integer. atan2(0, 0) is undefined, and
473 if the complex arguments are used for atan2(), a division by zero will
474 happen if z1**2+z2**2 == 0.
475 Note that because we are operating on approximations of real numbers,
477 these errors can happen when merely `too close' to the singularities
478 listed above.
479
481 The "make" and "emake" accept both real and complex arguments. When
482 they cannot recognize the arguments they will die with error messages
483 like the following
484 Math::Complex::make: Cannot take real part of ...
486 Math::Complex::make: Cannot take real part of ...
487 Math::Complex::emake: Cannot take rho of ...
488 Math::Complex::emake: Cannot take theta of ...
489
491 Saying "use Math::Complex;" exports many mathematical routines in the
492 caller environment and even overrides some ("sqrt", "log", "atan2").
493 This is construed as a feature by the Authors, actually... ;-)
494 All routines expect to be given real or complex numbers. Don't attempt
496 to use BigFloat, since Perl has currently no rule to disambiguate a '+'
497 operation (for instance) between two overloaded entities.
498 In Cray UNICOS there is some strange numerical instability that results
500 in root(), cos(), sin(), cosh(), sinh(), losing accuracy fast. Beware.
501 The bug may be in UNICOS math libs, in UNICOS C compiler, in
502 Math::Complex. Whatever it is, it does not manifest itself anywhere
503 else where Perl runs.
504
506 Math::Trig
507
509 Daniel S. Lewart <lewart!at!uiuc.edu>, Jarkko Hietaniemi
510 <jhi!at!iki.fi>, Raphael Manfredi <Raphael_Manfredi!at!pobox.com>,
511 Zefram <zefram@fysh.org>
512
514 This library is free software; you can redistribute it and/or modify it
515 under the same terms as Perl itself.
516perl v5.36.0 2022-08-30 Math::Complex(3pm)