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