1Math::Trig(3pm)        Perl Programmers Reference Guide        Math::Trig(3pm)
2
3
4

NAME

6       Math::Trig - trigonometric functions
7

SYNOPSIS

9           use Math::Trig;
10
11           $x = tan(0.9);
12           $y = acos(3.7);
13           $z = asin(2.4);
14
15           $halfpi = pi/2;
16
17           $rad = deg2rad(120);
18
19           # Import constants pi2, pip2, pip4 (2*pi, pi/2, pi/4).
20           use Math::Trig ':pi';
21
22           # Import the conversions between cartesian/spherical/cylindrical.
23           use Math::Trig ':radial';
24
25               # Import the great circle formulas.
26           use Math::Trig ':great_circle';
27

DESCRIPTION

29       "Math::Trig" defines many trigonometric functions not defined by the
30       core Perl which defines only the "sin()" and "cos()".  The constant pi
31       is also defined as are a few convenience functions for angle
32       conversions, and great circle formulas for spherical movement.
33

TRIGONOMETRIC FUNCTIONS

35       The tangent
36
37       tan
38
39       The cofunctions of the sine, cosine, and tangent (cosec/csc and
40       cotan/cot are aliases)
41
42       csc, cosec, sec, sec, cot, cotan
43
44       The arcus (also known as the inverse) functions of the sine, cosine,
45       and tangent
46
47       asin, acos, atan
48
49       The principal value of the arc tangent of y/x
50
51       atan2(y, x)
52
53       The arcus cofunctions of the sine, cosine, and tangent (acosec/acsc and
54       acotan/acot are aliases).  Note that atan2(0, 0) is not well-defined.
55
56       acsc, acosec, asec, acot, acotan
57
58       The hyperbolic sine, cosine, and tangent
59
60       sinh, cosh, tanh
61
62       The cofunctions of the hyperbolic sine, cosine, and tangent
63       (cosech/csch and cotanh/coth are aliases)
64
65       csch, cosech, sech, coth, cotanh
66
67       The area (also known as the inverse) functions of the hyperbolic sine,
68       cosine, and tangent
69
70       asinh, acosh, atanh
71
72       The area cofunctions of the hyperbolic sine, cosine, and tangent
73       (acsch/acosech and acoth/acotanh are aliases)
74
75       acsch, acosech, asech, acoth, acotanh
76
77       The trigonometric constant pi and some of handy multiples of it are
78       also defined.
79
80       pi, pi2, pi4, pip2, pip4
81
82   ERRORS DUE TO DIVISION BY ZERO
83       The following functions
84
85           acoth
86           acsc
87           acsch
88           asec
89           asech
90           atanh
91           cot
92           coth
93           csc
94           csch
95           sec
96           sech
97           tan
98           tanh
99
100       cannot be computed for all arguments because that would mean dividing
101       by zero or taking logarithm of zero. These situations cause fatal
102       runtime errors looking like this
103
104           cot(0): Division by zero.
105           (Because in the definition of cot(0), the divisor sin(0) is 0)
106           Died at ...
107
108       or
109
110           atanh(-1): Logarithm of zero.
111           Died at...
112
113       For the "csc", "cot", "asec", "acsc", "acot", "csch", "coth", "asech",
114       "acsch", the argument cannot be 0 (zero).  For the "atanh", "acoth",
115       the argument cannot be 1 (one).  For the "atanh", "acoth", the argument
116       cannot be "-1" (minus one).  For the "tan", "sec", "tanh", "sech", the
117       argument cannot be pi/2 + k * pi, where k is any integer.
118
119       Note that atan2(0, 0) is not well-defined.
120
121   SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS
122       Please note that some of the trigonometric functions can break out from
123       the real axis into the complex plane. For example asin(2) has no
124       definition for plain real numbers but it has definition for complex
125       numbers.
126
127       In Perl terms this means that supplying the usual Perl numbers (also
128       known as scalars, please see perldata) as input for the trigonometric
129       functions might produce as output results that no more are simple real
130       numbers: instead they are complex numbers.
131
132       The "Math::Trig" handles this by using the "Math::Complex" package
133       which knows how to handle complex numbers, please see Math::Complex for
134       more information. In practice you need not to worry about getting
135       complex numbers as results because the "Math::Complex" takes care of
136       details like for example how to display complex numbers. For example:
137
138           print asin(2), "\n";
139
140       should produce something like this (take or leave few last decimals):
141
142           1.5707963267949-1.31695789692482i
143
144       That is, a complex number with the real part of approximately 1.571 and
145       the imaginary part of approximately "-1.317".
146

