Debian Codegraph @

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