Debian Codegraph @

upstream/debian-unstable/man3/Math::Complex.3perl

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