PLANE ANGLE CONVERSIONS

148       (Plane, 2-dimensional) angles may be converted with the following
149       functions.
150
151       deg2rad
152               $radians  = deg2rad($degrees);
153
154       grad2rad
155               $radians  = grad2rad($gradians);
156
157       rad2deg
158               $degrees  = rad2deg($radians);
159
160       grad2deg
161               $degrees  = grad2deg($gradians);
162
163       deg2grad
164               $gradians = deg2grad($degrees);
165
166       rad2grad
167               $gradians = rad2grad($radians);
168
169       The full circle is 2 pi radians or 360 degrees or 400 gradians.  The
170       result is by default wrapped to be inside the [0, {2pi,360,400}[
171       circle.  If you don't want this, supply a true second argument:
172
173           $zillions_of_radians  = deg2rad($zillions_of_degrees, 1);
174           $negative_degrees     = rad2deg($negative_radians, 1);
175
176       You can also do the wrapping explicitly by rad2rad(), deg2deg(), and
177       grad2grad().
178
179       rad2rad
180               $radians_wrapped_by_2pi = rad2rad($radians);
181
182       deg2deg
183               $degrees_wrapped_by_360 = deg2deg($degrees);
184
185       grad2grad
186               $gradians_wrapped_by_400 = grad2grad($gradians);
187

RADIAL COORDINATE CONVERSIONS

189       Radial coordinate systems are the spherical and the cylindrical
190       systems, explained shortly in more detail.
191
192       You can import radial coordinate conversion functions by using the
193       ":radial" tag:
194
195           use Math::Trig ':radial';
196
197           ($rho, $theta, $z)     = cartesian_to_cylindrical($x, $y, $z);
198           ($rho, $theta, $phi)   = cartesian_to_spherical($x, $y, $z);
199           ($x, $y, $z)           = cylindrical_to_cartesian($rho, $theta, $z);
200           ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);
201           ($x, $y, $z)           = spherical_to_cartesian($rho, $theta, $phi);
202           ($rho_c, $theta, $z)   = spherical_to_cylindrical($rho_s, $theta, $phi);
203
204       All angles are in radians.
205
206   COORDINATE SYSTEMS
207       Cartesian coordinates are the usual rectangular (x, y, z)-coordinates.
208
209       Spherical coordinates, (rho, theta, pi), are three-dimensional
210       coordinates which define a point in three-dimensional space.  They are
211       based on a sphere surface.  The radius of the sphere is rho, also known
212       as the radial coordinate.  The angle in the xy-plane (around the
213       z-axis) is theta, also known as the azimuthal coordinate.  The angle
214       from the z-axis is phi, also known as the polar coordinate.  The North
215       Pole is therefore 0, 0, rho, and the Gulf of Guinea (think of the
216       missing big chunk of Africa) 0, pi/2, rho.  In geographical terms phi
217       is latitude (northward positive, southward negative) and theta is
218       longitude (eastward positive, westward negative).
219
220       BEWARE: some texts define theta and phi the other way round, some texts
221       define the phi to start from the horizontal plane, some texts use r in
222       place of rho.
223
224       Cylindrical coordinates, (rho, theta, z), are three-dimensional
225       coordinates which define a point in three-dimensional space.  They are
226       based on a cylinder surface.  The radius of the cylinder is rho, also
227       known as the radial coordinate.  The angle in the xy-plane (around the
228       z-axis) is theta, also known as the azimuthal coordinate.  The third
229       coordinate is the z, pointing up from the theta-plane.
230
231   3-D ANGLE CONVERSIONS
232       Conversions to and from spherical and cylindrical coordinates are
233       available.  Please notice that the conversions are not necessarily
234       reversible because of the equalities like pi angles being equal to -pi
235       angles.
236
237       cartesian_to_cylindrical
238               ($rho, $theta, $z) = cartesian_to_cylindrical($x, $y, $z);
239
240       cartesian_to_spherical
241               ($rho, $theta, $phi) = cartesian_to_spherical($x, $y, $z);
242
243       cylindrical_to_cartesian
244               ($x, $y, $z) = cylindrical_to_cartesian($rho, $theta, $z);
245
246       cylindrical_to_spherical
247               ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);
248
249           Notice that when $z is not 0 $rho_s is not equal to $rho_c.
250
251       spherical_to_cartesian
252               ($x, $y, $z) = spherical_to_cartesian($rho, $theta, $phi);
253
254       spherical_to_cylindrical
255               ($rho_c, $theta, $z) = spherical_to_cylindrical($rho_s, $theta, $phi);
256
257           Notice that when $z is not 0 $rho_c is not equal to $rho_s.
258

