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, pi4, pip2, pip4 (2*pi, 4*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 is
31 also defined as are a few convenience functions for angle conversions,
32 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, phi), 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 rho, 0, 0, and the Gulf of Guinea (think of the
216 missing big chunk of Africa) rho, 0, pi/2. 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 Returns the great circle distance between two points on a sphere.
267 $distance = great_circle_distance($theta0, $phi0, $theta1, $phi1, [, $rho]);
269 Where ($theta0, $phi0) and ($theta1, $phi1) are the spherical
271 coordinates of the two points, respectively. The distance is in $rho
272 units. The $rho is optional. It defaults to 1 (the unit sphere).
273 If you are using geographic coordinates, latitude and longitude, you
275 need to adjust for the fact that latitude is zero at the equator
276 increasing towards the north and decreasing towards the south. Assuming
277 ($lat0, $lon0) and ($lat1, $lon1) are the geographic coordinates in
278 radians of the two points, the distance can be computed with
279 $distance = great_circle_distance($lon0, pi/2 - $lat0,
281 $lon1, pi/2 - $lat1, $rho);
282 great_circle_direction
284 The direction you must follow the great circle (also known as bearing)
285 can be computed by the great_circle_direction() function:
286 use Math::Trig 'great_circle_direction';
288 $direction = great_circle_direction($theta0, $phi0, $theta1, $phi1);
290 great_circle_bearing
292 Alias 'great_circle_bearing' for 'great_circle_direction' is also
293 available.
294 use Math::Trig 'great_circle_bearing';
296 $direction = great_circle_bearing($theta0, $phi0, $theta1, $phi1);
298 The result of great_circle_direction is in radians, zero indicating
300 straight north, pi or -pi straight south, pi/2 straight west, and -pi/2
301 straight east.
302 great_circle_destination
304 You can inversely compute the destination if you know the starting
305 point, direction, and distance:
306 use Math::Trig 'great_circle_destination';
308 # $diro is the original direction,
310 # for example from great_circle_bearing().
311 # $distance is the angular distance in radians,
312 # for example from great_circle_distance().
313 # $thetad and $phid are the destination coordinates,
314 # $dird is the final direction at the destination.
315 ($thetad, $phid, $dird) =
317 great_circle_destination($theta, $phi, $diro, $distance);
318 or the midpoint if you know the end points:
320 great_circle_midpoint
322 use Math::Trig 'great_circle_midpoint';
323 ($thetam, $phim) =
325 great_circle_midpoint($theta0, $phi0, $theta1, $phi1);
326 The great_circle_midpoint() is just a special case of
328 great_circle_waypoint
330 use Math::Trig 'great_circle_waypoint';
331 ($thetai, $phii) =
333 great_circle_waypoint($theta0, $phi0, $theta1, $phi1, $way);
334 Where $way indicates the position of the waypoint along the great
336 circle arc through the starting point ($theta0, $phi0) and the end
337 point ($theta1, $phi1) relative to the distance from the starting point
338 to the end point. So $way = 0 gives the starting point, $way = 1 gives
339 the end point, $way < 0 gives a point "behind" the starting point, and
340 $way > 1 gives a point beyond the end point. $way defaults to 0.5 if
341 not given.
342 Note that antipodal points (where their distance is pi radians) do not
344 have unique waypoints between them, and therefore "undef" is returned
345 in such cases. If the points are the same, so the distance between
346 them is zero, all waypoints are identical to the starting/end point.
347 The thetas, phis, direction, and distance in the above are all in
349 radians.
350 You can import all the great circle formulas by
352 use Math::Trig ':great_circle';
354 Notice that the resulting directions might be somewhat surprising if
356 you are looking at a flat worldmap: in such map projections the great
357 circles quite often do not look like the shortest routes -- but for
358 example the shortest possible routes from Europe or North America to
359 Asia do often cross the polar regions. (The common Mercator projection
360 does not show great circles as straight lines: straight lines in the
361 Mercator projection are lines of constant bearing.)
362
364 To calculate the distance between London (51.3N 0.5W) and Tokyo (35.7N
365 139.8E) in kilometers:
366 use Math::Trig qw(great_circle_distance deg2rad);
368 # Notice the 90 - latitude: phi zero is at the North Pole.
370 sub NESW { deg2rad($_[0]), deg2rad(90 - $_[1]) }
371 my @L = NESW( -0.5, 51.3);
372 my @T = NESW(139.8, 35.7);
373 my $km = great_circle_distance(@L, @T, 6378); # About 9600 km.
374 The direction you would have to go from London to Tokyo (in radians,
376 straight north being zero, straight east being pi/2).
377 use Math::Trig qw(great_circle_direction);
379 my $rad = great_circle_direction(@L, @T); # About 0.547 or 0.174 pi.
381 The midpoint between London and Tokyo being
383 use Math::Trig qw(great_circle_midpoint rad2deg);
385 my @M = great_circle_midpoint(@L, @T);
387 sub SWNE { rad2deg( $_[0] ), 90 - rad2deg( $_[1] ) }
388 my @lonlat = SWNE(@M);
389 or about 69 N 89 E, on the Putorana Plateau of Siberia.
391 NOTE: you cannot get from A to B like this:
393 Dist = great_circle_distance(A, B)
395 Dir = great_circle_direction(A, B)
396 C = great_circle_destination(A, Dist, Dir)
397 and expect C to be B, because the bearing constantly changes when going
399 from A to B (except in some special case like the meridians or the
400 circles of latitudes) and in great_circle_destination() one gives a
401 constant bearing to follow.
402 CAVEAT FOR GREAT CIRCLE FORMULAS
404 The answers may be off by few percentages because of the irregular
405 (slightly aspherical) form of the Earth. The errors are at worst about
406 0.55%, but generally below 0.3%.
407 Real-valued asin and acos
409 For small inputs asin() and acos() may return complex numbers even when
410 real numbers would be enough and correct, this happens because of
411 floating-point inaccuracies. You can see these inaccuracies for
412 example by trying theses:
413 print cos(1e-6)**2+sin(1e-6)**2 - 1,"\n";
415 printf "%.20f", cos(1e-6)**2+sin(1e-6)**2,"\n";
416 which will print something like this
418 -1.11022302462516e-16
420 0.99999999999999988898
421 even though the expected results are of course exactly zero and one.
423 The formulas used to compute asin() and acos() are quite sensitive to
424 this, and therefore they might accidentally slip into the complex plane
425 even when they should not. To counter this there are two interfaces
426 that are guaranteed to return a real-valued output.
427 asin_real
429 use Math::Trig qw(asin_real);
430 $real_angle = asin_real($input_sin);
432 Return a real-valued arcus sine if the input is between [-1, 1],
434 inclusive the endpoints. For inputs greater than one, pi/2 is
435 returned. For inputs less than minus one, -pi/2 is returned.
436 acos_real
438 use Math::Trig qw(acos_real);
439 $real_angle = acos_real($input_cos);
441 Return a real-valued arcus cosine if the input is between [-1, 1],
443 inclusive the endpoints. For inputs greater than one, zero is
444 returned. For inputs less than minus one, pi is returned.
445
447 Saying "use Math::Trig;" exports many mathematical routines in the
448 caller environment and even overrides some ("sin", "cos"). This is
449 construed as a feature by the Authors, actually... ;-)
450 The code is not optimized for speed, especially because we use
452 "Math::Complex" and thus go quite near complex numbers while doing the
453 computations even when the arguments are not. This, however, cannot be
454 completely avoided if we want things like asin(2) to give an answer
455 instead of giving a fatal runtime error.
456 Do not attempt navigation using these formulas.
458
460 Math::Complex
461
463 Jarkko Hietaniemi <jhi!at!iki.fi>, Raphael Manfredi
464 <Raphael_Manfredi!at!pobox.com>, Zefram <zefram@fysh.org>
465
467 This library is free software; you can redistribute it and/or modify it
468 under the same terms as Perl itself.
469perl v5.38.2 2023-11-30 Math::Trig(3pm)