1Math::Trig(3pm) Perl Programmers Reference Guide Math::Trig(3pm)
2
3
4
6 Math::Trig - trigonometric functions
7
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, pi4, pip2, pip4 (2*pi, 4*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
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
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
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
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, 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
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
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 Returns the great circle distance between two points on a sphere.
267
268 $distance = great_circle_distance($theta0, $phi0, $theta1, $phi1, [, $rho]);
269
270 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
274 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
280 $distance = great_circle_distance($lon0, pi/2 - $lat0,
281 $lon1, pi/2 - $lat1, $rho);
282
283 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
287 use Math::Trig 'great_circle_direction';
288
289 $direction = great_circle_direction($theta0, $phi0, $theta1, $phi1);
290
291 great_circle_bearing
292 Alias 'great_circle_bearing' for 'great_circle_direction' is also
293 available.
294
295 use Math::Trig 'great_circle_bearing';
296
297 $direction = great_circle_bearing($theta0, $phi0, $theta1, $phi1);
298
299 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
303 great_circle_destination
304 You can inversely compute the destination if you know the starting
305 point, direction, and distance:
306
307 use Math::Trig 'great_circle_destination';
308
309 # $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
316 ($thetad, $phid, $dird) =
317 great_circle_destination($theta, $phi, $diro, $distance);
318
319 or the midpoint if you know the end points:
320
321 great_circle_midpoint
322 use Math::Trig 'great_circle_midpoint';
323
324 ($thetam, $phim) =
325 great_circle_midpoint($theta0, $phi0, $theta1, $phi1);
326
327 The great_circle_midpoint() is just a special case of
328
329 great_circle_waypoint
330 use Math::Trig 'great_circle_waypoint';
331
332 ($thetai, $phii) =
333 great_circle_waypoint($theta0, $phi0, $theta1, $phi1, $way);
334
335 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
343 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
348 The thetas, phis, direction, and distance in the above are all in
349 radians.
350
351 You can import all the great circle formulas by
352
353 use Math::Trig ':great_circle';
354
355 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
367 use Math::Trig qw(great_circle_distance deg2rad);
368
369 # 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
375 The direction you would have to go from London to Tokyo (in radians,
376 straight north being zero, straight east being pi/2).
377
378 use Math::Trig qw(great_circle_direction);
379
380 my $rad = great_circle_direction(@L, @T); # About 0.547 or 0.174 pi.
381
382 The midpoint between London and Tokyo being
383
384 use Math::Trig qw(great_circle_midpoint rad2deg);
385
386 my @M = great_circle_midpoint(@L, @T);
387 sub SWNE { rad2deg( $_[0] ), 90 - rad2deg( $_[1] ) }
388 my @lonlat = SWNE(@M);
389
390 or about 69 N 89 E, on the Putorana Plateau of Siberia.
391
392 NOTE: you cannot get from A to B like this:
393
394 Dist = great_circle_distance(A, B)
395 Dir = great_circle_direction(A, B)
396 C = great_circle_destination(A, Dist, Dir)
397
398 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
403 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
408 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
414 print cos(1e-6)**2+sin(1e-6)**2 - 1,"\n";
415 printf "%.20f", cos(1e-6)**2+sin(1e-6)**2,"\n";
416
417 which will print something like this
418
419 -1.11022302462516e-16
420 0.99999999999999988898
421
422 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
428 asin_real
429 use Math::Trig qw(asin_real);
430
431 $real_angle = asin_real($input_sin);
432
433 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
437 acos_real
438 use Math::Trig qw(acos_real);
439
440 $real_angle = acos_real($input_cos);
441
442 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
451 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
457 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.
469
470
471
472perl v5.38.2 2023-11-30 Math::Trig(3pm)