GREAT CIRCLE DISTANCES AND DIRECTIONS

260       A great circle is section of a circle that contains the circle
261       diameter: the shortest distance between two (non-antipodal) points on
262       the spherical surface goes along the great circle connecting those two
263       points.
264
265   great_circle_distance
266       You can compute spherical distances, called great circle distances, by
267       importing the great_circle_distance() function:
268
269         use Math::Trig 'great_circle_distance';
270
271         $distance = great_circle_distance($theta0, $phi0, $theta1, $phi1, [, $rho]);
272
273       The great circle distance is the shortest distance between two points
274       on a sphere.  The distance is in $rho units.  The $rho is optional, it
275       defaults to 1 (the unit sphere), therefore the distance defaults to
276       radians.
277
278       If you think geographically the theta are longitudes: zero at the
279       Greenwhich meridian, eastward positive, westward negative -- and the
280       phi are latitudes: zero at the North Pole, northward positive,
281       southward negative.  NOTE: this formula thinks in mathematics, not
282       geographically: the phi zero is at the North Pole, not at the Equator
283       on the west coast of Africa (Bay of Guinea).  You need to subtract your
284       geographical coordinates from pi/2 (also known as 90 degrees).
285
286         $distance = great_circle_distance($lon0, pi/2 - $lat0,
287                                           $lon1, pi/2 - $lat1, $rho);
288
289   great_circle_direction
290       The direction you must follow the great circle (also known as bearing)
291       can be computed by the great_circle_direction() function:
292
293         use Math::Trig 'great_circle_direction';
294
295         $direction = great_circle_direction($theta0, $phi0, $theta1, $phi1);
296
297   great_circle_bearing
298       Alias 'great_circle_bearing' for 'great_circle_direction' is also
299       available.
300
301         use Math::Trig 'great_circle_bearing';
302
303         $direction = great_circle_bearing($theta0, $phi0, $theta1, $phi1);
304
305       The result of great_circle_direction is in radians, zero indicating
306       straight north, pi or -pi straight south, pi/2 straight west, and -pi/2
307       straight east.
308
309   great_circle_destination
310       You can inversely compute the destination if you know the starting
311       point, direction, and distance:
312
313         use Math::Trig 'great_circle_destination';
314
315         # $diro is the original direction,
316         # for example from great_circle_bearing().
317         # $distance is the angular distance in radians,
318         # for example from great_circle_distance().
319         # $thetad and $phid are the destination coordinates,
320         # $dird is the final direction at the destination.
321
322         ($thetad, $phid, $dird) =
323           great_circle_destination($theta, $phi, $diro, $distance);
324
325       or the midpoint if you know the end points:
326
327   great_circle_midpoint
328         use Math::Trig 'great_circle_midpoint';
329
330         ($thetam, $phim) =
331           great_circle_midpoint($theta0, $phi0, $theta1, $phi1);
332
333       The great_circle_midpoint() is just a special case of
334
335   great_circle_waypoint
336         use Math::Trig 'great_circle_waypoint';
337
338         ($thetai, $phii) =
339           great_circle_waypoint($theta0, $phi0, $theta1, $phi1, $way);
340
341       Where the $way is a value from zero ($theta0, $phi0) to one ($theta1,
342       $phi1).  Note that antipodal points (where their distance is pi
343       radians) do not have waypoints between them (they would have an an
344       "equator" between them), and therefore "undef" is returned for
345       antipodal points.  If the points are the same and the distance
346       therefore zero and all waypoints therefore identical, the first point
347       (either point) is returned.
348
349       The thetas, phis, direction, and distance in the above are all in
350       radians.
351
352       You can import all the great circle formulas by
353
354         use Math::Trig ':great_circle';
355
356       Notice that the resulting directions might be somewhat surprising if
357       you are looking at a flat worldmap: in such map projections the great
358       circles quite often do not look like the shortest routes --  but for
359       example the shortest possible routes from Europe or North America to
360       Asia do often cross the polar regions.  (The common Mercator projection
361       does not show great circles as straight lines: straight lines in the
362       Mercator projection are lines of constant bearing.)
363

