{
    "content": [
        {
            "type": "text",
            "text": "# Math::Trig (perldoc)\n\n**Summary:** Math::Trig - trigonometric functions\n\n**Synopsis:** use Math::Trig;\n$x = tan(0.9);\n$y = acos(3.7);\n$z = asin(2.4);\n$halfpi = pi/2;\n$rad = deg2rad(120);\n# Import constants pi2, pip2, pip4 (2*pi, pi/2, pi/4).\nuse Math::Trig ':pi';\n# Import the conversions between cartesian/spherical/cylindrical.\nuse Math::Trig ':radial';\n# Import the great circle formulas.\nuse Math::Trig ':greatcircle';\n\n## Examples\n\n- `To calculate the distance between London (51.3N 0.5W) and Tokyo (35.7N 139.8E) in kilometers:`\n- `use Math::Trig qw(greatcircledistance deg2rad);`\n- `# Notice the 90 - latitude: phi zero is at the North Pole.`\n- `sub NESW { deg2rad($[0]), deg2rad(90 - $[1]) }`\n- `my @L = NESW( -0.5, 51.3);`\n- `my @T = NESW(139.8, 35.7);`\n- `my $km = greatcircledistance(@L, @T, 6378); # About 9600 km.`\n- `The direction you would have to go from London to Tokyo (in radians, straight north being zero,`\n- `straight east being pi/2).`\n- `use Math::Trig qw(greatcircledirection);`\n- `my $rad = greatcircledirection(@L, @T); # About 0.547 or 0.174 pi.`\n- `The midpoint between London and Tokyo being`\n- `use Math::Trig qw(greatcirclemidpoint);`\n- `my @M = greatcirclemidpoint(@L, @T);`\n- `or about 69 N 89 E, in the frozen wastes of Siberia.`\n- `NOTE: you cannot get from A to B like this:`\n- `Dist = greatcircledistance(A, B)`\n- `Dir  = greatcircledirection(A, B)`\n- `C    = greatcircledestination(A, Dist, Dir)`\n- `and expect C to be B, because the bearing constantly changes when going from A to B (except in`\n- `some special case like the meridians or the circles of latitudes) and in`\n- `CAVEAT FOR GREAT CIRCLE FORMULAS`\n- `The answers may be off by few percentages because of the irregular (slightly aspherical) form of`\n- `the Earth. The errors are at worst about 0.55%, but generally below 0.3%.`\n- `For small inputs asin() and acos() may return complex numbers even when real numbers would be`\n- `enough and correct, this happens because of floating-point inaccuracies. You can see these`\n- `inaccuracies for example by trying theses:`\n- `print cos(1e-6)2+sin(1e-6)2 - 1,\"\\n\";`\n- `printf \"%.20f\", cos(1e-6)2+sin(1e-6)2,\"\\n\";`\n- `which will print something like this`\n- `-1.11022302462516e-16`\n- `0.99999999999999988898`\n- `even though the expected results are of course exactly zero and one. The formulas used to`\n- `compute asin() and acos() are quite sensitive to this, and therefore they might accidentally`\n- `slip into the complex plane even when they should not. To counter this there are two interfaces`\n- `that are guaranteed to return a real-valued output.`\n- `asinreal`\n- `use Math::Trig qw(asinreal);`\n- `$realangle = asinreal($inputsin);`\n- `Return a real-valued arcus sine if the input is between [-1, 1], inclusive the endpoints.`\n- `For inputs greater than one, pi/2 is returned. For inputs less than minus one, -pi/2 is`\n- `returned.`\n- `acosreal`\n- `use Math::Trig qw(acosreal);`\n- `$realangle = acosreal($inputcos);`\n- `Return a real-valued arcus cosine if the input is between [-1, 1], inclusive the endpoints.`\n- `For inputs greater than one, zero is returned. For inputs less than minus one, pi is`\n- `returned.`\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (19 lines)\n- **DESCRIPTION** (4 lines)\n- **ANGLES** (3 lines)\n- **TRIGONOMETRIC FUNCTIONS** (14 lines) — 1 subsections\n  - atan2 (87 lines)\n- **PLANE ANGLE CONVERSIONS** (38 lines)\n- **RADIAL COORDINATE CONVERSIONS** (64 lines)\n- **GREAT CIRCLE DISTANCES AND DIRECTIONS** (6 lines) — 2 subsections\n  - great_circle_distance (20 lines)\n  - great_circle_direction (64 lines)\n- **EXAMPLES** (33 lines) — 2 subsections\n  - great_circle_destination (4 lines)\n  - Real-valued asin and acos (35 lines)\n- **BUGS** (10 lines)\n- **SEE ALSO** (2 lines)\n- **AUTHORS** (3 lines)\n- **LICENSE** (3 lines)\n\n## Full Content\n\n### NAME\n\nMath::Trig - trigonometric functions\n\n### SYNOPSIS\n\nuse Math::Trig;\n\n$x = tan(0.9);\n$y = acos(3.7);\n$z = asin(2.4);\n\n$halfpi = pi/2;\n\n$rad = deg2rad(120);\n\n# Import constants pi2, pip2, pip4 (2*pi, pi/2, pi/4).\nuse Math::Trig ':pi';\n\n# Import the conversions between cartesian/spherical/cylindrical.\nuse Math::Trig ':radial';\n\n# Import the great circle formulas.\nuse Math::Trig ':greatcircle';\n\n### DESCRIPTION\n\n\"Math::Trig\" defines many trigonometric functions not defined by the core Perl which defines\nonly the \"sin()\" and \"cos()\". The constant pi is also defined as are a few convenience functions\nfor angle conversions, and *great circle formulas* for spherical movement.\n\n### ANGLES\n\nAll angles are defined in radians, except where otherwise specified (for example in the deg/rad\nconversion functions).\n\n### TRIGONOMETRIC FUNCTIONS\n\nThe tangent\n\ntan\n\nThe cofunctions of the sine, cosine, and tangent (cosec/csc and cotan/cot are aliases)\n\ncsc, cosec, sec, sec, cot, cotan\n\nThe arcus (also known as the inverse) functions of the sine, cosine, and tangent\n\nasin, acos, atan\n\nThe principal value of the arc tangent of y/x\n\n#### atan2\n\nThe arcus cofunctions of the sine, cosine, and tangent (acosec/acsc and acotan/acot are\naliases). Note that atan2(0, 0) is not well-defined.\n\nacsc, acosec, asec, acot, acotan\n\nThe hyperbolic sine, cosine, and tangent\n\nsinh, cosh, tanh\n\nThe cofunctions of the hyperbolic sine, cosine, and tangent (cosech/csch and cotanh/coth are\naliases)\n\ncsch, cosech, sech, coth, cotanh\n\nThe area (also known as the inverse) functions of the hyperbolic sine, cosine, and tangent\n\nasinh, acosh, atanh\n\nThe area cofunctions of the hyperbolic sine, cosine, and tangent (acsch/acosech and\nacoth/acotanh are aliases)\n\nacsch, acosech, asech, acoth, acotanh\n\nThe trigonometric constant pi and some of handy multiples of it are also defined.\n\npi, pi2, pi4, pip2, pip4\n\nERRORS DUE TO DIVISION BY ZERO\nThe following functions\n\nacoth\nacsc\nacsch\nasec\nasech\natanh\ncot\ncoth\ncsc\ncsch\nsec\nsech\ntan\ntanh\n\ncannot be computed for all arguments because that would mean dividing by zero or taking\nlogarithm of zero. These situations cause fatal runtime errors looking like this\n\ncot(0): Division by zero.\n(Because in the definition of cot(0), the divisor sin(0) is 0)\nDied at ...\n\nor\n\natanh(-1): Logarithm of zero.\nDied at...\n\nFor the \"csc\", \"cot\", \"asec\", \"acsc\", \"acot\", \"csch\", \"coth\", \"asech\", \"acsch\", the argument\ncannot be 0 (zero). For the \"atanh\", \"acoth\", the argument cannot be 1 (one). For the \"atanh\",\n\"acoth\", the argument cannot be -1 (minus one). For the \"tan\", \"sec\", \"tanh\", \"sech\", the\nargument cannot be *pi/2 + k * pi*, where *k* is any integer.\n\nNote that atan2(0, 0) is not well-defined.\n\nSIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS\nPlease note that some of the trigonometric functions can break out from the real axis into the\ncomplex plane. For example asin(2) has no definition for plain real numbers but it has\ndefinition for complex numbers.\n\nIn Perl terms this means that supplying the usual Perl numbers (also known as scalars, please\nsee perldata) as input for the trigonometric functions might produce as output results that no\nmore are simple real numbers: instead they are complex numbers.\n\nThe \"Math::Trig\" handles this by using the \"Math::Complex\" package which knows how to handle\ncomplex numbers, please see Math::Complex for more information. In practice you need not to\nworry about getting complex numbers as results because the \"Math::Complex\" takes care of details\nlike for example how to display complex numbers. For example:\n\nprint asin(2), \"\\n\";\n\nshould produce something like this (take or leave few last decimals):\n\n1.5707963267949-1.31695789692482i\n\nThat is, a complex number with the real part of approximately 1.571 and the imaginary part of\napproximately -1.317.\n\n### PLANE ANGLE CONVERSIONS\n\n(Plane, 2-dimensional) angles may be converted with the following functions.\n\ndeg2rad\n$radians  = deg2rad($degrees);\n\ngrad2rad\n$radians  = grad2rad($gradians);\n\nrad2deg\n$degrees  = rad2deg($radians);\n\ngrad2deg\n$degrees  = grad2deg($gradians);\n\ndeg2grad\n$gradians = deg2grad($degrees);\n\nrad2grad\n$gradians = rad2grad($radians);\n\nThe full circle is 2 *pi* radians or *360* degrees or *400* gradians. The result is by default\nwrapped to be inside the [0, {2pi,360,400}[ circle. If you don't want this, supply a true second\nargument:\n\n$zillionsofradians  = deg2rad($zillionsofdegrees, 1);\n$negativedegrees     = rad2deg($negativeradians, 1);\n\nYou can also do the wrapping explicitly by rad2rad(), deg2deg(), and grad2grad().\n\nrad2rad\n$radianswrappedby2pi = rad2rad($radians);\n\ndeg2deg\n$degreeswrappedby360 = deg2deg($degrees);\n\ngrad2grad\n$gradianswrappedby400 = grad2grad($gradians);\n\n### RADIAL COORDINATE CONVERSIONS\n\nRadial coordinate systems are the spherical and the cylindrical systems, explained shortly in\nmore detail.\n\nYou can import radial coordinate conversion functions by using the \":radial\" tag:\n\nuse Math::Trig ':radial';\n\n($rho, $theta, $z)     = cartesiantocylindrical($x, $y, $z);\n($rho, $theta, $phi)   = cartesiantospherical($x, $y, $z);\n($x, $y, $z)           = cylindricaltocartesian($rho, $theta, $z);\n($rhos, $theta, $phi) = cylindricaltospherical($rhoc, $theta, $z);\n($x, $y, $z)           = sphericaltocartesian($rho, $theta, $phi);\n($rhoc, $theta, $z)   = sphericaltocylindrical($rhos, $theta, $phi);\n\nAll angles are in radians.\n\nCOORDINATE SYSTEMS\nCartesian coordinates are the usual rectangular *(x, y, z)*-coordinates.\n\nSpherical coordinates, *(rho, theta, pi)*, are three-dimensional coordinates which define a\npoint in three-dimensional space. They are based on a sphere surface. The radius of the sphere\nis rho, also known as the *radial* coordinate. The angle in the *xy*-plane (around the *z*-axis)\nis theta, also known as the *azimuthal* coordinate. The angle from the *z*-axis is phi, also\nknown as the *polar* coordinate. The North Pole is therefore *0, 0, rho*, and the Gulf of Guinea\n(think of the missing big chunk of Africa) *0, pi/2, rho*. In geographical terms *phi* is\nlatitude (northward positive, southward negative) and *theta* is longitude (eastward positive,\nwestward negative).\n\nBEWARE: some texts define *theta* and *phi* the other way round, some texts define the *phi* to\nstart from the horizontal plane, some texts use *r* in place of *rho*.\n\nCylindrical coordinates, *(rho, theta, z)*, are three-dimensional coordinates which define a\npoint in three-dimensional space. They are based on a cylinder surface. The radius of the\ncylinder is rho, also known as the *radial* coordinate. The angle in the *xy*-plane (around the\n*z*-axis) is theta, also known as the *azimuthal* coordinate. The third coordinate is the *z*,\npointing up from the theta-plane.\n\n3-D ANGLE CONVERSIONS\nConversions to and from spherical and cylindrical coordinates are available. Please notice that\nthe conversions are not necessarily reversible because of the equalities like *pi* angles being\nequal to *-pi* angles.\n\ncartesiantocylindrical\n($rho, $theta, $z) = cartesiantocylindrical($x, $y, $z);\n\ncartesiantospherical\n($rho, $theta, $phi) = cartesiantospherical($x, $y, $z);\n\ncylindricaltocartesian\n($x, $y, $z) = cylindricaltocartesian($rho, $theta, $z);\n\ncylindricaltospherical\n($rhos, $theta, $phi) = cylindricaltospherical($rhoc, $theta, $z);\n\nNotice that when $z is not 0 $rhos is not equal to $rhoc.\n\nsphericaltocartesian\n($x, $y, $z) = sphericaltocartesian($rho, $theta, $phi);\n\nsphericaltocylindrical\n($rhoc, $theta, $z) = sphericaltocylindrical($rhos, $theta, $phi);\n\nNotice that when $z is not 0 $rhoc is not equal to $rhos.\n\n### GREAT CIRCLE DISTANCES AND DIRECTIONS\n\nA great circle is section of a circle that contains the circle diameter: the shortest distance\nbetween two (non-antipodal) points on the spherical surface goes along the great circle\nconnecting those two points.\n\ngreatcircledistance\nYou can compute spherical distances, called great circle distances, by importing the\n\n#### great_circle_distance\n\nuse Math::Trig 'greatcircledistance';\n\n$distance = greatcircledistance($theta0, $phi0, $theta1, $phi1, [, $rho]);\n\nThe *great circle distance* is the shortest distance between two points on a sphere. The\ndistance is in $rho units. The $rho is optional, it defaults to 1 (the unit sphere), therefore\nthe distance defaults to radians.\n\nIf you think geographically the *theta* are longitudes: zero at the Greenwhich meridian,\neastward positive, westward negative -- and the *phi* are latitudes: zero at the North Pole,\nnorthward positive, southward negative. NOTE: this formula thinks in mathematics, not\ngeographically: the *phi* zero is at the North Pole, not at the Equator on the west coast of\nAfrica (Bay of Guinea). You need to subtract your geographical coordinates from *pi/2* (also\nknown as 90 degrees).\n\n$distance = greatcircledistance($lon0, pi/2 - $lat0,\n$lon1, pi/2 - $lat1, $rho);\n\ngreatcircledirection\nThe direction you must follow the great circle (also known as *bearing*) can be computed by the\n\n#### great_circle_direction\n\nuse Math::Trig 'greatcircledirection';\n\n$direction = greatcircledirection($theta0, $phi0, $theta1, $phi1);\n\ngreatcirclebearing\nAlias 'greatcirclebearing' for 'greatcircledirection' is also available.\n\nuse Math::Trig 'greatcirclebearing';\n\n$direction = greatcirclebearing($theta0, $phi0, $theta1, $phi1);\n\nThe result of greatcircledirection is in radians, zero indicating straight north, pi or -pi\nstraight south, pi/2 straight west, and -pi/2 straight east.\n\ngreatcircledestination\nYou can inversely compute the destination if you know the starting point, direction, and\ndistance:\n\nuse Math::Trig 'greatcircledestination';\n\n# $diro is the original direction,\n# for example from greatcirclebearing().\n# $distance is the angular distance in radians,\n# for example from greatcircledistance().\n# $thetad and $phid are the destination coordinates,\n# $dird is the final direction at the destination.\n\n($thetad, $phid, $dird) =\ngreatcircledestination($theta, $phi, $diro, $distance);\n\nor the midpoint if you know the end points:\n\ngreatcirclemidpoint\nuse Math::Trig 'greatcirclemidpoint';\n\n($thetam, $phim) =\ngreatcirclemidpoint($theta0, $phi0, $theta1, $phi1);\n\nThe greatcirclemidpoint() is just a special case (with $way = 0.5) of\n\ngreatcirclewaypoint\nuse Math::Trig 'greatcirclewaypoint';\n\n($thetai, $phii) =\ngreatcirclewaypoint($theta0, $phi0, $theta1, $phi1, $way);\n\nWhere the $way is a value from zero ($theta0, $phi0) to one ($theta1, $phi1). Note that\nantipodal points (where their distance is *pi* radians) do not have waypoints between them (they\nwould have an an \"equator\" between them), and therefore \"undef\" is returned for antipodal\npoints. If the points are the same and the distance therefore zero and all waypoints therefore\nidentical, the first point (either point) is returned.\n\nThe thetas, phis, direction, and distance in the above are all in radians.\n\nYou can import all the great circle formulas by\n\nuse Math::Trig ':greatcircle';\n\nNotice that the resulting directions might be somewhat surprising if you are looking at a flat\nworldmap: in such map projections the great circles quite often do not look like the shortest\nroutes -- but for example the shortest possible routes from Europe or North America to Asia do\noften cross the polar regions. (The common Mercator projection does not show great circles as\nstraight lines: straight lines in the Mercator projection are lines of constant bearing.)\n\n### EXAMPLES\n\nTo calculate the distance between London (51.3N 0.5W) and Tokyo (35.7N 139.8E) in kilometers:\n\nuse Math::Trig qw(greatcircledistance deg2rad);\n\n# Notice the 90 - latitude: phi zero is at the North Pole.\nsub NESW { deg2rad($[0]), deg2rad(90 - $[1]) }\nmy @L = NESW( -0.5, 51.3);\nmy @T = NESW(139.8, 35.7);\nmy $km = greatcircledistance(@L, @T, 6378); # About 9600 km.\n\nThe direction you would have to go from London to Tokyo (in radians, straight north being zero,\nstraight east being pi/2).\n\nuse Math::Trig qw(greatcircledirection);\n\nmy $rad = greatcircledirection(@L, @T); # About 0.547 or 0.174 pi.\n\nThe midpoint between London and Tokyo being\n\nuse Math::Trig qw(greatcirclemidpoint);\n\nmy @M = greatcirclemidpoint(@L, @T);\n\nor about 69 N 89 E, in the frozen wastes of Siberia.\n\nNOTE: you cannot get from A to B like this:\n\nDist = greatcircledistance(A, B)\nDir  = greatcircledirection(A, B)\nC    = greatcircledestination(A, Dist, Dir)\n\nand expect C to be B, because the bearing constantly changes when going from A to B (except in\nsome special case like the meridians or the circles of latitudes) and in\n\n#### great_circle_destination\n\nCAVEAT FOR GREAT CIRCLE FORMULAS\nThe answers may be off by few percentages because of the irregular (slightly aspherical) form of\nthe Earth. The errors are at worst about 0.55%, but generally below 0.3%.\n\n#### Real-valued asin and acos\n\nFor small inputs asin() and acos() may return complex numbers even when real numbers would be\nenough and correct, this happens because of floating-point inaccuracies. You can see these\ninaccuracies for example by trying theses:\n\nprint cos(1e-6)2+sin(1e-6)2 - 1,\"\\n\";\nprintf \"%.20f\", cos(1e-6)2+sin(1e-6)2,\"\\n\";\n\nwhich will print something like this\n\n-1.11022302462516e-16\n0.99999999999999988898\n\neven though the expected results are of course exactly zero and one. The formulas used to\ncompute asin() and acos() are quite sensitive to this, and therefore they might accidentally\nslip into the complex plane even when they should not. To counter this there are two interfaces\nthat are guaranteed to return a real-valued output.\n\nasinreal\nuse Math::Trig qw(asinreal);\n\n$realangle = asinreal($inputsin);\n\nReturn a real-valued arcus sine if the input is between [-1, 1], inclusive the endpoints.\nFor inputs greater than one, pi/2 is returned. For inputs less than minus one, -pi/2 is\nreturned.\n\nacosreal\nuse Math::Trig qw(acosreal);\n\n$realangle = acosreal($inputcos);\n\nReturn a real-valued arcus cosine if the input is between [-1, 1], inclusive the endpoints.\nFor inputs greater than one, zero is returned. For inputs less than minus one, pi is\nreturned.\n\n### BUGS\n\nSaying \"use Math::Trig;\" exports many mathematical routines in the caller environment and even\noverrides some (\"sin\", \"cos\"). This is construed as a feature by the Authors, actually... ;-)\n\nThe code is not optimized for speed, especially because we use \"Math::Complex\" and thus go quite\nnear complex numbers while doing the computations even when the arguments are not. This,\nhowever, cannot be completely avoided if we want things like asin(2) to give an answer instead\nof giving a fatal runtime error.\n\nDo not attempt navigation using these formulas.\n\n### SEE ALSO\n\nMath::Complex\n\n### AUTHORS\n\nJarkko Hietaniemi <jhi!at!iki.fi>, Raphael Manfredi <RaphaelManfredi!at!pobox.com>, Zefram\n<zefram@fysh.org>\n\n### LICENSE\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\n"
        }
    ],
    "structuredContent": {
        "command": "Math::Trig",
        "section": "",
        "mode": "perldoc",
        "summary": "Math::Trig - trigonometric functions",
        "synopsis": "use Math::Trig;\n$x = tan(0.9);\n$y = acos(3.7);\n$z = asin(2.4);\n$halfpi = pi/2;\n$rad = deg2rad(120);\n# Import constants pi2, pip2, pip4 (2*pi, pi/2, pi/4).\nuse Math::Trig ':pi';\n# Import the conversions between cartesian/spherical/cylindrical.\nuse Math::Trig ':radial';\n# Import the great circle formulas.\nuse Math::Trig ':greatcircle';",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [
            "To calculate the distance between London (51.3N 0.5W) and Tokyo (35.7N 139.8E) in kilometers:",
            "use Math::Trig qw(greatcircledistance deg2rad);",
            "# Notice the 90 - latitude: phi zero is at the North Pole.",
            "sub NESW { deg2rad($[0]), deg2rad(90 - $[1]) }",
            "my @L = NESW( -0.5, 51.3);",
            "my @T = NESW(139.8, 35.7);",
            "my $km = greatcircledistance(@L, @T, 6378); # About 9600 km.",
            "The direction you would have to go from London to Tokyo (in radians, straight north being zero,",
            "straight east being pi/2).",
            "use Math::Trig qw(greatcircledirection);",
            "my $rad = greatcircledirection(@L, @T); # About 0.547 or 0.174 pi.",
            "The midpoint between London and Tokyo being",
            "use Math::Trig qw(greatcirclemidpoint);",
            "my @M = greatcirclemidpoint(@L, @T);",
            "or about 69 N 89 E, in the frozen wastes of Siberia.",
            "NOTE: you cannot get from A to B like this:",
            "Dist = greatcircledistance(A, B)",
            "Dir  = greatcircledirection(A, B)",
            "C    = greatcircledestination(A, Dist, Dir)",
            "and expect C to be B, because the bearing constantly changes when going from A to B (except in",
            "some special case like the meridians or the circles of latitudes) and in",
            "CAVEAT FOR GREAT CIRCLE FORMULAS",
            "The answers may be off by few percentages because of the irregular (slightly aspherical) form of",
            "the Earth. The errors are at worst about 0.55%, but generally below 0.3%.",
            "For small inputs asin() and acos() may return complex numbers even when real numbers would be",
            "enough and correct, this happens because of floating-point inaccuracies. You can see these",
            "inaccuracies for example by trying theses:",
            "print cos(1e-6)2+sin(1e-6)2 - 1,\"\\n\";",
            "printf \"%.20f\", cos(1e-6)2+sin(1e-6)2,\"\\n\";",
            "which will print something like this",
            "-1.11022302462516e-16",
            "0.99999999999999988898",
            "even though the expected results are of course exactly zero and one. The formulas used to",
            "compute asin() and acos() are quite sensitive to this, and therefore they might accidentally",
            "slip into the complex plane even when they should not. To counter this there are two interfaces",
            "that are guaranteed to return a real-valued output.",
            "asinreal",
            "use Math::Trig qw(asinreal);",
            "$realangle = asinreal($inputsin);",
            "Return a real-valued arcus sine if the input is between [-1, 1], inclusive the endpoints.",
            "For inputs greater than one, pi/2 is returned. For inputs less than minus one, -pi/2 is",
            "returned.",
            "acosreal",
            "use Math::Trig qw(acosreal);",
            "$realangle = acosreal($inputcos);",
            "Return a real-valued arcus cosine if the input is between [-1, 1], inclusive the endpoints.",
            "For inputs greater than one, zero is returned. For inputs less than minus one, pi is",
            "returned."
        ],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 19,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "ANGLES",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "TRIGONOMETRIC FUNCTIONS",
                "lines": 14,
                "subsections": [
                    {
                        "name": "atan2",
                        "lines": 87
                    }
                ]
            },
            {
                "name": "PLANE ANGLE CONVERSIONS",
                "lines": 38,
                "subsections": []
            },
            {
                "name": "RADIAL COORDINATE CONVERSIONS",
                "lines": 64,
                "subsections": []
            },
            {
                "name": "GREAT CIRCLE DISTANCES AND DIRECTIONS",
                "lines": 6,
                "subsections": [
                    {
                        "name": "great_circle_distance",
                        "lines": 20
                    },
                    {
                        "name": "great_circle_direction",
                        "lines": 64
                    }
                ]
            },
            {
                "name": "EXAMPLES",
                "lines": 33,
                "subsections": [
                    {
                        "name": "great_circle_destination",
                        "lines": 4
                    },
                    {
                        "name": "Real-valued asin and acos",
                        "lines": 35
                    }
                ]
            },
            {
                "name": "BUGS",
                "lines": 10,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "AUTHORS",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "LICENSE",
                "lines": 3,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Math::Trig - trigonometric functions\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use Math::Trig;\n\n$x = tan(0.9);\n$y = acos(3.7);\n$z = asin(2.4);\n\n$halfpi = pi/2;\n\n$rad = deg2rad(120);\n\n# Import constants pi2, pip2, pip4 (2*pi, pi/2, pi/4).\nuse Math::Trig ':pi';\n\n# Import the conversions between cartesian/spherical/cylindrical.\nuse Math::Trig ':radial';\n\n# Import the great circle formulas.\nuse Math::Trig ':greatcircle';\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "\"Math::Trig\" defines many trigonometric functions not defined by the core Perl which defines\nonly the \"sin()\" and \"cos()\". The constant pi is also defined as are a few convenience functions\nfor angle conversions, and *great circle formulas* for spherical movement.\n",
                "subsections": []
            },
            "ANGLES": {
                "content": "All angles are defined in radians, except where otherwise specified (for example in the deg/rad\nconversion functions).\n",
                "subsections": []
            },
            "TRIGONOMETRIC FUNCTIONS": {
                "content": "The tangent\n\ntan\n\nThe cofunctions of the sine, cosine, and tangent (cosec/csc and cotan/cot are aliases)\n\ncsc, cosec, sec, sec, cot, cotan\n\nThe arcus (also known as the inverse) functions of the sine, cosine, and tangent\n\nasin, acos, atan\n\nThe principal value of the arc tangent of y/x\n",
                "subsections": [
                    {
                        "name": "atan2",
                        "content": "The arcus cofunctions of the sine, cosine, and tangent (acosec/acsc and acotan/acot are\naliases). Note that atan2(0, 0) is not well-defined.\n\nacsc, acosec, asec, acot, acotan\n\nThe hyperbolic sine, cosine, and tangent\n\nsinh, cosh, tanh\n\nThe cofunctions of the hyperbolic sine, cosine, and tangent (cosech/csch and cotanh/coth are\naliases)\n\ncsch, cosech, sech, coth, cotanh\n\nThe area (also known as the inverse) functions of the hyperbolic sine, cosine, and tangent\n\nasinh, acosh, atanh\n\nThe area cofunctions of the hyperbolic sine, cosine, and tangent (acsch/acosech and\nacoth/acotanh are aliases)\n\nacsch, acosech, asech, acoth, acotanh\n\nThe trigonometric constant pi and some of handy multiples of it are also defined.\n\npi, pi2, pi4, pip2, pip4\n\nERRORS DUE TO DIVISION BY ZERO\nThe following functions\n\nacoth\nacsc\nacsch\nasec\nasech\natanh\ncot\ncoth\ncsc\ncsch\nsec\nsech\ntan\ntanh\n\ncannot be computed for all arguments because that would mean dividing by zero or taking\nlogarithm of zero. These situations cause fatal runtime errors looking like this\n\ncot(0): Division by zero.\n(Because in the definition of cot(0), the divisor sin(0) is 0)\nDied at ...\n\nor\n\natanh(-1): Logarithm of zero.\nDied at...\n\nFor the \"csc\", \"cot\", \"asec\", \"acsc\", \"acot\", \"csch\", \"coth\", \"asech\", \"acsch\", the argument\ncannot be 0 (zero). For the \"atanh\", \"acoth\", the argument cannot be 1 (one). For the \"atanh\",\n\"acoth\", the argument cannot be -1 (minus one). For the \"tan\", \"sec\", \"tanh\", \"sech\", the\nargument cannot be *pi/2 + k * pi*, where *k* is any integer.\n\nNote that atan2(0, 0) is not well-defined.\n\nSIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS\nPlease note that some of the trigonometric functions can break out from the real axis into the\ncomplex plane. For example asin(2) has no definition for plain real numbers but it has\ndefinition for complex numbers.\n\nIn Perl terms this means that supplying the usual Perl numbers (also known as scalars, please\nsee perldata) as input for the trigonometric functions might produce as output results that no\nmore are simple real numbers: instead they are complex numbers.\n\nThe \"Math::Trig\" handles this by using the \"Math::Complex\" package which knows how to handle\ncomplex numbers, please see Math::Complex for more information. In practice you need not to\nworry about getting complex numbers as results because the \"Math::Complex\" takes care of details\nlike for example how to display complex numbers. For example:\n\nprint asin(2), \"\\n\";\n\nshould produce something like this (take or leave few last decimals):\n\n1.5707963267949-1.31695789692482i\n\nThat is, a complex number with the real part of approximately 1.571 and the imaginary part of\napproximately -1.317.\n"
                    }
                ]
            },
            "PLANE ANGLE CONVERSIONS": {
                "content": "(Plane, 2-dimensional) angles may be converted with the following functions.\n\ndeg2rad\n$radians  = deg2rad($degrees);\n\ngrad2rad\n$radians  = grad2rad($gradians);\n\nrad2deg\n$degrees  = rad2deg($radians);\n\ngrad2deg\n$degrees  = grad2deg($gradians);\n\ndeg2grad\n$gradians = deg2grad($degrees);\n\nrad2grad\n$gradians = rad2grad($radians);\n\nThe full circle is 2 *pi* radians or *360* degrees or *400* gradians. The result is by default\nwrapped to be inside the [0, {2pi,360,400}[ circle. If you don't want this, supply a true second\nargument:\n\n$zillionsofradians  = deg2rad($zillionsofdegrees, 1);\n$negativedegrees     = rad2deg($negativeradians, 1);\n\nYou can also do the wrapping explicitly by rad2rad(), deg2deg(), and grad2grad().\n\nrad2rad\n$radianswrappedby2pi = rad2rad($radians);\n\ndeg2deg\n$degreeswrappedby360 = deg2deg($degrees);\n\ngrad2grad\n$gradianswrappedby400 = grad2grad($gradians);\n",
                "subsections": []
            },
            "RADIAL COORDINATE CONVERSIONS": {
                "content": "Radial coordinate systems are the spherical and the cylindrical systems, explained shortly in\nmore detail.\n\nYou can import radial coordinate conversion functions by using the \":radial\" tag:\n\nuse Math::Trig ':radial';\n\n($rho, $theta, $z)     = cartesiantocylindrical($x, $y, $z);\n($rho, $theta, $phi)   = cartesiantospherical($x, $y, $z);\n($x, $y, $z)           = cylindricaltocartesian($rho, $theta, $z);\n($rhos, $theta, $phi) = cylindricaltospherical($rhoc, $theta, $z);\n($x, $y, $z)           = sphericaltocartesian($rho, $theta, $phi);\n($rhoc, $theta, $z)   = sphericaltocylindrical($rhos, $theta, $phi);\n\nAll angles are in radians.\n\nCOORDINATE SYSTEMS\nCartesian coordinates are the usual rectangular *(x, y, z)*-coordinates.\n\nSpherical coordinates, *(rho, theta, pi)*, are three-dimensional coordinates which define a\npoint in three-dimensional space. They are based on a sphere surface. The radius of the sphere\nis rho, also known as the *radial* coordinate. The angle in the *xy*-plane (around the *z*-axis)\nis theta, also known as the *azimuthal* coordinate. The angle from the *z*-axis is phi, also\nknown as the *polar* coordinate. The North Pole is therefore *0, 0, rho*, and the Gulf of Guinea\n(think of the missing big chunk of Africa) *0, pi/2, rho*. In geographical terms *phi* is\nlatitude (northward positive, southward negative) and *theta* is longitude (eastward positive,\nwestward negative).\n\nBEWARE: some texts define *theta* and *phi* the other way round, some texts define the *phi* to\nstart from the horizontal plane, some texts use *r* in place of *rho*.\n\nCylindrical coordinates, *(rho, theta, z)*, are three-dimensional coordinates which define a\npoint in three-dimensional space. They are based on a cylinder surface. The radius of the\ncylinder is rho, also known as the *radial* coordinate. The angle in the *xy*-plane (around the\n*z*-axis) is theta, also known as the *azimuthal* coordinate. The third coordinate is the *z*,\npointing up from the theta-plane.\n\n3-D ANGLE CONVERSIONS\nConversions to and from spherical and cylindrical coordinates are available. Please notice that\nthe conversions are not necessarily reversible because of the equalities like *pi* angles being\nequal to *-pi* angles.\n\ncartesiantocylindrical\n($rho, $theta, $z) = cartesiantocylindrical($x, $y, $z);\n\ncartesiantospherical\n($rho, $theta, $phi) = cartesiantospherical($x, $y, $z);\n\ncylindricaltocartesian\n($x, $y, $z) = cylindricaltocartesian($rho, $theta, $z);\n\ncylindricaltospherical\n($rhos, $theta, $phi) = cylindricaltospherical($rhoc, $theta, $z);\n\nNotice that when $z is not 0 $rhos is not equal to $rhoc.\n\nsphericaltocartesian\n($x, $y, $z) = sphericaltocartesian($rho, $theta, $phi);\n\nsphericaltocylindrical\n($rhoc, $theta, $z) = sphericaltocylindrical($rhos, $theta, $phi);\n\nNotice that when $z is not 0 $rhoc is not equal to $rhos.\n",
                "subsections": []
            },
            "GREAT CIRCLE DISTANCES AND DIRECTIONS": {
                "content": "A great circle is section of a circle that contains the circle diameter: the shortest distance\nbetween two (non-antipodal) points on the spherical surface goes along the great circle\nconnecting those two points.\n\ngreatcircledistance\nYou can compute spherical distances, called great circle distances, by importing the",
                "subsections": [
                    {
                        "name": "great_circle_distance",
                        "content": "use Math::Trig 'greatcircledistance';\n\n$distance = greatcircledistance($theta0, $phi0, $theta1, $phi1, [, $rho]);\n\nThe *great circle distance* is the shortest distance between two points on a sphere. The\ndistance is in $rho units. The $rho is optional, it defaults to 1 (the unit sphere), therefore\nthe distance defaults to radians.\n\nIf you think geographically the *theta* are longitudes: zero at the Greenwhich meridian,\neastward positive, westward negative -- and the *phi* are latitudes: zero at the North Pole,\nnorthward positive, southward negative. NOTE: this formula thinks in mathematics, not\ngeographically: the *phi* zero is at the North Pole, not at the Equator on the west coast of\nAfrica (Bay of Guinea). You need to subtract your geographical coordinates from *pi/2* (also\nknown as 90 degrees).\n\n$distance = greatcircledistance($lon0, pi/2 - $lat0,\n$lon1, pi/2 - $lat1, $rho);\n\ngreatcircledirection\nThe direction you must follow the great circle (also known as *bearing*) can be computed by the"
                    },
                    {
                        "name": "great_circle_direction",
                        "content": "use Math::Trig 'greatcircledirection';\n\n$direction = greatcircledirection($theta0, $phi0, $theta1, $phi1);\n\ngreatcirclebearing\nAlias 'greatcirclebearing' for 'greatcircledirection' is also available.\n\nuse Math::Trig 'greatcirclebearing';\n\n$direction = greatcirclebearing($theta0, $phi0, $theta1, $phi1);\n\nThe result of greatcircledirection is in radians, zero indicating straight north, pi or -pi\nstraight south, pi/2 straight west, and -pi/2 straight east.\n\ngreatcircledestination\nYou can inversely compute the destination if you know the starting point, direction, and\ndistance:\n\nuse Math::Trig 'greatcircledestination';\n\n# $diro is the original direction,\n# for example from greatcirclebearing().\n# $distance is the angular distance in radians,\n# for example from greatcircledistance().\n# $thetad and $phid are the destination coordinates,\n# $dird is the final direction at the destination.\n\n($thetad, $phid, $dird) =\ngreatcircledestination($theta, $phi, $diro, $distance);\n\nor the midpoint if you know the end points:\n\ngreatcirclemidpoint\nuse Math::Trig 'greatcirclemidpoint';\n\n($thetam, $phim) =\ngreatcirclemidpoint($theta0, $phi0, $theta1, $phi1);\n\nThe greatcirclemidpoint() is just a special case (with $way = 0.5) of\n\ngreatcirclewaypoint\nuse Math::Trig 'greatcirclewaypoint';\n\n($thetai, $phii) =\ngreatcirclewaypoint($theta0, $phi0, $theta1, $phi1, $way);\n\nWhere the $way is a value from zero ($theta0, $phi0) to one ($theta1, $phi1). Note that\nantipodal points (where their distance is *pi* radians) do not have waypoints between them (they\nwould have an an \"equator\" between them), and therefore \"undef\" is returned for antipodal\npoints. If the points are the same and the distance therefore zero and all waypoints therefore\nidentical, the first point (either point) is returned.\n\nThe thetas, phis, direction, and distance in the above are all in radians.\n\nYou can import all the great circle formulas by\n\nuse Math::Trig ':greatcircle';\n\nNotice that the resulting directions might be somewhat surprising if you are looking at a flat\nworldmap: in such map projections the great circles quite often do not look like the shortest\nroutes -- but for example the shortest possible routes from Europe or North America to Asia do\noften cross the polar regions. (The common Mercator projection does not show great circles as\nstraight lines: straight lines in the Mercator projection are lines of constant bearing.)\n"
                    }
                ]
            },
            "EXAMPLES": {
                "content": "To calculate the distance between London (51.3N 0.5W) and Tokyo (35.7N 139.8E) in kilometers:\n\nuse Math::Trig qw(greatcircledistance deg2rad);\n\n# Notice the 90 - latitude: phi zero is at the North Pole.\nsub NESW { deg2rad($[0]), deg2rad(90 - $[1]) }\nmy @L = NESW( -0.5, 51.3);\nmy @T = NESW(139.8, 35.7);\nmy $km = greatcircledistance(@L, @T, 6378); # About 9600 km.\n\nThe direction you would have to go from London to Tokyo (in radians, straight north being zero,\nstraight east being pi/2).\n\nuse Math::Trig qw(greatcircledirection);\n\nmy $rad = greatcircledirection(@L, @T); # About 0.547 or 0.174 pi.\n\nThe midpoint between London and Tokyo being\n\nuse Math::Trig qw(greatcirclemidpoint);\n\nmy @M = greatcirclemidpoint(@L, @T);\n\nor about 69 N 89 E, in the frozen wastes of Siberia.\n\nNOTE: you cannot get from A to B like this:\n\nDist = greatcircledistance(A, B)\nDir  = greatcircledirection(A, B)\nC    = greatcircledestination(A, Dist, Dir)\n\nand expect C to be B, because the bearing constantly changes when going from A to B (except in\nsome special case like the meridians or the circles of latitudes) and in",
                "subsections": [
                    {
                        "name": "great_circle_destination",
                        "content": "CAVEAT FOR GREAT CIRCLE FORMULAS\nThe answers may be off by few percentages because of the irregular (slightly aspherical) form of\nthe Earth. The errors are at worst about 0.55%, but generally below 0.3%.\n"
                    },
                    {
                        "name": "Real-valued asin and acos",
                        "content": "For small inputs asin() and acos() may return complex numbers even when real numbers would be\nenough and correct, this happens because of floating-point inaccuracies. You can see these\ninaccuracies for example by trying theses:\n\nprint cos(1e-6)2+sin(1e-6)2 - 1,\"\\n\";\nprintf \"%.20f\", cos(1e-6)2+sin(1e-6)2,\"\\n\";\n\nwhich will print something like this\n\n-1.11022302462516e-16\n0.99999999999999988898\n\neven though the expected results are of course exactly zero and one. The formulas used to\ncompute asin() and acos() are quite sensitive to this, and therefore they might accidentally\nslip into the complex plane even when they should not. To counter this there are two interfaces\nthat are guaranteed to return a real-valued output.\n\nasinreal\nuse Math::Trig qw(asinreal);\n\n$realangle = asinreal($inputsin);\n\nReturn a real-valued arcus sine if the input is between [-1, 1], inclusive the endpoints.\nFor inputs greater than one, pi/2 is returned. For inputs less than minus one, -pi/2 is\nreturned.\n\nacosreal\nuse Math::Trig qw(acosreal);\n\n$realangle = acosreal($inputcos);\n\nReturn a real-valued arcus cosine if the input is between [-1, 1], inclusive the endpoints.\nFor inputs greater than one, zero is returned. For inputs less than minus one, pi is\nreturned.\n"
                    }
                ]
            },
            "BUGS": {
                "content": "Saying \"use Math::Trig;\" exports many mathematical routines in the caller environment and even\noverrides some (\"sin\", \"cos\"). This is construed as a feature by the Authors, actually... ;-)\n\nThe code is not optimized for speed, especially because we use \"Math::Complex\" and thus go quite\nnear complex numbers while doing the computations even when the arguments are not. This,\nhowever, cannot be completely avoided if we want things like asin(2) to give an answer instead\nof giving a fatal runtime error.\n\nDo not attempt navigation using these formulas.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "Math::Complex\n",
                "subsections": []
            },
            "AUTHORS": {
                "content": "Jarkko Hietaniemi <jhi!at!iki.fi>, Raphael Manfredi <RaphaelManfredi!at!pobox.com>, Zefram\n<zefram@fysh.org>\n",
                "subsections": []
            },
            "LICENSE": {
                "content": "This library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
                "subsections": []
            }
        }
    }
}