Debian Codegraph @

upstream/mageia-cauldron/man3pm/Math::Trig.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::Trig 3pm"
61 .TH Math::Trig 3pm 2025-06-24 "perl v5.42.0" "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::Trig \- trigonometric functions
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Math::Trig;
72 \&
73 \& $x = tan(0.9);
74 \& $y = acos(3.7);
75 \& $z = asin(2.4);
76 \&
77 \& $halfpi = pi/2;
78 \&
79 \& $rad = deg2rad(120);
80 \&
81 \& # Import constants pi2, pi4, pip2, pip4 (2*pi, 4*pi, pi/2, pi/4).
82 \& use Math::Trig \*(Aq:pi\*(Aq;
83 \&
84 \& # Import the conversions between cartesian/spherical/cylindrical.
85 \& use Math::Trig \*(Aq:radial\*(Aq;
86 \&
87 \& # Import the great circle formulas.
88 \& use Math::Trig \*(Aq:great_circle\*(Aq;
89 .Ve
90 .SH DESCRIPTION
91 .IX Header "DESCRIPTION"
92 \&\f(CW\*(C`Math::Trig\*(C'\fR defines many trigonometric functions not defined by the
93 core Perl which defines only the \f(CWsin()\fR and \f(CWcos()\fR. The constant
94 \&\fBpi\fR is also defined as are a few convenience functions for angle
95 conversions, and \fIgreat circle formulas\fR for spherical movement.
96 .SH "TRIGONOMETRIC FUNCTIONS"
97 .IX Header "TRIGONOMETRIC FUNCTIONS"
98 The tangent
99 .IP \fBtan\fR 4
100 .IX Item "tan"
101 .PP
102 The cofunctions of the sine, cosine, and tangent (cosec/csc and cotan/cot
103 are aliases)
104 .PP
105 \&\fBcsc\fR, \fBcosec\fR, \fBsec\fR, \fBsec\fR, \fBcot\fR, \fBcotan\fR
106 .PP
107 The arcus (also known as the inverse) functions of the sine, cosine,
108 and tangent
109 .PP
110 \&\fBasin\fR, \fBacos\fR, \fBatan\fR
111 .PP
112 The principal value of the arc tangent of y/x
113 .PP
114 \&\fBatan2\fR(y, x)
115 .PP
116 The arcus cofunctions of the sine, cosine, and tangent (acosec/acsc
117 and acotan/acot are aliases). Note that atan2(0, 0) is not well\-defined.
118 .PP
119 \&\fBacsc\fR, \fBacosec\fR, \fBasec\fR, \fBacot\fR, \fBacotan\fR
120 .PP
121 The hyperbolic sine, cosine, and tangent
122 .PP
123 \&\fBsinh\fR, \fBcosh\fR, \fBtanh\fR
124 .PP
125 The cofunctions of the hyperbolic sine, cosine, and tangent (cosech/csch
126 and cotanh/coth are aliases)
127 .PP
128 \&\fBcsch\fR, \fBcosech\fR, \fBsech\fR, \fBcoth\fR, \fBcotanh\fR
129 .PP
130 The area (also known as the inverse) functions of the hyperbolic
131 sine, cosine, and tangent
132 .PP
133 \&\fBasinh\fR, \fBacosh\fR, \fBatanh\fR
134 .PP
135 The area cofunctions of the hyperbolic sine, cosine, and tangent
136 (acsch/acosech and acoth/acotanh are aliases)
137 .PP
138 \&\fBacsch\fR, \fBacosech\fR, \fBasech\fR, \fBacoth\fR, \fBacotanh\fR
139 .PP
140 The trigonometric constant \fBpi\fR and some of handy multiples
141 of it are also defined.
142 .PP
143 \&\fBpi, pi2, pi4, pip2, pip4\fR
144 .SS "ERRORS DUE TO DIVISION BY ZERO"
145 .IX Subsection "ERRORS DUE TO DIVISION BY ZERO"
146 The following functions
147 .PP
148 .Vb 10
149 \& acoth
150 \& acsc
151 \& acsch
152 \& asec
153 \& asech
154 \& atanh
155 \& cot
156 \& coth
157 \& csc
158 \& csch
159 \& sec
160 \& sech
161 \& tan
162 \& tanh
163 .Ve
164 .PP
165 cannot be computed for all arguments because that would mean dividing
166 by zero or taking logarithm of zero. These situations cause fatal
167 runtime errors looking like this
168 .PP
169 .Vb 3
170 \& cot(0): Division by zero.
171 \& (Because in the definition of cot(0), the divisor sin(0) is 0)
172 \& Died at ...
173 .Ve
174 .PP
175 or
176 .PP
177 .Vb 2
178 \& atanh(\-1): Logarithm of zero.
179 \& Died at...
180 .Ve
181 .PP
182 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,
183 \&\f(CW\*(C`asech\*(C'\fR, \f(CW\*(C`acsch\*(C'\fR, the argument cannot be \f(CW0\fR (zero). For the
184 \&\f(CW\*(C`atanh\*(C'\fR, \f(CW\*(C`acoth\*(C'\fR, the argument cannot be \f(CW1\fR (one). For the
185 \&\f(CW\*(C`atanh\*(C'\fR, \f(CW\*(C`acoth\*(C'\fR, the argument cannot be \f(CW\-1\fR (minus one). For the
186 \&\f(CW\*(C`tan\*(C'\fR, \f(CW\*(C`sec\*(C'\fR, \f(CW\*(C`tanh\*(C'\fR, \f(CW\*(C`sech\*(C'\fR, the argument cannot be \fIpi/2 + k *
187 pi\fR, where \fIk\fR is any integer.
188 .PP
189 Note that atan2(0, 0) is not well\-defined.
190 .SS "SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS"
191 .IX Subsection "SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS"
192 Please note that some of the trigonometric functions can break out
193 from the \fBreal axis\fR into the \fBcomplex plane\fR. For example
194 \&\f(CWasin(2)\fR has no definition for plain real numbers but it has
195 definition for complex numbers.
196 .PP
197 In Perl terms this means that supplying the usual Perl numbers (also
198 known as scalars, please see perldata) as input for the
199 trigonometric functions might produce as output results that no more
200 are simple real numbers: instead they are complex numbers.
201 .PP
202 The \f(CW\*(C`Math::Trig\*(C'\fR handles this by using the \f(CW\*(C`Math::Complex\*(C'\fR package
203 which knows how to handle complex numbers, please see Math::Complex
204 for more information. In practice you need not to worry about getting
205 complex numbers as results because the \f(CW\*(C`Math::Complex\*(C'\fR takes care of
206 details like for example how to display complex numbers. For example:
207 .PP
208 .Vb 1
209 \& print asin(2), "\en";
210 .Ve
211 .PP
212 should produce something like this (take or leave few last decimals):
213 .PP
214 .Vb 1
215 \& 1.5707963267949\-1.31695789692482i
216 .Ve
217 .PP
218 That is, a complex number with the real part of approximately \f(CW1.571\fR
219 and the imaginary part of approximately \f(CW\-1.317\fR.
220 .SH "PLANE ANGLE CONVERSIONS"
221 .IX Header "PLANE ANGLE CONVERSIONS"
222 (Plane, 2\-dimensional) angles may be converted with the following functions.
223 .IP deg2rad 4
224 .IX Item "deg2rad"
225 .Vb 1
226 \& $radians = deg2rad($degrees);
227 .Ve
228 .IP grad2rad 4
229 .IX Item "grad2rad"
230 .Vb 1
231 \& $radians = grad2rad($gradians);
232 .Ve
233 .IP rad2deg 4
234 .IX Item "rad2deg"
235 .Vb 1
236 \& $degrees = rad2deg($radians);
237 .Ve
238 .IP grad2deg 4
239 .IX Item "grad2deg"
240 .Vb 1
241 \& $degrees = grad2deg($gradians);
242 .Ve
243 .IP deg2grad 4
244 .IX Item "deg2grad"
245 .Vb 1
246 \& $gradians = deg2grad($degrees);
247 .Ve
248 .IP rad2grad 4
249 .IX Item "rad2grad"
250 .Vb 1
251 \& $gradians = rad2grad($radians);
252 .Ve
253 .PP
254 The full circle is 2 \fIpi\fR radians or \fI360\fR degrees or \fI400\fR gradians.
255 The result is by default wrapped to be inside the [0, {2pi,360,400}) circle.
256 If you don\*(Aqt want this, supply a true second argument:
257 .PP
258 .Vb 2
259 \& $zillions_of_radians = deg2rad($zillions_of_degrees, 1);
260 \& $negative_degrees = rad2deg($negative_radians, 1);
261 .Ve
262 .PP
263 You can also do the wrapping explicitly by \fBrad2rad()\fR, \fBdeg2deg()\fR, and
264 \&\fBgrad2grad()\fR.
265 .IP rad2rad 4
266 .IX Item "rad2rad"
267 .Vb 1
268 \& $radians_wrapped_by_2pi = rad2rad($radians);
269 .Ve
270 .IP deg2deg 4
271 .IX Item "deg2deg"
272 .Vb 1
273 \& $degrees_wrapped_by_360 = deg2deg($degrees);
274 .Ve
275 .IP grad2grad 4
276 .IX Item "grad2grad"
277 .Vb 1
278 \& $gradians_wrapped_by_400 = grad2grad($gradians);
279 .Ve
280 .SH "RADIAL COORDINATE CONVERSIONS"
281 .IX Header "RADIAL COORDINATE CONVERSIONS"
282 \&\fBRadial coordinate systems\fR are the \fBspherical\fR and the \fBcylindrical\fR
283 systems, explained shortly in more detail.
284 .PP
285 You can import radial coordinate conversion functions by using the
286 \&\f(CW\*(C`:radial\*(C'\fR tag:
287 .PP
288 .Vb 1
289 \& use Math::Trig \*(Aq:radial\*(Aq;
290 \&
291 \& ($rho, $theta, $z) = cartesian_to_cylindrical($x, $y, $z);
292 \& ($rho, $theta, $phi) = cartesian_to_spherical($x, $y, $z);
293 \& ($x, $y, $z) = cylindrical_to_cartesian($rho, $theta, $z);
294 \& ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);
295 \& ($x, $y, $z) = spherical_to_cartesian($rho, $theta, $phi);
296 \& ($rho_c, $theta, $z) = spherical_to_cylindrical($rho_s, $theta, $phi);
297 .Ve
298 .PP
299 \&\fBAll angles are in radians\fR.
300 .SS "COORDINATE SYSTEMS"
301 .IX Subsection "COORDINATE SYSTEMS"
302 \&\fBCartesian\fR coordinates are the usual rectangular \fI(x, y, z)\fR\-coordinates.
303 .PP
304 Spherical coordinates, \fI(rho, theta, phi)\fR, are three\-dimensional
305 coordinates which define a point in three\-dimensional space. They are
306 based on a sphere surface. The radius of the sphere is \fBrho\fR, also
307 known as the \fIradial\fR coordinate. The angle in the \fIxy\fR\-plane
308 (around the \fIz\fR\-axis) is \fBtheta\fR, also known as the \fIazimuthal\fR
309 coordinate. The angle from the \fIz\fR\-axis is \fBphi\fR, also known as the
310 \&\fIpolar\fR coordinate. The North Pole is therefore \fIrho, 0, 0\fR, and
311 the Gulf of Guinea (think of the missing big chunk of Africa) \fIrho,
312 0, pi/2\fR. In geographical terms \fIphi\fR is latitude (northward
313 positive, southward negative) and \fItheta\fR is longitude (eastward
314 positive, westward negative).
315 .PP
316 \&\fBBEWARE\fR: some texts define \fItheta\fR and \fIphi\fR the other way round,
317 some texts define the \fIphi\fR to start from the horizontal plane, some
318 texts use \fIr\fR in place of \fIrho\fR.
319 .PP
320 Cylindrical coordinates, \fI(rho, theta, z)\fR, are three\-dimensional
321 coordinates which define a point in three\-dimensional space. They are
322 based on a cylinder surface. The radius of the cylinder is \fBrho\fR,
323 also known as the \fIradial\fR coordinate. The angle in the \fIxy\fR\-plane
324 (around the \fIz\fR\-axis) is \fBtheta\fR, also known as the \fIazimuthal\fR
325 coordinate. The third coordinate is the \fIz\fR, pointing up from the
326 \&\fBtheta\fR\-plane.
327 .SS "3\-D ANGLE CONVERSIONS"
328 .IX Subsection "3-D ANGLE CONVERSIONS"
329 Conversions to and from spherical and cylindrical coordinates are
330 available. Please notice that the conversions are not necessarily
331 reversible because of the equalities like \fIpi\fR angles being equal to
332 \&\fI\-pi\fR angles.
333 .IP cartesian_to_cylindrical 4
334 .IX Item "cartesian_to_cylindrical"
335 .Vb 1
336 \& ($rho, $theta, $z) = cartesian_to_cylindrical($x, $y, $z);
337 .Ve
338 .IP cartesian_to_spherical 4
339 .IX Item "cartesian_to_spherical"
340 .Vb 1
341 \& ($rho, $theta, $phi) = cartesian_to_spherical($x, $y, $z);
342 .Ve
343 .IP cylindrical_to_cartesian 4
344 .IX Item "cylindrical_to_cartesian"
345 .Vb 1
346 \& ($x, $y, $z) = cylindrical_to_cartesian($rho, $theta, $z);
347 .Ve
348 .IP cylindrical_to_spherical 4
349 .IX Item "cylindrical_to_spherical"
350 .Vb 1
351 \& ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);
352 .Ve
353 .Sp
354 Notice that when \f(CW$z\fR is not 0 \f(CW$rho_s\fR is not equal to \f(CW$rho_c\fR.
355 .IP spherical_to_cartesian 4
356 .IX Item "spherical_to_cartesian"
357 .Vb 1
358 \& ($x, $y, $z) = spherical_to_cartesian($rho, $theta, $phi);
359 .Ve
360 .IP spherical_to_cylindrical 4
361 .IX Item "spherical_to_cylindrical"
362 .Vb 1
363 \& ($rho_c, $theta, $z) = spherical_to_cylindrical($rho_s, $theta, $phi);
364 .Ve
365 .Sp
366 Notice that when \f(CW$z\fR is not 0 \f(CW$rho_c\fR is not equal to \f(CW$rho_s\fR.
367 .SH "GREAT CIRCLE DISTANCES AND DIRECTIONS"
368 .IX Header "GREAT CIRCLE DISTANCES AND DIRECTIONS"
369 A great circle is section of a circle that contains the circle
370 diameter: the shortest distance between two (non\-antipodal) points on
371 the spherical surface goes along the great circle connecting those two
372 points.
373 .SS great_circle_distance
374 .IX Subsection "great_circle_distance"
375 Returns the great circle distance between two points on a sphere.
376 .PP
377 .Vb 1
378 \& $distance = great_circle_distance($theta0, $phi0, $theta1, $phi1, [, $rho]);
379 .Ve
380 .PP
381 Where ($theta0, \f(CW$phi0\fR) and ($theta1, \f(CW$phi1\fR) are the spherical coordinates of
382 the two points, respectively. The distance is in \f(CW$rho\fR units. The \f(CW$rho\fR
383 is optional. It defaults to 1 (the unit sphere).
384 .PP
385 If you are using geographic coordinates, latitude and longitude, you need to
386 adjust for the fact that latitude is zero at the equator increasing towards
387 the north and decreasing towards the south. Assuming ($lat0, \f(CW$lon0\fR) and
388 ($lat1, \f(CW$lon1\fR) are the geographic coordinates in radians of the two points,
389 the distance can be computed with
390 .PP
391 .Vb 2
392 \& $distance = great_circle_distance($lon0, pi/2 \- $lat0,
393 \& $lon1, pi/2 \- $lat1, $rho);
394 .Ve
395 .SS great_circle_direction
396 .IX Subsection "great_circle_direction"
397 The direction you must follow the great circle (also known as \fIbearing\fR)
398 can be computed by the \fBgreat_circle_direction()\fR function:
399 .PP
400 .Vb 1
401 \& use Math::Trig \*(Aqgreat_circle_direction\*(Aq;
402 \&
403 \& $direction = great_circle_direction($theta0, $phi0, $theta1, $phi1);
404 .Ve
405 .SS great_circle_bearing
406 .IX Subsection "great_circle_bearing"
407 Alias \*(Aqgreat_circle_bearing\*(Aq for \*(Aqgreat_circle_direction\*(Aq is also available.
408 .PP
409 .Vb 1
410 \& use Math::Trig \*(Aqgreat_circle_bearing\*(Aq;
411 \&
412 \& $direction = great_circle_bearing($theta0, $phi0, $theta1, $phi1);
413 .Ve
414 .PP
415 The result of great_circle_direction is in radians, zero indicating
416 straight north, pi or \-pi straight south, pi/2 straight west, and
417 \&\-pi/2 straight east.
418 .SS great_circle_destination
419 .IX Subsection "great_circle_destination"
420 You can inversely compute the destination if you know the
421 starting point, direction, and distance:
422 .PP
423 .Vb 1
424 \& use Math::Trig \*(Aqgreat_circle_destination\*(Aq;
425 \&
426 \& # $diro is the original direction,
427 \& # for example from great_circle_bearing().
428 \& # $distance is the angular distance in radians,
429 \& # for example from great_circle_distance().
430 \& # $thetad and $phid are the destination coordinates,
431 \& # $dird is the final direction at the destination.
432 \&
433 \& ($thetad, $phid, $dird) =
434 \& great_circle_destination($theta, $phi, $diro, $distance);
435 .Ve
436 .PP
437 or the midpoint if you know the end points:
438 .SS great_circle_midpoint
439 .IX Subsection "great_circle_midpoint"
440 .Vb 1
441 \& use Math::Trig \*(Aqgreat_circle_midpoint\*(Aq;
442 \&
443 \& ($thetam, $phim) =
444 \& great_circle_midpoint($theta0, $phi0, $theta1, $phi1);
445 .Ve
446 .PP
447 The \fBgreat_circle_midpoint()\fR is just a special case of
448 .SS great_circle_waypoint
449 .IX Subsection "great_circle_waypoint"
450 .Vb 1
451 \& use Math::Trig \*(Aqgreat_circle_waypoint\*(Aq;
452 \&
453 \& ($thetai, $phii) =
454 \& great_circle_waypoint($theta0, $phi0, $theta1, $phi1, $way);
455 .Ve
456 .PP
457 Where \f(CW$way\fR indicates the position of the waypoint along the great
458 circle arc through the starting point ($theta0, \f(CW$phi0\fR) and the end
459 point ($theta1, \f(CW$phi1\fR) relative to the distance from the starting
460 point to the end point. So \f(CW$way\fR = 0 gives the starting point, \f(CW$way\fR = 1
461 gives the end point, \f(CW$way\fR < 0 gives a point "behind" the starting
462 point, and \f(CW$way\fR > 1 gives a point beyond the end point. \f(CW$way\fR defaults
463 to 0.5 if not given.
464 .PP
465 Note that antipodal points (where their distance is \fIpi\fR radians) do
466 not have unique waypoints between them, and therefore \f(CW\*(C`undef\*(C'\fR is
467 returned in such cases. If the points are the same, so the distance
468 between them is zero, all waypoints are identical to the starting/end
469 point.
470 .PP
471 The thetas, phis, direction, and distance in the above are all in
472 radians.
473 .PP
474 You can import all the great circle formulas by
475 .PP
476 .Vb 1
477 \& use Math::Trig \*(Aq:great_circle\*(Aq;
478 .Ve
479 .PP
480 Notice that the resulting directions might be somewhat surprising if
481 you are looking at a flat worldmap: in such map projections the great
482 circles quite often do not look like the shortest routes \-\- but for
483 example the shortest possible routes from Europe or North America to
484 Asia do often cross the polar regions. (The common Mercator projection
485 does \fBnot\fR show great circles as straight lines: straight lines in the
486 Mercator projection are lines of constant bearing.)
487 .SH EXAMPLES
488 .IX Header "EXAMPLES"
489 To calculate the distance between London (51.3N 0.5W) and Tokyo
490 (35.7N 139.8E) in kilometers:
491 .PP
492 .Vb 1
493 \& use Math::Trig qw(great_circle_distance deg2rad);
494 \&
495 \& # Notice the 90 \- latitude: phi zero is at the North Pole.
496 \& sub NESW { deg2rad($_[0]), deg2rad(90 \- $_[1]) }
497 \& my @L = NESW( \-0.5, 51.3);
498 \& my @T = NESW(139.8, 35.7);
499 \& my $km = great_circle_distance(@L, @T, 6378); # About 9600 km.
500 .Ve
501 .PP
502 The direction you would have to go from London to Tokyo (in radians,
503 straight north being zero, straight east being pi/2).
504 .PP
505 .Vb 1
506 \& use Math::Trig qw(great_circle_direction);
507 \&
508 \& my $rad = great_circle_direction(@L, @T); # About 0.547 or 0.174 pi.
509 .Ve
510 .PP
511 The midpoint between London and Tokyo being
512 .PP
513 .Vb 1
514 \& use Math::Trig qw(great_circle_midpoint rad2deg);
515 \&
516 \& my @M = great_circle_midpoint(@L, @T);
517 \& sub SWNE { rad2deg( $_[0] ), 90 \- rad2deg( $_[1] ) }
518 \& my @lonlat = SWNE(@M);
519 .Ve
520 .PP
521 or about 69 N 89 E, on the Putorana Plateau of Siberia.
522 .PP
523 \&\fBNOTE\fR: you \fBcannot\fR get from A to B like this:
524 .PP
525 .Vb 3
526 \& Dist = great_circle_distance(A, B)
527 \& Dir = great_circle_direction(A, B)
528 \& C = great_circle_destination(A, Dist, Dir)
529 .Ve
530 .PP
531 and expect C to be B, because the bearing constantly changes when
532 going from A to B (except in some special case like the meridians or
533 the circles of latitudes) and in \fBgreat_circle_destination()\fR one gives
534 a \fBconstant\fR bearing to follow.
535 .SS "CAVEAT FOR GREAT CIRCLE FORMULAS"
536 .IX Subsection "CAVEAT FOR GREAT CIRCLE FORMULAS"
537 The answers may be off by few percentages because of the irregular
538 (slightly aspherical) form of the Earth. The errors are at worst
539 about 0.55%, but generally below 0.3%.
540 .SS "Real\-valued asin and acos"
541 .IX Subsection "Real-valued asin and acos"
542 For small inputs \fBasin()\fR and \fBacos()\fR may return complex numbers even
543 when real numbers would be enough and correct, this happens because of
544 floating\-point inaccuracies. You can see these inaccuracies for
545 example by trying theses:
546 .PP
547 .Vb 2
548 \& print cos(1e\-6)**2+sin(1e\-6)**2 \- 1,"\en";
549 \& printf "%.20f", cos(1e\-6)**2+sin(1e\-6)**2,"\en";
550 .Ve
551 .PP
552 which will print something like this
553 .PP
554 .Vb 2
555 \& \-1.11022302462516e\-16
556 \& 0.99999999999999988898
557 .Ve
558 .PP
559 even though the expected results are of course exactly zero and one.
560 The formulas used to compute \fBasin()\fR and \fBacos()\fR are quite sensitive to
561 this, and therefore they might accidentally slip into the complex
562 plane even when they should not. To counter this there are two
563 interfaces that are guaranteed to return a real\-valued output.
564 .IP asin_real 4
565 .IX Item "asin_real"
566 .Vb 1
567 \& use Math::Trig qw(asin_real);
568 \&
569 \& $real_angle = asin_real($input_sin);
570 .Ve
571 .Sp
572 Return a real\-valued arcus sine if the input is between [\-1, 1],
573 \&\fBinclusive\fR the endpoints. For inputs greater than one, pi/2
574 is returned. For inputs less than minus one, \-pi/2 is returned.
575 .IP acos_real 4
576 .IX Item "acos_real"
577 .Vb 1
578 \& use Math::Trig qw(acos_real);
579 \&
580 \& $real_angle = acos_real($input_cos);
581 .Ve
582 .Sp
583 Return a real\-valued arcus cosine if the input is between [\-1, 1],
584 \&\fBinclusive\fR the endpoints. For inputs greater than one, zero
585 is returned. For inputs less than minus one, pi is returned.
586 .SH BUGS
587 .IX Header "BUGS"
588 Saying \f(CW\*(C`use Math::Trig;\*(C'\fR exports many mathematical routines in the
589 caller environment and even overrides some (\f(CW\*(C`sin\*(C'\fR, \f(CW\*(C`cos\*(C'\fR). This is
590 construed as a feature by the Authors, actually... ;\-)
591 .PP
592 The code is not optimized for speed, especially because we use
593 \&\f(CW\*(C`Math::Complex\*(C'\fR and thus go quite near complex numbers while doing
594 the computations even when the arguments are not. This, however,
595 cannot be completely avoided if we want things like \f(CWasin(2)\fR to give
596 an answer instead of giving a fatal runtime error.
597 .PP
598 Do not attempt navigation using these formulas.
599 .SH "SEE ALSO"
600 .IX Header "SEE ALSO"
601 Math::Complex
602 .SH AUTHORS
603 .IX Header "AUTHORS"
604 Jarkko Hietaniemi <\fIjhi!at!iki.fi\fR>,
605 Raphael Manfredi <\fIRaphael_Manfredi!at!pobox.com\fR>,
606 Zefram <[email protected]>
607 .SH LICENSE
608 .IX Header "LICENSE"
609 This library is free software; you can redistribute it and/or modify
610 it under the same terms as Perl itself.