Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Math::Complex.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Math::Complex 3pm"
61 .TH Math::Complex 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Math::Complex \- complex numbers and associated mathematical functions
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Math::Complex;
72 \&
73 \& $z = Math::Complex\->make(5, 6);
74 \& $t = 4 \- 3*i + $z;
75 \& $j = cplxe(1, 2*pi/3);
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 This package lets you create and manipulate complex numbers. By default,
80 \&\fIPerl\fR limits itself to real numbers, but an extra \f(CW\*(C`use\*(C'\fR statement brings
81 full complex support, along with a full set of mathematical functions
82 typically associated with and/or extended to complex numbers.
83 .PP
84 If you wonder what complex numbers are, they were invented to be able to solve
85 the following equation:
86 .PP
87 .Vb 1
88 \& x*x = \-1
89 .Ve
90 .PP
91 and by definition, the solution is noted \fIi\fR (engineers use \fIj\fR instead since
92 \&\fIi\fR usually denotes an intensity, but the name does not matter). The number
93 \&\fIi\fR is a pure \fIimaginary\fR number.
94 .PP
95 The arithmetics with pure imaginary numbers works just like you would expect
96 it with real numbers... you just have to remember that
97 .PP
98 .Vb 1
99 \& i*i = \-1
100 .Ve
101 .PP
102 so you have:
103 .PP
104 .Vb 5
105 \& 5i + 7i = i * (5 + 7) = 12i
106 \& 4i \- 3i = i * (4 \- 3) = i
107 \& 4i * 2i = \-8
108 \& 6i / 2i = 3
109 \& 1 / i = \-i
110 .Ve
111 .PP
112 Complex numbers are numbers that have both a real part and an imaginary
113 part, and are usually noted:
114 .PP
115 .Vb 1
116 \& a + bi
117 .Ve
118 .PP
119 where \f(CW\*(C`a\*(C'\fR is the \fIreal\fR part and \f(CW\*(C`b\*(C'\fR is the \fIimaginary\fR part. The
120 arithmetic with complex numbers is straightforward. You have to
121 keep track of the real and the imaginary parts, but otherwise the
122 rules used for real numbers just apply:
123 .PP
124 .Vb 2
125 \& (4 + 3i) + (5 \- 2i) = (4 + 5) + i(3 \- 2) = 9 + i
126 \& (2 + i) * (4 \- i) = 2*4 + 4i \-2i \-i*i = 8 + 2i + 1 = 9 + 2i
127 .Ve
128 .PP
129 A graphical representation of complex numbers is possible in a plane
130 (also called the \fIcomplex plane\fR, but it\*(Aqs really a 2D plane).
131 The number
132 .PP
133 .Vb 1
134 \& z = a + bi
135 .Ve
136 .PP
137 is the point whose coordinates are (a, b). Actually, it would
138 be the vector originating from (0, 0) to (a, b). It follows that the addition
139 of two complex numbers is a vectorial addition.
140 .PP
141 Since there is a bijection between a point in the 2D plane and a complex
142 number (i.e. the mapping is unique and reciprocal), a complex number
143 can also be uniquely identified with polar coordinates:
144 .PP
145 .Vb 1
146 \& [rho, theta]
147 .Ve
148 .PP
149 where \f(CW\*(C`rho\*(C'\fR is the distance to the origin, and \f(CW\*(C`theta\*(C'\fR the angle between
150 the vector and the \fIx\fR axis. There is a notation for this using the
151 exponential form, which is:
152 .PP
153 .Vb 1
154 \& rho * exp(i * theta)
155 .Ve
156 .PP
157 where \fIi\fR is the famous imaginary number introduced above. Conversion
158 between this form and the cartesian form \f(CW\*(C`a + bi\*(C'\fR is immediate:
159 .PP
160 .Vb 2
161 \& a = rho * cos(theta)
162 \& b = rho * sin(theta)
163 .Ve
164 .PP
165 which is also expressed by this formula:
166 .PP
167 .Vb 1
168 \& z = rho * exp(i * theta) = rho * (cos theta + i * sin theta)
169 .Ve
170 .PP
171 In other words, it\*(Aqs the projection of the vector onto the \fIx\fR and \fIy\fR
172 axes. Mathematicians call \fIrho\fR the \fInorm\fR or \fImodulus\fR and \fItheta\fR
173 the \fIargument\fR of the complex number. The \fInorm\fR of \f(CW\*(C`z\*(C'\fR is
174 marked here as \f(CWabs(z)\fR.
175 .PP
176 The polar notation (also known as the trigonometric representation) is
177 much more handy for performing multiplications and divisions of
178 complex numbers, whilst the cartesian notation is better suited for
179 additions and subtractions. Real numbers are on the \fIx\fR axis, and
180 therefore \fIy\fR or \fItheta\fR is zero or \fIpi\fR.
181 .PP
182 All the common operations that can be performed on a real number have
183 been defined to work on complex numbers as well, and are merely
184 \&\fIextensions\fR of the operations defined on real numbers. This means
185 they keep their natural meaning when there is no imaginary part, provided
186 the number is within their definition set.
187 .PP
188 For instance, the \f(CW\*(C`sqrt\*(C'\fR routine which computes the square root of
189 its argument is only defined for non\-negative real numbers and yields a
190 non\-negative real number (it is an application from \fBR+\fR to \fBR+\fR).
191 If we allow it to return a complex number, then it can be extended to
192 negative real numbers to become an application from \fBR\fR to \fBC\fR (the
193 set of complex numbers):
194 .PP
195 .Vb 1
196 \& sqrt(x) = x >= 0 ? sqrt(x) : sqrt(\-x)*i
197 .Ve
198 .PP
199 It can also be extended to be an application from \fBC\fR to \fBC\fR,
200 whilst its restriction to \fBR\fR behaves as defined above by using
201 the following definition:
202 .PP
203 .Vb 1
204 \& sqrt(z = [r,t]) = sqrt(r) * exp(i * t/2)
205 .Ve
206 .PP
207 Indeed, a negative real number can be noted \f(CW\*(C`[x,pi]\*(C'\fR (the modulus
208 \&\fIx\fR is always non\-negative, so \f(CW\*(C`[x,pi]\*(C'\fR is really \f(CW\*(C`\-x\*(C'\fR, a negative
209 number) and the above definition states that
210 .PP
211 .Vb 1
212 \& sqrt([x,pi]) = sqrt(x) * exp(i*pi/2) = [sqrt(x),pi/2] = sqrt(x)*i
213 .Ve
214 .PP
215 which is exactly what we had defined for negative real numbers above.
216 The \f(CW\*(C`sqrt\*(C'\fR returns only one of the solutions: if you want the both,
217 use the \f(CW\*(C`root\*(C'\fR function.
218 .PP
219 All the common mathematical functions defined on real numbers that
220 are extended to complex numbers share that same property of working
221 \&\fIas usual\fR when the imaginary part is zero (otherwise, it would not
222 be called an extension, would it?).
223 .PP
224 A \fInew\fR operation possible on a complex number that is
225 the identity for real numbers is called the \fIconjugate\fR, and is noted
226 with a horizontal bar above the number, or \f(CW\*(C`~z\*(C'\fR here.
227 .PP
228 .Vb 2
229 \& z = a + bi
230 \& ~z = a \- bi
231 .Ve
232 .PP
233 Simple... Now look:
234 .PP
235 .Vb 1
236 \& z * ~z = (a + bi) * (a \- bi) = a*a + b*b
237 .Ve
238 .PP
239 We saw that the norm of \f(CW\*(C`z\*(C'\fR was noted \f(CWabs(z)\fR and was defined as the
240 distance to the origin, also known as:
241 .PP
242 .Vb 1
243 \& rho = abs(z) = sqrt(a*a + b*b)
244 .Ve
245 .PP
246 so
247 .PP
248 .Vb 1
249 \& z * ~z = abs(z) ** 2
250 .Ve
251 .PP
252 If z is a pure real number (i.e. \f(CW\*(C`b == 0\*(C'\fR), then the above yields:
253 .PP
254 .Vb 1
255 \& a * a = abs(a) ** 2
256 .Ve
257 .PP
258 which is true (\f(CW\*(C`abs\*(C'\fR has the regular meaning for real number, i.e. stands
259 for the absolute value). This example explains why the norm of \f(CW\*(C`z\*(C'\fR is
260 noted \f(CWabs(z)\fR: it extends the \f(CW\*(C`abs\*(C'\fR function to complex numbers, yet
261 is the regular \f(CW\*(C`abs\*(C'\fR we know when the complex number actually has no
262 imaginary part... This justifies \fIa posteriori\fR our use of the \f(CW\*(C`abs\*(C'\fR
263 notation for the norm.
264 .SH OPERATIONS
265 .IX Header "OPERATIONS"
266 Given the following notations:
267 .PP
268 .Vb 3
269 \& z1 = a + bi = r1 * exp(i * t1)
270 \& z2 = c + di = r2 * exp(i * t2)
271 \& z = <any complex or real number>
272 .Ve
273 .PP
274 the following (overloaded) operations are supported on complex numbers:
275 .PP
276 .Vb 10
277 \& z1 + z2 = (a + c) + i(b + d)
278 \& z1 \- z2 = (a \- c) + i(b \- d)
279 \& z1 * z2 = (r1 * r2) * exp(i * (t1 + t2))
280 \& z1 / z2 = (r1 / r2) * exp(i * (t1 \- t2))
281 \& z1 ** z2 = exp(z2 * log z1)
282 \& ~z = a \- bi
283 \& abs(z) = r1 = sqrt(a*a + b*b)
284 \& sqrt(z) = sqrt(r1) * exp(i * t/2)
285 \& exp(z) = exp(a) * exp(i * b)
286 \& log(z) = log(r1) + i*t
287 \& sin(z) = 1/2i (exp(i * z1) \- exp(\-i * z))
288 \& cos(z) = 1/2 (exp(i * z1) + exp(\-i * z))
289 \& atan2(y, x) = atan(y / x) # Minding the right quadrant, note the order.
290 .Ve
291 .PP
292 The definition used for complex arguments of \fBatan2()\fR is
293 .PP
294 .Vb 1
295 \& \-i log((x + iy)/sqrt(x*x+y*y))
296 .Ve
297 .PP
298 Note that atan2(0, 0) is not well\-defined.
299 .PP
300 The following extra operations are supported on both real and complex
301 numbers:
302 .PP
303 .Vb 4
304 \& Re(z) = a
305 \& Im(z) = b
306 \& arg(z) = t
307 \& abs(z) = r
308 \&
309 \& cbrt(z) = z ** (1/3)
310 \& log10(z) = log(z) / log(10)
311 \& logn(z, n) = log(z) / log(n)
312 \&
313 \& tan(z) = sin(z) / cos(z)
314 \&
315 \& csc(z) = 1 / sin(z)
316 \& sec(z) = 1 / cos(z)
317 \& cot(z) = 1 / tan(z)
318 \&
319 \& asin(z) = \-i * log(i*z + sqrt(1\-z*z))
320 \& acos(z) = \-i * log(z + i*sqrt(1\-z*z))
321 \& atan(z) = i/2 * log((i+z) / (i\-z))
322 \&
323 \& acsc(z) = asin(1 / z)
324 \& asec(z) = acos(1 / z)
325 \& acot(z) = atan(1 / z) = \-i/2 * log((i+z) / (z\-i))
326 \&
327 \& sinh(z) = 1/2 (exp(z) \- exp(\-z))
328 \& cosh(z) = 1/2 (exp(z) + exp(\-z))
329 \& tanh(z) = sinh(z) / cosh(z) = (exp(z) \- exp(\-z)) / (exp(z) + exp(\-z))
330 \&
331 \& csch(z) = 1 / sinh(z)
332 \& sech(z) = 1 / cosh(z)
333 \& coth(z) = 1 / tanh(z)
334 \&
335 \& asinh(z) = log(z + sqrt(z*z+1))
336 \& acosh(z) = log(z + sqrt(z*z\-1))
337 \& atanh(z) = 1/2 * log((1+z) / (1\-z))
338 \&
339 \& acsch(z) = asinh(1 / z)
340 \& asech(z) = acosh(1 / z)
341 \& acoth(z) = atanh(1 / z) = 1/2 * log((1+z) / (z\-1))
342 .Ve
343 .PP
344 \&\fIarg\fR, \fIabs\fR, \fIlog\fR, \fIcsc\fR, \fIcot\fR, \fIacsc\fR, \fIacot\fR, \fIcsch\fR,
345 \&\fIcoth\fR, \fIacosech\fR, \fIacotanh\fR, have aliases \fIrho\fR, \fItheta\fR, \fIln\fR,
346 \&\fIcosec\fR, \fIcotan\fR, \fIacosec\fR, \fIacotan\fR, \fIcosech\fR, \fIcotanh\fR,
347 \&\fIacosech\fR, \fIacotanh\fR, respectively. \f(CW\*(C`Re\*(C'\fR, \f(CW\*(C`Im\*(C'\fR, \f(CW\*(C`arg\*(C'\fR, \f(CW\*(C`abs\*(C'\fR,
348 \&\f(CW\*(C`rho\*(C'\fR, and \f(CW\*(C`theta\*(C'\fR can be used also as mutators. The \f(CW\*(C`cbrt\*(C'\fR
349 returns only one of the solutions: if you want all three, use the
350 \&\f(CW\*(C`root\*(C'\fR function.
351 .PP
352 The \fIroot\fR function is available to compute all the \fIn\fR
353 roots of some complex, where \fIn\fR is a strictly positive integer.
354 There are exactly \fIn\fR such roots, returned as a list. Getting the
355 number mathematicians call \f(CW\*(C`j\*(C'\fR such that:
356 .PP
357 .Vb 1
358 \& 1 + j + j*j = 0;
359 .Ve
360 .PP
361 is a simple matter of writing:
362 .PP
363 .Vb 1
364 \& $j = (root(1, 3))[1];
365 .Ve
366 .PP
367 The \fIk\fRth root for \f(CW\*(C`z = [r,t]\*(C'\fR is given by:
368 .PP
369 .Vb 1
370 \& (root(z, n))[k] = r**(1/n) * exp(i * (t + 2*k*pi)/n)
371 .Ve
372 .PP
373 You can return the \fIk\fRth root directly by \f(CW\*(C`root(z, n, k)\*(C'\fR,
374 indexing starting from \fIzero\fR and ending at \fIn \- 1\fR.
375 .PP
376 The \fIspaceship\fR numeric comparison operator, <=>, is also
377 defined. In order to ensure its restriction to real numbers is conform
378 to what you would expect, the comparison is run on the real part of
379 the complex number first, and imaginary parts are compared only when
380 the real parts match.
381 .SH CREATION
382 .IX Header "CREATION"
383 To create a complex number, use either:
384 .PP
385 .Vb 2
386 \& $z = Math::Complex\->make(3, 4);
387 \& $z = cplx(3, 4);
388 .Ve
389 .PP
390 if you know the cartesian form of the number, or
391 .PP
392 .Vb 1
393 \& $z = 3 + 4*i;
394 .Ve
395 .PP
396 if you like. To create a number using the polar form, use either:
397 .PP
398 .Vb 2
399 \& $z = Math::Complex\->emake(5, pi/3);
400 \& $x = cplxe(5, pi/3);
401 .Ve
402 .PP
403 instead. The first argument is the modulus, the second is the angle
404 (in radians, the full circle is 2*pi). (Mnemonic: \f(CW\*(C`e\*(C'\fR is used as a
405 notation for complex numbers in the polar form).
406 .PP
407 It is possible to write:
408 .PP
409 .Vb 1
410 \& $x = cplxe(\-3, pi/4);
411 .Ve
412 .PP
413 but that will be silently converted into \f(CW\*(C`[3,\-3pi/4]\*(C'\fR, since the
414 modulus must be non\-negative (it represents the distance to the origin
415 in the complex plane).
416 .PP
417 It is also possible to have a complex number as either argument of the
418 \&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`emake\*(C'\fR, \f(CW\*(C`cplx\*(C'\fR, and \f(CW\*(C`cplxe\*(C'\fR: the appropriate component of
419 the argument will be used.
420 .PP
421 .Vb 2
422 \& $z1 = cplx(\-2, 1);
423 \& $z2 = cplx($z1, 4);
424 .Ve
425 .PP
426 The \f(CW\*(C`new\*(C'\fR, \f(CW\*(C`make\*(C'\fR, \f(CW\*(C`emake\*(C'\fR, \f(CW\*(C`cplx\*(C'\fR, and \f(CW\*(C`cplxe\*(C'\fR will also
427 understand a single (string) argument of the forms
428 .PP
429 .Vb 5
430 \& 2\-3i
431 \& \-3i
432 \& [2,3]
433 \& [2,\-3pi/4]
434 \& [2]
435 .Ve
436 .PP
437 in which case the appropriate cartesian and exponential components
438 will be parsed from the string and used to create new complex numbers.
439 The imaginary component and the theta, respectively, will default to zero.
440 .PP
441 The \f(CW\*(C`new\*(C'\fR, \f(CW\*(C`make\*(C'\fR, \f(CW\*(C`emake\*(C'\fR, \f(CW\*(C`cplx\*(C'\fR, and \f(CW\*(C`cplxe\*(C'\fR will also
442 understand the case of no arguments: this means plain zero or (0, 0).
443 .SH DISPLAYING
444 .IX Header "DISPLAYING"
445 When printed, a complex number is usually shown under its cartesian
446 style \fIa+bi\fR, but there are legitimate cases where the polar style
447 \&\fI[r,t]\fR is more appropriate. The process of converting the complex
448 number into a string that can be displayed is known as \fIstringification\fR.
449 .PP
450 By calling the class method \f(CW\*(C`Math::Complex::display_format\*(C'\fR and
451 supplying either \f(CW"polar"\fR or \f(CW"cartesian"\fR as an argument, you
452 override the default display style, which is \f(CW"cartesian"\fR. Not
453 supplying any argument returns the current settings.
454 .PP
455 This default can be overridden on a per\-number basis by calling the
456 \&\f(CW\*(C`display_format\*(C'\fR method instead. As before, not supplying any argument
457 returns the current display style for this number. Otherwise whatever you
458 specify will be the new display style for \fIthis\fR particular number.
459 .PP
460 For instance:
461 .PP
462 .Vb 1
463 \& use Math::Complex;
464 \&
465 \& Math::Complex::display_format(\*(Aqpolar\*(Aq);
466 \& $j = (root(1, 3))[1];
467 \& print "j = $j\en"; # Prints "j = [1,2pi/3]"
468 \& $j\->display_format(\*(Aqcartesian\*(Aq);
469 \& print "j = $j\en"; # Prints "j = \-0.5+0.866025403784439i"
470 .Ve
471 .PP
472 The polar style attempts to emphasize arguments like \fIk*pi/n\fR
473 (where \fIn\fR is a positive integer and \fIk\fR an integer within [\-9, +9]),
474 this is called \fIpolar pretty\-printing\fR.
475 .PP
476 For the reverse of stringifying, see the \f(CW\*(C`make\*(C'\fR and \f(CW\*(C`emake\*(C'\fR.
477 .SS "CHANGED IN PERL 5.6"
478 .IX Subsection "CHANGED IN PERL 5.6"
479 The \f(CW\*(C`display_format\*(C'\fR class method and the corresponding
480 \&\f(CW\*(C`display_format\*(C'\fR object method can now be called using
481 a parameter hash instead of just a one parameter.
482 .PP
483 The old display format style, which can have values \f(CW"cartesian"\fR or
484 \&\f(CW"polar"\fR, can be changed using the \f(CW"style"\fR parameter.
485 .PP
486 .Vb 1
487 \& $j\->display_format(style => "polar");
488 .Ve
489 .PP
490 The one parameter calling convention also still works.
491 .PP
492 .Vb 1
493 \& $j\->display_format("polar");
494 .Ve
495 .PP
496 There are two new display parameters.
497 .PP
498 The first one is \f(CW"format"\fR, which is a \fBsprintf()\fR\-style format string
499 to be used for both numeric parts of the complex number(s). The is
500 somewhat system\-dependent but most often it corresponds to \f(CW"%.15g"\fR.
501 You can revert to the default by setting the \f(CW\*(C`format\*(C'\fR to \f(CW\*(C`undef\*(C'\fR.
502 .PP
503 .Vb 1
504 \& # the $j from the above example
505 \&
506 \& $j\->display_format(\*(Aqformat\*(Aq => \*(Aq%.5f\*(Aq);
507 \& print "j = $j\en"; # Prints "j = \-0.50000+0.86603i"
508 \& $j\->display_format(\*(Aqformat\*(Aq => undef);
509 \& print "j = $j\en"; # Prints "j = \-0.5+0.86603i"
510 .Ve
511 .PP
512 Notice that this affects also the return values of the
513 \&\f(CW\*(C`display_format\*(C'\fR methods: in list context the whole parameter hash
514 will be returned, as opposed to only the style parameter value.
515 This is a potential incompatibility with earlier versions if you
516 have been calling the \f(CW\*(C`display_format\*(C'\fR method in list context.
517 .PP
518 The second new display parameter is \f(CW"polar_pretty_print"\fR, which can
519 be set to true or false, the default being true. See the previous
520 section for what this means.
521 .SH USAGE
522 .IX Header "USAGE"
523 Thanks to overloading, the handling of arithmetics with complex numbers
524 is simple and almost transparent.
525 .PP
526 Here are some examples:
527 .PP
528 .Vb 1
529 \& use Math::Complex;
530 \&
531 \& $j = cplxe(1, 2*pi/3); # $j ** 3 == 1
532 \& print "j = $j, j**3 = ", $j ** 3, "\en";
533 \& print "1 + j + j**2 = ", 1 + $j + $j**2, "\en";
534 \&
535 \& $z = \-16 + 0*i; # Force it to be a complex
536 \& print "sqrt($z) = ", sqrt($z), "\en";
537 \&
538 \& $k = exp(i * 2*pi/3);
539 \& print "$j \- $k = ", $j \- $k, "\en";
540 \&
541 \& $z\->Re(3); # Re, Im, arg, abs,
542 \& $j\->arg(2); # (the last two aka rho, theta)
543 \& # can be used also as mutators.
544 .Ve
545 .SH CONSTANTS
546 .IX Header "CONSTANTS"
547 .SS PI
548 .IX Subsection "PI"
549 The constant \f(CW\*(C`pi\*(C'\fR and some handy multiples of it (pi2, pi4,
550 and pip2 (pi/2) and pip4 (pi/4)) are also available if separately
551 exported:
552 .PP
553 .Vb 2
554 \& use Math::Complex \*(Aq:pi\*(Aq;
555 \& $third_of_circle = pi2 / 3;
556 .Ve
557 .SS Inf
558 .IX Subsection "Inf"
559 The floating point infinity can be exported as a subroutine \fBInf()\fR:
560 .PP
561 .Vb 4
562 \& use Math::Complex qw(Inf sinh);
563 \& my $AlsoInf = Inf() + 42;
564 \& my $AnotherInf = sinh(1e42);
565 \& print "$AlsoInf is $AnotherInf\en" if $AlsoInf == $AnotherInf;
566 .Ve
567 .PP
568 Note that the stringified form of infinity varies between platforms:
569 it can be for example any of
570 .PP
571 .Vb 4
572 \& inf
573 \& infinity
574 \& INF
575 \& 1.#INF
576 .Ve
577 .PP
578 or it can be something else.
579 .PP
580 Also note that in some platforms trying to use the infinity in
581 arithmetic operations may result in Perl crashing because using
582 an infinity causes SIGFPE or its moral equivalent to be sent.
583 The way to ignore this is
584 .PP
585 .Vb 1
586 \& local $SIG{FPE} = sub { };
587 .Ve
588 .SH "ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO"
589 .IX Header "ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO"
590 The division (/) and the following functions
591 .PP
592 .Vb 5
593 \& log ln log10 logn
594 \& tan sec csc cot
595 \& atan asec acsc acot
596 \& tanh sech csch coth
597 \& atanh asech acsch acoth
598 .Ve
599 .PP
600 cannot be computed for all arguments because that would mean dividing
601 by zero or taking logarithm of zero. These situations cause fatal
602 runtime errors looking like this
603 .PP
604 .Vb 3
605 \& cot(0): Division by zero.
606 \& (Because in the definition of cot(0), the divisor sin(0) is 0)
607 \& Died at ...
608 .Ve
609 .PP
610 or
611 .PP
612 .Vb 2
613 \& atanh(\-1): Logarithm of zero.
614 \& Died at...
615 .Ve
616 .PP
617 For the \f(CW\*(C`csc\*(C'\fR, \f(CW\*(C`cot\*(C'\fR, \f(CW\*(C`asec\*(C'\fR, \f(CW\*(C`acsc\*(C'\fR, \f(CW\*(C`acot\*(C'\fR, \f(CW\*(C`csch\*(C'\fR, \f(CW\*(C`coth\*(C'\fR,
618 \&\f(CW\*(C`asech\*(C'\fR, \f(CW\*(C`acsch\*(C'\fR, the argument cannot be \f(CW0\fR (zero). For the
619 logarithmic functions and the \f(CW\*(C`atanh\*(C'\fR, \f(CW\*(C`acoth\*(C'\fR, the argument cannot
620 be \f(CW1\fR (one). For the \f(CW\*(C`atanh\*(C'\fR, \f(CW\*(C`acoth\*(C'\fR, the argument cannot be
621 \&\f(CW\-1\fR (minus one). For the \f(CW\*(C`atan\*(C'\fR, \f(CW\*(C`acot\*(C'\fR, the argument cannot be
622 \&\f(CW\*(C`i\*(C'\fR (the imaginary unit). For the \f(CW\*(C`atan\*(C'\fR, \f(CW\*(C`acoth\*(C'\fR, the argument
623 cannot be \f(CW\*(C`\-i\*(C'\fR (the negative imaginary unit). For the \f(CW\*(C`tan\*(C'\fR,
624 \&\f(CW\*(C`sec\*(C'\fR, \f(CW\*(C`tanh\*(C'\fR, the argument cannot be \fIpi/2 + k * pi\fR, where \fIk\fR
625 is any integer. atan2(0, 0) is undefined, and if the complex arguments
626 are used for \fBatan2()\fR, a division by zero will happen if z1**2+z2**2 == 0.
627 .PP
628 Note that because we are operating on approximations of real numbers,
629 these errors can happen when merely \`too close\*(Aq to the singularities
630 listed above.
631 .SH "ERRORS DUE TO INDIGESTIBLE ARGUMENTS"
632 .IX Header "ERRORS DUE TO INDIGESTIBLE ARGUMENTS"
633 The \f(CW\*(C`make\*(C'\fR and \f(CW\*(C`emake\*(C'\fR accept both real and complex arguments.
634 When they cannot recognize the arguments they will die with error
635 messages like the following
636 .PP
637 .Vb 4
638 \& Math::Complex::make: Cannot take real part of ...
639 \& Math::Complex::make: Cannot take real part of ...
640 \& Math::Complex::emake: Cannot take rho of ...
641 \& Math::Complex::emake: Cannot take theta of ...
642 .Ve
643 .SH BUGS
644 .IX Header "BUGS"
645 Saying \f(CW\*(C`use Math::Complex;\*(C'\fR exports many mathematical routines in the
646 caller environment and even overrides some (\f(CW\*(C`sqrt\*(C'\fR, \f(CW\*(C`log\*(C'\fR, \f(CW\*(C`atan2\*(C'\fR).
647 This is construed as a feature by the Authors, actually... ;\-)
648 .PP
649 All routines expect to be given real or complex numbers. Don\*(Aqt attempt to
650 use BigFloat, since Perl has currently no rule to disambiguate a \*(Aq+\*(Aq
651 operation (for instance) between two overloaded entities.
652 .PP
653 In Cray UNICOS there is some strange numerical instability that results
654 in \fBroot()\fR, \fBcos()\fR, \fBsin()\fR, \fBcosh()\fR, \fBsinh()\fR, losing accuracy fast. Beware.
655 The bug may be in UNICOS math libs, in UNICOS C compiler, in Math::Complex.
656 Whatever it is, it does not manifest itself anywhere else where Perl runs.
657 .SH "SEE ALSO"
658 .IX Header "SEE ALSO"
659 Math::Trig
660 .SH AUTHORS
661 .IX Header "AUTHORS"
662 Daniel S. Lewart <\fIlewart!at!uiuc.edu\fR>,
663 Jarkko Hietaniemi <\fIjhi!at!iki.fi\fR>,
664 Raphael Manfredi <\fIRaphael_Manfredi!at!pobox.com\fR>,
665 Zefram <[email protected]>
666 .SH LICENSE
667 .IX Header "LICENSE"
668 This library is free software; you can redistribute it and/or modify
669 it under the same terms as Perl itself.