1Math::Trig(3pm) Perl Programmers Reference Guide Math::Trig(3pm)
2
6 Math::Trig - trigonometric functions
7
9 use Math::Trig;
10 $x = tan(0.9);
12 $y = acos(3.7);
13 $z = asin(2.4);
14 $halfpi = pi/2;
16 $rad = deg2rad(120);
18 # Import constants pi2, pip2, pip4 (2*pi, pi/2, pi/4).
20 use Math::Trig ':pi';
21 # Import the conversions between cartesian/spherical/cylindrical.
23 use Math::Trig ':radial';
24 # Import the great circle formulas.
26 use Math::Trig ':great_circle';
27
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
35 The tangent
36 tan
38 The cofunctions of the sine, cosine, and tangent (cosec/csc and
40 cotan/cot are aliases)
41 csc, cosec, sec, sec, cot, cotan
43 The arcus (also known as the inverse) functions of the sine, cosine,
45 and tangent
46 asin, acos, atan
48 The principal value of the arc tangent of y/x
50 atan2(y, x)
52 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 acsc, acosec, asec, acot, acotan
57 The hyperbolic sine, cosine, and tangent
59 sinh, cosh, tanh
61 The cofunctions of the hyperbolic sine, cosine, and tangent
63 (cosech/csch and cotanh/coth are aliases)
64 csch, cosech, sech, coth, cotanh
66 The area (also known as the inverse) functions of the hyperbolic sine,
68 cosine, and tangent
69 asinh, acosh, atanh
71 The area cofunctions of the hyperbolic sine, cosine, and tangent
73 (acsch/acosech and acoth/acotanh are aliases)
74 acsch, acosech, asech, acoth, acotanh
76 The trigonometric constant pi and some of handy multiples of it are
78 also defined.
79 pi, pi2, pi4, pip2, pip4
81 ERRORS DUE TO DIVISION BY ZERO
83 The following functions
84 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 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 cot(0): Division by zero.
105 (Because in the definition of cot(0), the divisor sin(0) is 0)
106 Died at ...
107 or
109 atanh(-1): Logarithm of zero.
111 Died at...
112 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 Note that atan2(0, 0) is not well-defined.
120 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 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 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 print asin(2), "\n";
139 should produce something like this (take or leave few last decimals):
141 1.5707963267949-1.31695789692482i
143 That is, a complex number with the real part of approximately 1.571 and
145 the imaginary part of approximately "-1.317".
146
148 (Plane, 2-dimensional) angles may be converted with the following
149 functions.
150 deg2rad
152 $radians = deg2rad($degrees);
153 grad2rad
155 $radians = grad2rad($gradians);
156 rad2deg
158 $degrees = rad2deg($radians);
159 grad2deg
161 $degrees = grad2deg($gradians);
162 deg2grad
164 $gradians = deg2grad($degrees);
165 rad2grad
167 $gradians = rad2grad($radians);
168 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 $zillions_of_radians = deg2rad($zillions_of_degrees, 1);
174 $negative_degrees = rad2deg($negative_radians, 1);
175 You can also do the wrapping explicitly by rad2rad(), deg2deg(), and
177 grad2grad().
178 rad2rad
180 $radians_wrapped_by_2pi = rad2rad($radians);
181 deg2deg
183 $degrees_wrapped_by_360 = deg2deg($degrees);
184 grad2grad
186 $gradians_wrapped_by_400 = grad2grad($gradians);
187
189 Radial coordinate systems are the spherical and the cylindrical
190 systems, explained shortly in more detail.
191 You can import radial coordinate conversion functions by using the
193 ":radial" tag:
194 use Math::Trig ':radial';
196 ($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 All angles are in radians.
205 COORDINATE SYSTEMS
207 Cartesian coordinates are the usual rectangular (x, y, z)-coordinates.
208 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 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 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 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 cartesian_to_cylindrical
238 ($rho, $theta, $z) = cartesian_to_cylindrical($x, $y, $z);
239 cartesian_to_spherical
241 ($rho, $theta, $phi) = cartesian_to_spherical($x, $y, $z);
242 cylindrical_to_cartesian
244 ($x, $y, $z) = cylindrical_to_cartesian($rho, $theta, $z);
245 cylindrical_to_spherical
247 ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);
248 Notice that when $z is not 0 $rho_s is not equal to $rho_c.
250 spherical_to_cartesian
252 ($x, $y, $z) = spherical_to_cartesian($rho, $theta, $phi);
253 spherical_to_cylindrical
255 ($rho_c, $theta, $z) = spherical_to_cylindrical($rho_s, $theta, $phi);
256 Notice that when $z is not 0 $rho_c is not equal to $rho_s.
258
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 great_circle_distance
266 You can compute spherical distances, called great circle distances, by
267 importing the great_circle_distance() function:
268 use Math::Trig 'great_circle_distance';
270 $distance = great_circle_distance($theta0, $phi0, $theta1, $phi1, [, $rho]);
272 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 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 $distance = great_circle_distance($lon0, pi/2 - $lat0,
287 $lon1, pi/2 - $lat1, $rho);
288 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 use Math::Trig 'great_circle_direction';
294 $direction = great_circle_direction($theta0, $phi0, $theta1, $phi1);
296 great_circle_bearing
298 Alias 'great_circle_bearing' for 'great_circle_direction' is also
299 available.
300 use Math::Trig 'great_circle_bearing';
302 $direction = great_circle_bearing($theta0, $phi0, $theta1, $phi1);
304 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 great_circle_destination
310 You can inversely compute the destination if you know the starting
311 point, direction, and distance:
312 use Math::Trig 'great_circle_destination';
314 # $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 ($thetad, $phid, $dird) =
323 great_circle_destination($theta, $phi, $diro, $distance);
324 or the midpoint if you know the end points:
326 great_circle_midpoint
328 use Math::Trig 'great_circle_midpoint';
329 ($thetam, $phim) =
331 great_circle_midpoint($theta0, $phi0, $theta1, $phi1);
332 The great_circle_midpoint() is just a special case of
334 great_circle_waypoint
336 use Math::Trig 'great_circle_waypoint';
337 ($thetai, $phii) =
339 great_circle_waypoint($theta0, $phi0, $theta1, $phi1, $way);
340 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 The thetas, phis, direction, and distance in the above are all in
350 radians.
351 You can import all the great circle formulas by
353 use Math::Trig ':great_circle';
355 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
365 To calculate the distance between London (51.3N 0.5W) and Tokyo (35.7N
366 139.8E) in kilometers:
367 use Math::Trig qw(great_circle_distance deg2rad);
369 # 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 The direction you would have to go from London to Tokyo (in radians,
377 straight north being zero, straight east being pi/2).
378 use Math::Trig qw(great_circle_direction);
380 my $rad = great_circle_direction(@L, @T); # About 0.547 or 0.174 pi.
382 The midpoint between London and Tokyo being
384 use Math::Trig qw(great_circle_midpoint);
386 my @M = great_circle_midpoint(@L, @T);
388 or about 69 N 89 E, in the frozen wastes of Siberia.
390 NOTE: you cannot get from A to B like this:
392 Dist = great_circle_distance(A, B)
394 Dir = great_circle_direction(A, B)
395 C = great_circle_destination(A, Dist, Dir)
396 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 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 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 print cos(1e-6)**2+sin(1e-6)**2 - 1,"\n";
414 printf "%.20f", cos(1e-6)**2+sin(1e-6)**2,"\n";
415 which will print something like this
417 -1.11022302462516e-16
419 0.99999999999999988898
420 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 asin_real
428 use Math::Trig qw(asin_real);
429 $real_angle = asin_real($input_sin);
431 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 acos_real
437 use Math::Trig qw(acos_real);
438 $real_angle = acos_real($input_cos);
440 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
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 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 Do not attempt navigation using these formulas.
457 Math::Complex
459
461 Jarkko Hietaniemi <jhi!at!iki.fi>, Raphael Manfredi
462 <Raphael_Manfredi!at!pobox.com>, Zefram <zefram@fysh.org>
463
465 This library is free software; you can redistribute it and/or modify it
466 under the same terms as Perl itself.
467perl v5.34.0 2021-10-18 Math::Trig(3pm)