EXAMPLES

365       To calculate the distance between London (51.3N 0.5W) and Tokyo (35.7N
366       139.8E) in kilometers:
367
368           use Math::Trig qw(great_circle_distance deg2rad);
369
370           # Notice the 90 - latitude: phi zero is at the North Pole.
371           sub NESW { deg2rad($_[0]), deg2rad(90 - $_[1]) }
372           my @L = NESW( -0.5, 51.3);
373           my @T = NESW(139.8, 35.7);
374           my $km = great_circle_distance(@L, @T, 6378); # About 9600 km.
375
376       The direction you would have to go from London to Tokyo (in radians,
377       straight north being zero, straight east being pi/2).
378
379           use Math::Trig qw(great_circle_direction);
380
381           my $rad = great_circle_direction(@L, @T); # About 0.547 or 0.174 pi.
382
383       The midpoint between London and Tokyo being
384
385           use Math::Trig qw(great_circle_midpoint);
386
387           my @M = great_circle_midpoint(@L, @T);
388
389       or about 69 N 89 E, in the frozen wastes of Siberia.
390
391       NOTE: you cannot get from A to B like this:
392
393          Dist = great_circle_distance(A, B)
394          Dir  = great_circle_direction(A, B)
395          C    = great_circle_destination(A, Dist, Dir)
396
397       and expect C to be B, because the bearing constantly changes when going
398       from A to B (except in some special case like the meridians or the
399       circles of latitudes) and in great_circle_destination() one gives a
400       constant bearing to follow.
401
402   CAVEAT FOR GREAT CIRCLE FORMULAS
403       The answers may be off by few percentages because of the irregular
404       (slightly aspherical) form of the Earth.  The errors are at worst about
405       0.55%, but generally below 0.3%.
406
407   Real-valued asin and acos
408       For small inputs asin() and acos() may return complex numbers even when
409       real numbers would be enough and correct, this happens because of
410       floating-point inaccuracies.  You can see these inaccuracies for
411       example by trying theses:
412
413         print cos(1e-6)**2+sin(1e-6)**2 - 1,"\n";
414         printf "%.20f", cos(1e-6)**2+sin(1e-6)**2,"\n";
415
416       which will print something like this
417
418         -1.11022302462516e-16
419         0.99999999999999988898
420
421       even though the expected results are of course exactly zero and one.
422       The formulas used to compute asin() and acos() are quite sensitive to
423       this, and therefore they might accidentally slip into the complex plane
424       even when they should not.  To counter this there are two interfaces
425       that are guaranteed to return a real-valued output.
426
427       asin_real
428               use Math::Trig qw(asin_real);
429
430               $real_angle = asin_real($input_sin);
431
432           Return a real-valued arcus sine if the input is between [-1, 1],
433           inclusive the endpoints.  For inputs greater than one, pi/2 is
434           returned.  For inputs less than minus one, -pi/2 is returned.
435
436       acos_real
437               use Math::Trig qw(acos_real);
438
439               $real_angle = acos_real($input_cos);
440
441           Return a real-valued arcus cosine if the input is between [-1, 1],
442           inclusive the endpoints.  For inputs greater than one, zero is
443           returned.  For inputs less than minus one, pi is returned.
444

BUGS

446       Saying "use Math::Trig;" exports many mathematical routines in the
447       caller environment and even overrides some ("sin", "cos").  This is
448       construed as a feature by the Authors, actually... ;-)
449
450       The code is not optimized for speed, especially because we use
451       "Math::Complex" and thus go quite near complex numbers while doing the
452       computations even when the arguments are not. This, however, cannot be
453       completely avoided if we want things like asin(2) to give an answer
454       instead of giving a fatal runtime error.
455
456       Do not attempt navigation using these formulas.
457
458       Math::Complex
459

AUTHORS

461       Jarkko Hietaniemi <jhi!at!iki.fi>, Raphael Manfredi
462       <Raphael_Manfredi!at!pobox.com>, Zefram <zefram@fysh.org>
463

LICENSE

465       This library is free software; you can redistribute it and/or modify it
466       under the same terms as Perl itself.
467
468
469
470perl v5.34.0                      2021-10-18                   Math::Trig(3pm)
Impressum