This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
d8ecf69be4a31fa17ac840b03f4993bd310ce70d
[perl5.git] / lib / Math / Trig.pm
1 #
2 # Trigonometric functions, mostly inherited from Math::Complex.
3 # -- Jarkko Hietaniemi, since April 1997
4 # -- Raphael Manfredi, September 1996 (indirectly: because of Math::Complex)
5 #
6
7 require Exporter;
8 package Math::Trig;
9
10 use 5.005;
11 use strict;
12
13 use Math::Complex 1.47;
14 use Math::Complex qw(:trig :pi);
15
16 use vars qw($VERSION $PACKAGE @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
17
18 @ISA = qw(Exporter);
19
20 $VERSION = 1.12;
21
22 my @angcnv = qw(rad2deg rad2grad
23                 deg2rad deg2grad
24                 grad2rad grad2deg);
25
26 my @areal = qw(asin_real acos_real);
27
28 @EXPORT = (@{$Math::Complex::EXPORT_TAGS{'trig'}},
29            @angcnv, @areal);
30
31 my @rdlcnv = qw(cartesian_to_cylindrical
32                 cartesian_to_spherical
33                 cylindrical_to_cartesian
34                 cylindrical_to_spherical
35                 spherical_to_cartesian
36                 spherical_to_cylindrical);
37
38 my @greatcircle = qw(
39                      great_circle_distance
40                      great_circle_direction
41                      great_circle_bearing
42                      great_circle_waypoint
43                      great_circle_midpoint
44                      great_circle_destination
45                     );
46
47 my @pi = qw(pi pi2 pi4 pip2 pip4);
48
49 @EXPORT_OK = (@rdlcnv, @greatcircle, @pi, 'Inf');
50
51 # See e.g. the following pages:
52 # http://www.movable-type.co.uk/scripts/LatLong.html
53 # http://williams.best.vwh.net/avform.htm
54
55 %EXPORT_TAGS = ('radial' => [ @rdlcnv ],
56                 'great_circle' => [ @greatcircle ],
57                 'pi'     => [ @pi ]);
58
59 sub _DR  () { pi2/360 }
60 sub _RD  () { 360/pi2 }
61 sub _DG  () { 400/360 }
62 sub _GD  () { 360/400 }
63 sub _RG  () { 400/pi2 }
64 sub _GR  () { pi2/400 }
65
66 #
67 # Truncating remainder.
68 #
69
70 sub _remt ($$) {
71     # Oh yes, POSIX::fmod() would be faster. Possibly. If it is available.
72     $_[0] - $_[1] * int($_[0] / $_[1]);
73 }
74
75 #
76 # Angle conversions.
77 #
78
79 sub rad2rad($)     { _remt($_[0], pi2) }
80
81 sub deg2deg($)     { _remt($_[0], 360) }
82
83 sub grad2grad($)   { _remt($_[0], 400) }
84
85 sub rad2deg ($;$)  { my $d = _RD * $_[0]; $_[1] ? $d : deg2deg($d) }
86
87 sub deg2rad ($;$)  { my $d = _DR * $_[0]; $_[1] ? $d : rad2rad($d) }
88
89 sub grad2deg ($;$) { my $d = _GD * $_[0]; $_[1] ? $d : deg2deg($d) }
90
91 sub deg2grad ($;$) { my $d = _DG * $_[0]; $_[1] ? $d : grad2grad($d) }
92
93 sub rad2grad ($;$) { my $d = _RG * $_[0]; $_[1] ? $d : grad2grad($d) }
94
95 sub grad2rad ($;$) { my $d = _GR * $_[0]; $_[1] ? $d : rad2rad($d) }
96
97 #
98 # acos and asin functions which always return a real number
99 #
100
101 sub acos_real {
102     return 0  if $_[0] >=  1;
103     return pi if $_[0] <= -1;
104     return acos($_[0]);
105 }
106
107 sub asin_real {
108     return  &pip2 if $_[0] >=  1;
109     return -&pip2 if $_[0] <= -1;
110     return asin($_[0]);
111 }
112
113 sub cartesian_to_spherical {
114     my ( $x, $y, $z ) = @_;
115
116     my $rho = sqrt( $x * $x + $y * $y + $z * $z );
117
118     return ( $rho,
119              atan2( $y, $x ),
120              $rho ? acos_real( $z / $rho ) : 0 );
121 }
122
123 sub spherical_to_cartesian {
124     my ( $rho, $theta, $phi ) = @_;
125
126     return ( $rho * cos( $theta ) * sin( $phi ),
127              $rho * sin( $theta ) * sin( $phi ),
128              $rho * cos( $phi   ) );
129 }
130
131 sub spherical_to_cylindrical {
132     my ( $x, $y, $z ) = spherical_to_cartesian( @_ );
133
134     return ( sqrt( $x * $x + $y * $y ), $_[1], $z );
135 }
136
137 sub cartesian_to_cylindrical {
138     my ( $x, $y, $z ) = @_;
139
140     return ( sqrt( $x * $x + $y * $y ), atan2( $y, $x ), $z );
141 }
142
143 sub cylindrical_to_cartesian {
144     my ( $rho, $theta, $z ) = @_;
145
146     return ( $rho * cos( $theta ), $rho * sin( $theta ), $z );
147 }
148
149 sub cylindrical_to_spherical {
150     return ( cartesian_to_spherical( cylindrical_to_cartesian( @_ ) ) );
151 }
152
153 sub great_circle_distance {
154     my ( $theta0, $phi0, $theta1, $phi1, $rho ) = @_;
155
156     $rho = 1 unless defined $rho; # Default to the unit sphere.
157
158     my $lat0 = pip2 - $phi0;
159     my $lat1 = pip2 - $phi1;
160
161     return $rho *
162         acos_real( cos( $lat0 ) * cos( $lat1 ) * cos( $theta0 - $theta1 ) +
163                    sin( $lat0 ) * sin( $lat1 ) );
164 }
165
166 sub great_circle_direction {
167     my ( $theta0, $phi0, $theta1, $phi1 ) = @_;
168
169     my $distance = &great_circle_distance;
170
171     my $lat0 = pip2 - $phi0;
172     my $lat1 = pip2 - $phi1;
173
174     my $direction =
175         acos_real((sin($lat1) - sin($lat0) * cos($distance)) /
176                   (cos($lat0) * sin($distance)));
177   
178     $direction = pi2 - $direction
179         if sin($theta1 - $theta0) < 0;
180
181     return rad2rad($direction);
182 }
183
184 *great_circle_bearing = \&great_circle_direction;
185
186 sub great_circle_waypoint {
187     my ( $theta0, $phi0, $theta1, $phi1, $point ) = @_;
188
189     $point = 0.5 unless defined $point;
190
191     my $d = great_circle_distance( $theta0, $phi0, $theta1, $phi1 );
192
193     return undef if $d == pi;
194
195     my $sd = sin($d);
196
197     return ($theta0, $phi0) if $sd == 0;
198
199     my $A = sin((1 - $point) * $d) / $sd;
200     my $B = sin(     $point  * $d) / $sd;
201
202     my $lat0 = pip2 - $phi0;
203     my $lat1 = pip2 - $phi1;
204
205     my $x = $A * cos($lat0) * cos($theta0) + $B * cos($lat1) * cos($theta1);
206     my $y = $A * cos($lat0) * sin($theta0) + $B * cos($lat1) * sin($theta1);
207     my $z = $A * sin($lat0)                + $B * sin($lat1);
208
209     my $theta = atan2($y, $x);
210     my $phi   = acos_real($z);
211     
212     return ($theta, $phi);
213 }
214
215 sub great_circle_midpoint {
216     great_circle_waypoint(@_[0..3], 0.5);
217 }
218
219 sub great_circle_destination {
220     my ( $theta0, $phi0, $dir0, $dst ) = @_;
221
222     my $lat0 = pip2 - $phi0;
223
224     my $phi1   = asin_real(sin($lat0)*cos($dst) + 
225                            cos($lat0)*sin($dst)*cos($dir0));
226     my $theta1 = $theta0 + atan2(sin($dir0)*sin($dst)*cos($lat0),
227                                  cos($dst)-sin($lat0)*sin($phi1));
228
229     my $dir1 = great_circle_bearing($theta1, $phi1, $theta0, $phi0) + pi;
230
231     $dir1 -= pi2 if $dir1 > pi2;
232
233     return ($theta1, $phi1, $dir1);
234 }
235
236 1;
237
238 __END__
239 =pod
240
241 =head1 NAME
242
243 Math::Trig - trigonometric functions
244
245 =head1 SYNOPSIS
246
247     use Math::Trig;
248
249     $x = tan(0.9);
250     $y = acos(3.7);
251     $z = asin(2.4);
252
253     $halfpi = pi/2;
254
255     $rad = deg2rad(120);
256
257     # Import constants pi2, pip2, pip4 (2*pi, pi/2, pi/4).
258     use Math::Trig ':pi';
259
260     # Import the conversions between cartesian/spherical/cylindrical.
261     use Math::Trig ':radial';
262
263         # Import the great circle formulas.
264     use Math::Trig ':great_circle';
265
266 =head1 DESCRIPTION
267
268 C<Math::Trig> defines many trigonometric functions not defined by the
269 core Perl which defines only the C<sin()> and C<cos()>.  The constant
270 B<pi> is also defined as are a few convenience functions for angle
271 conversions, and I<great circle formulas> for spherical movement.
272
273 =head1 TRIGONOMETRIC FUNCTIONS
274
275 The tangent
276
277 =over 4
278
279 =item B<tan>
280
281 =back
282
283 The cofunctions of the sine, cosine, and tangent (cosec/csc and cotan/cot
284 are aliases)
285
286 B<csc>, B<cosec>, B<sec>, B<sec>, B<cot>, B<cotan>
287
288 The arcus (also known as the inverse) functions of the sine, cosine,
289 and tangent
290
291 B<asin>, B<acos>, B<atan>
292
293 The principal value of the arc tangent of y/x
294
295 B<atan2>(y, x)
296
297 The arcus cofunctions of the sine, cosine, and tangent (acosec/acsc
298 and acotan/acot are aliases).  Note that atan2(0, 0) is not well-defined.
299
300 B<acsc>, B<acosec>, B<asec>, B<acot>, B<acotan>
301
302 The hyperbolic sine, cosine, and tangent
303
304 B<sinh>, B<cosh>, B<tanh>
305
306 The cofunctions of the hyperbolic sine, cosine, and tangent (cosech/csch
307 and cotanh/coth are aliases)
308
309 B<csch>, B<cosech>, B<sech>, B<coth>, B<cotanh>
310
311 The arcus (also known as the inverse) functions of the hyperbolic
312 sine, cosine, and tangent
313
314 B<asinh>, B<acosh>, B<atanh>
315
316 The arcus cofunctions of the hyperbolic sine, cosine, and tangent
317 (acsch/acosech and acoth/acotanh are aliases)
318
319 B<acsch>, B<acosech>, B<asech>, B<acoth>, B<acotanh>
320
321 The trigonometric constant B<pi> and some of handy multiples
322 of it are also defined.
323
324 B<pi, pi2, pi4, pip2, pip4>
325
326 =head2 ERRORS DUE TO DIVISION BY ZERO
327
328 The following functions
329
330     acoth
331     acsc
332     acsch
333     asec
334     asech
335     atanh
336     cot
337     coth
338     csc
339     csch
340     sec
341     sech
342     tan
343     tanh
344
345 cannot be computed for all arguments because that would mean dividing
346 by zero or taking logarithm of zero. These situations cause fatal
347 runtime errors looking like this
348
349     cot(0): Division by zero.
350     (Because in the definition of cot(0), the divisor sin(0) is 0)
351     Died at ...
352
353 or
354
355     atanh(-1): Logarithm of zero.
356     Died at...
357
358 For the C<csc>, C<cot>, C<asec>, C<acsc>, C<acot>, C<csch>, C<coth>,
359 C<asech>, C<acsch>, the argument cannot be C<0> (zero).  For the
360 C<atanh>, C<acoth>, the argument cannot be C<1> (one).  For the
361 C<atanh>, C<acoth>, the argument cannot be C<-1> (minus one).  For the
362 C<tan>, C<sec>, C<tanh>, C<sech>, the argument cannot be I<pi/2 + k *
363 pi>, where I<k> is any integer.
364
365 Note that atan2(0, 0) is not well-defined.
366
367 =head2 SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS
368
369 Please note that some of the trigonometric functions can break out
370 from the B<real axis> into the B<complex plane>. For example
371 C<asin(2)> has no definition for plain real numbers but it has
372 definition for complex numbers.
373
374 In Perl terms this means that supplying the usual Perl numbers (also
375 known as scalars, please see L<perldata>) as input for the
376 trigonometric functions might produce as output results that no more
377 are simple real numbers: instead they are complex numbers.
378
379 The C<Math::Trig> handles this by using the C<Math::Complex> package
380 which knows how to handle complex numbers, please see L<Math::Complex>
381 for more information. In practice you need not to worry about getting
382 complex numbers as results because the C<Math::Complex> takes care of
383 details like for example how to display complex numbers. For example:
384
385     print asin(2), "\n";
386
387 should produce something like this (take or leave few last decimals):
388
389     1.5707963267949-1.31695789692482i
390
391 That is, a complex number with the real part of approximately C<1.571>
392 and the imaginary part of approximately C<-1.317>.
393
394 =head1 PLANE ANGLE CONVERSIONS
395
396 (Plane, 2-dimensional) angles may be converted with the following functions.
397
398 =over
399
400 =item deg2rad
401
402     $radians  = deg2rad($degrees);
403
404 =item grad2rad
405
406     $radians  = grad2rad($gradians);
407
408 =item rad2deg
409
410     $degrees  = rad2deg($radians);
411
412 =item grad2deg
413
414     $degrees  = grad2deg($gradians);
415
416 =item deg2grad
417
418     $gradians = deg2grad($degrees);
419
420 =item rad2grad
421
422     $gradians = rad2grad($radians);
423
424 =back
425
426 The full circle is 2 I<pi> radians or I<360> degrees or I<400> gradians.
427 The result is by default wrapped to be inside the [0, {2pi,360,400}[ circle.
428 If you don't want this, supply a true second argument:
429
430     $zillions_of_radians  = deg2rad($zillions_of_degrees, 1);
431     $negative_degrees     = rad2deg($negative_radians, 1);
432
433 You can also do the wrapping explicitly by rad2rad(), deg2deg(), and
434 grad2grad().
435
436 =over 4
437
438 =item rad2rad
439
440     $radians_wrapped_by_2pi = rad2rad($radians);
441
442 =item deg2deg
443
444     $degrees_wrapped_by_360 = deg2deg($degrees);
445
446 =item grad2grad
447
448     $gradians_wrapped_by_400 = grad2grad($gradians);
449
450 =back
451
452 =head1 RADIAL COORDINATE CONVERSIONS
453
454 B<Radial coordinate systems> are the B<spherical> and the B<cylindrical>
455 systems, explained shortly in more detail.
456
457 You can import radial coordinate conversion functions by using the
458 C<:radial> tag:
459
460     use Math::Trig ':radial';
461
462     ($rho, $theta, $z)     = cartesian_to_cylindrical($x, $y, $z);
463     ($rho, $theta, $phi)   = cartesian_to_spherical($x, $y, $z);
464     ($x, $y, $z)           = cylindrical_to_cartesian($rho, $theta, $z);
465     ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);
466     ($x, $y, $z)           = spherical_to_cartesian($rho, $theta, $phi);
467     ($rho_c, $theta, $z)   = spherical_to_cylindrical($rho_s, $theta, $phi);
468
469 B<All angles are in radians>.
470
471 =head2 COORDINATE SYSTEMS
472
473 B<Cartesian> coordinates are the usual rectangular I<(x, y, z)>-coordinates.
474
475 Spherical coordinates, I<(rho, theta, pi)>, are three-dimensional
476 coordinates which define a point in three-dimensional space.  They are
477 based on a sphere surface.  The radius of the sphere is B<rho>, also
478 known as the I<radial> coordinate.  The angle in the I<xy>-plane
479 (around the I<z>-axis) is B<theta>, also known as the I<azimuthal>
480 coordinate.  The angle from the I<z>-axis is B<phi>, also known as the
481 I<polar> coordinate.  The North Pole is therefore I<0, 0, rho>, and
482 the Gulf of Guinea (think of the missing big chunk of Africa) I<0,
483 pi/2, rho>.  In geographical terms I<phi> is latitude (northward
484 positive, southward negative) and I<theta> is longitude (eastward
485 positive, westward negative).
486
487 B<BEWARE>: some texts define I<theta> and I<phi> the other way round,
488 some texts define the I<phi> to start from the horizontal plane, some
489 texts use I<r> in place of I<rho>.
490
491 Cylindrical coordinates, I<(rho, theta, z)>, are three-dimensional
492 coordinates which define a point in three-dimensional space.  They are
493 based on a cylinder surface.  The radius of the cylinder is B<rho>,
494 also known as the I<radial> coordinate.  The angle in the I<xy>-plane
495 (around the I<z>-axis) is B<theta>, also known as the I<azimuthal>
496 coordinate.  The third coordinate is the I<z>, pointing up from the
497 B<theta>-plane.
498
499 =head2 3-D ANGLE CONVERSIONS
500
501 Conversions to and from spherical and cylindrical coordinates are
502 available.  Please notice that the conversions are not necessarily
503 reversible because of the equalities like I<pi> angles being equal to
504 I<-pi> angles.
505
506 =over 4
507
508 =item cartesian_to_cylindrical
509
510     ($rho, $theta, $z) = cartesian_to_cylindrical($x, $y, $z);
511
512 =item cartesian_to_spherical
513
514     ($rho, $theta, $phi) = cartesian_to_spherical($x, $y, $z);
515
516 =item cylindrical_to_cartesian
517
518     ($x, $y, $z) = cylindrical_to_cartesian($rho, $theta, $z);
519
520 =item cylindrical_to_spherical
521
522     ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);
523
524 Notice that when C<$z> is not 0 C<$rho_s> is not equal to C<$rho_c>.
525
526 =item spherical_to_cartesian
527
528     ($x, $y, $z) = spherical_to_cartesian($rho, $theta, $phi);
529
530 =item spherical_to_cylindrical
531
532     ($rho_c, $theta, $z) = spherical_to_cylindrical($rho_s, $theta, $phi);
533
534 Notice that when C<$z> is not 0 C<$rho_c> is not equal to C<$rho_s>.
535
536 =back
537
538 =head1 GREAT CIRCLE DISTANCES AND DIRECTIONS
539
540 A great circle is section of a circle that contains the circle
541 diameter: the shortest distance between two (non-antipodal) points on
542 the spherical surface goes along the great circle connecting those two
543 points.
544
545 =head2 great_circle_distance
546
547 You can compute spherical distances, called B<great circle distances>,
548 by importing the great_circle_distance() function:
549
550   use Math::Trig 'great_circle_distance';
551
552   $distance = great_circle_distance($theta0, $phi0, $theta1, $phi1, [, $rho]);
553
554 The I<great circle distance> is the shortest distance between two
555 points on a sphere.  The distance is in C<$rho> units.  The C<$rho> is
556 optional, it defaults to 1 (the unit sphere), therefore the distance
557 defaults to radians.
558
559 If you think geographically the I<theta> are longitudes: zero at the
560 Greenwhich meridian, eastward positive, westward negative -- and the
561 I<phi> are latitudes: zero at the North Pole, northward positive,
562 southward negative.  B<NOTE>: this formula thinks in mathematics, not
563 geographically: the I<phi> zero is at the North Pole, not at the
564 Equator on the west coast of Africa (Bay of Guinea).  You need to
565 subtract your geographical coordinates from I<pi/2> (also known as 90
566 degrees).
567
568   $distance = great_circle_distance($lon0, pi/2 - $lat0,
569                                     $lon1, pi/2 - $lat1, $rho);
570
571 =head2 great_circle_direction
572
573 The direction you must follow the great circle (also known as I<bearing>)
574 can be computed by the great_circle_direction() function:
575
576   use Math::Trig 'great_circle_direction';
577
578   $direction = great_circle_direction($theta0, $phi0, $theta1, $phi1);
579
580 =head2 great_circle_bearing
581
582 Alias 'great_circle_bearing' for 'great_circle_direction' is also available.
583
584   use Math::Trig 'great_circle_bearing';
585
586   $direction = great_circle_bearing($theta0, $phi0, $theta1, $phi1);
587
588 The result of great_circle_direction is in radians, zero indicating
589 straight north, pi or -pi straight south, pi/2 straight west, and
590 -pi/2 straight east.
591
592 You can inversely compute the destination if you know the
593 starting point, direction, and distance:
594
595 =head2 great_circle_destination
596
597   use Math::Trig 'great_circle_destination';
598
599   # thetad and phid are the destination coordinates,
600   # dird is the final direction at the destination.
601
602   ($thetad, $phid, $dird) =
603     great_circle_destination($theta, $phi, $direction, $distance);
604
605 or the midpoint if you know the end points:
606
607 =head2 great_circle_midpoint
608
609   use Math::Trig 'great_circle_midpoint';
610
611   ($thetam, $phim) =
612     great_circle_midpoint($theta0, $phi0, $theta1, $phi1);
613
614 The great_circle_midpoint() is just a special case of
615
616 =head2 great_circle_waypoint
617
618   use Math::Trig 'great_circle_waypoint';
619
620   ($thetai, $phii) =
621     great_circle_waypoint($theta0, $phi0, $theta1, $phi1, $way);
622
623 Where the $way is a value from zero ($theta0, $phi0) to one ($theta1,
624 $phi1).  Note that antipodal points (where their distance is I<pi>
625 radians) do not have waypoints between them (they would have an an
626 "equator" between them), and therefore C<undef> is returned for
627 antipodal points.  If the points are the same and the distance
628 therefore zero and all waypoints therefore identical, the first point
629 (either point) is returned.
630
631 The thetas, phis, direction, and distance in the above are all in radians.
632
633 You can import all the great circle formulas by
634
635   use Math::Trig ':great_circle';
636
637 Notice that the resulting directions might be somewhat surprising if
638 you are looking at a flat worldmap: in such map projections the great
639 circles quite often do not look like the shortest routes --  but for
640 example the shortest possible routes from Europe or North America to
641 Asia do often cross the polar regions.  (The common Mercator projection
642 does B<not> show great circles as straight lines: straight lines in the
643 Mercator projection are lines of constant bearing.)
644
645 =head1 EXAMPLES
646
647 To calculate the distance between London (51.3N 0.5W) and Tokyo
648 (35.7N 139.8E) in kilometers:
649
650     use Math::Trig qw(great_circle_distance deg2rad);
651
652     # Notice the 90 - latitude: phi zero is at the North Pole.
653     sub NESW { deg2rad($_[0]), deg2rad(90 - $_[1]) }
654     my @L = NESW( -0.5, 51.3);
655     my @T = NESW(139.8, 35.7);
656     my $km = great_circle_distance(@L, @T, 6378); # About 9600 km.
657
658 The direction you would have to go from London to Tokyo (in radians,
659 straight north being zero, straight east being pi/2).
660
661     use Math::Trig qw(great_circle_direction);
662
663     my $rad = great_circle_direction(@L, @T); # About 0.547 or 0.174 pi.
664
665 The midpoint between London and Tokyo being
666
667     use Math::Trig qw(great_circle_midpoint);
668
669     my @M = great_circle_midpoint(@L, @T);
670
671 or about 68.93N 89.16E, in the frozen wastes of Siberia.
672
673 =head2 CAVEAT FOR GREAT CIRCLE FORMULAS
674
675 The answers may be off by few percentages because of the irregular
676 (slightly aspherical) form of the Earth.  The errors are at worst
677 about 0.55%, but generally below 0.3%.
678
679 =head2 Real-valued asin and acos
680
681 For small inputs asin() and acos() may return complex numbers even
682 when real numbers would be enough and correct, this happens because of
683 floating-point inaccuracies.  You can see these inaccuracies for
684 example by trying theses:
685
686   print cos(1e-6)**2+sin(1e-6)**2 - 1,"\n";
687   printf "%.20f", cos(1e-6)**2+sin(1e-6)**2,"\n";
688
689 which will print something like this
690
691   -1.11022302462516e-16
692   0.99999999999999988898
693
694 even though the expected results are of course exactly zero and one.
695 The formulas used to compute asin() and acos() are quite sensitive to
696 this, and therefore they might accidentally slip into the complex
697 plane even when they should not.  To counter this there are two
698 interfaces that are guaranteed to return a real-valued output.
699
700 =over 4
701
702 =item asin_real
703
704     use Math::Trig qw(asin_real);
705
706     $real_angle = asin_real($input_sin);
707
708 Return a real-valued arcus sine if the input is between [-1, 1],
709 B<inclusive> the endpoints.  For inputs greater than one, pi/2
710 is returned.  For inputs less than minus one, -pi/2 is returned.
711
712 =item acos_real
713
714     use Math::Trig qw(acos_real);
715
716     $real_angle = acos_real($input_cos);
717
718 Return a real-valued arcus cosine if the input is between [-1, 1],
719 B<inclusive> the endpoints.  For inputs greater than one, zero
720 is returned.  For inputs less than minus one, pi is returned.
721
722 =back
723
724 =head1 BUGS
725
726 Saying C<use Math::Trig;> exports many mathematical routines in the
727 caller environment and even overrides some (C<sin>, C<cos>).  This is
728 construed as a feature by the Authors, actually... ;-)
729
730 The code is not optimized for speed, especially because we use
731 C<Math::Complex> and thus go quite near complex numbers while doing
732 the computations even when the arguments are not. This, however,
733 cannot be completely avoided if we want things like C<asin(2)> to give
734 an answer instead of giving a fatal runtime error.
735
736 Do not attempt navigation using these formulas.
737
738 L<Math::Complex>
739
740 =head1 AUTHORS
741
742 Jarkko Hietaniemi <F<jhi!at!iki.fi>> and 
743 Raphael Manfredi <F<Raphael_Manfredi!at!pobox.com>>.
744
745 =head1 LICENSE
746
747 This library is free software; you can redistribute it and/or modify
748 it under the same terms as Perl itself. 
749
750 =cut
751
752 # eof