# info > Math::Trig

---
type: CommandReference
command: Math::Trig
mode: perldoc
section: 3perl
source: perldoc
---

## Quick Reference

- `use Math::Trig;` — import all trigonometric functions
- `$x = tan(0.9);` — tangent
- `$y = acos(3.7);` — arc cosine (may return complex)
- `$rad = deg2rad(120);` — degrees to radians
- `use Math::Trig ':pi';` — import constants `pi2`, `pip2`, `pip4`
- `use Math::Trig ':radial';` — import coordinate conversion functions
- `use Math::Trig ':great_circle';` — import great circle formulas
- `$distance = great_circle_distance($theta0, $phi0, $theta1, $phi1, $rho);` — compute spherical distance

## Name

Math::Trig - trigonometric functions

## Synopsis

perl
use Math::Trig;

$x = tan(0.9);
$y = acos(3.7);
$z = asin(2.4);

$halfpi = pi/2;

$rad = deg2rad(120);

# Import constants pi2, pip2, pip4 (2*pi, pi/2, pi/4).
use Math::Trig ':pi';

# Import the conversions between cartesian/spherical/cylindrical.
use Math::Trig ':radial';

# Import the great circle formulas.
use Math::Trig ':great_circle';
## Functions

All angles are in radians unless otherwise noted.

### Trigonometric Functions

- `tan($x)` — tangent
- `csc($x)`, `cosec($x)` — cosecant
- `sec($x)` — secant
- `cot($x)`, `cotan($x)` — cotangent
- `asin($x)` — arc sine (inverse sine)
- `acos($x)` — arc cosine
- `atan($x)` — arc tangent
- `atan2($y, $x)` — principal value of arc tangent of y/x (note: `atan2(0,0)` not well-defined)
- `acsc($x)`, `acosec($x)` — arc cosecant
- `asec($x)` — arc secant
- `acot($x)`, `acotan($x)` — arc cotangent

### Hyperbolic Functions

- `sinh($x)` — hyperbolic sine
- `cosh($x)` — hyperbolic cosine
- `tanh($x)` — hyperbolic tangent
- `csch($x)`, `cosech($x)` — hyperbolic cosecant
- `sech($x)` — hyperbolic secant
- `coth($x)`, `cotanh($x)` — hyperbolic cotangent
- `asinh($x)` — area hyperbolic sine (inverse hyperbolic sine)
- `acosh($x)` — area hyperbolic cosine
- `atanh($x)` — area hyperbolic tangent
- `acsch($x)`, `acosech($x)` — area hyperbolic cosecant
- `asech($x)` — area hyperbolic secant
- `acoth($x)`, `acotanh($x)` — area hyperbolic cotangent

### Constants

- `pi` — π
- `pi2`, `pip2`, `pip4` — 2π, π/2, π/4 (imported with `:pi`)

### Errors Due to Division by Zero

The following functions cannot be computed for all arguments (division by zero or logarithm of zero): `acoth`, `acsc`, `acsch`, `asec`, `asech`, `atanh`, `cot`, `coth`, `csc`, `csch`, `sec`, `sech`, `tan`, `tanh`. These cause fatal runtime errors. Restrictions:

- `csc`, `cot`, `asec`, `acsc`, `acot`, `csch`, `coth`, `asech`, `acsch`: argument cannot be 0.
- `atanh`, `acoth`: argument cannot be 1 or -1.
- `tan`, `sec`, `tanh`, `sech`: argument cannot be π/2 + kπ for integer k.

Note: `atan2(0,0)` is not well-defined.

### Simple (Real) Arguments, Complex Results

Some functions (e.g., `asin(2)`) may return complex numbers when real input is outside the normal domain. The module uses `Math::Complex` to handle this transparently. Example:

perl
print asin(2), "\n";  # 1.5707963267949-1.31695789692482i
### Real-Valued asin and acos

Due to floating-point inaccuracies, `asin` and `acos` may return complex numbers for small real inputs. Counter functions:

- `asin_real($x)` — returns real arc sine for $x in [-1,1]; returns π/2 for $x>1, -π/2 for $x<-1.
- `acos_real($x)` — returns real arc cosine for $x in [-1,1]; returns 0 for $x>1, π for $x<-1.

### Plane Angle Conversions

- `deg2rad($degrees, $wrap?)` — degrees to radians; default wraps to [0,2π). Supply true second argument to skip wrapping.
- `grad2rad($gradians, $wrap?)` — gradians to radians
- `rad2deg($radians, $wrap?)` — radians to degrees
- `grad2deg($gradians, $wrap?)` — gradians to degrees
- `deg2grad($degrees, $wrap?)` — degrees to gradians
- `rad2grad($radians, $wrap?)` — radians to gradians
- `rad2rad($radians)` — wrap radians to [0,2π)
- `deg2deg($degrees)` — wrap degrees to [0,360)
- `grad2grad($gradians)` — wrap gradians to [0,400)

### Radial Coordinate Conversions

Import with `:radial` tag. All angles in radians.

- `cartesian_to_cylindrical($x, $y, $z)` → `($rho, $theta, $z)`
- `cartesian_to_spherical($x, $y, $z)` → `($rho, $theta, $phi)`
- `cylindrical_to_cartesian($rho, $theta, $z)` → `($x, $y, $z)`
- `cylindrical_to_spherical($rho_c, $theta, $z)` → `($rho_s, $theta, $phi)` — note: $rho_s ≠ $rho_c when $z≠0
- `spherical_to_cartesian($rho, $theta, $phi)` → `($x, $y, $z)`
- `spherical_to_cylindrical($rho_s, $theta, $phi)` → `($rho_c, $theta, $z)` — note: $rho_c ≠ $rho_s when $z≠0

Coordinate systems:
- **Cartesian**: (x, y, z)
- **Spherical**: (rho, theta, phi) — rho = radial, theta = azimuthal (xy-plane), phi = polar (from z-axis). North Pole: (0, 0, rho). In geography: phi = latitude (north positive), theta = longitude (east positive). Beware of differing conventions.
- **Cylindrical**: (rho, theta, z) — rho = radial, theta = azimuthal, z = height.

### Great Circle Distances and Directions

Import individually or with `:great_circle` tag.

- `great_circle_distance($theta0, $phi0, $theta1, $phi1, $rho)` — shortest distance between two points on sphere. $rho defaults to 1 (unit sphere). Theta = longitude, phi = latitude (0 at North Pole). To convert geographical latitude: use `pi/2 - $lat`.
- `great_circle_direction($theta0, $phi0, $theta1, $phi1)` — bearing (direction) at start, in radians. 0 = north, π/2 = east, -π/2 = west, π = south.
- `great_circle_bearing($theta0, $phi0, $theta1, $phi1)` — alias for `great_circle_direction`.
- `great_circle_destination($theta, $phi, $diro, $distance)` → `($thetad, $phid, $dird)` — destination given start, direction, and angular distance. Returns final direction at destination.
- `great_circle_midpoint($theta0, $phi0, $theta1, $phi1)` → `($thetam, $phim)` — midpoint between two points.
- `great_circle_waypoint($theta0, $phi0, $theta1, $phi1, $way)` → `($thetai, $phii)` — waypoint along great circle, where $way ∈ [0,1]. Returns `undef` for antipodal points (distance = π). Returns first point if distance = 0.

Note: The bearing changes constantly along a great circle; `great_circle_destination` assumes constant bearing, so you cannot round-trip A→B→A using these formulas.

### Caveat for Great Circle Formulas

Errors due to Earth's irregular shape are at most about 0.55%, typically below 0.3%.

## Examples

Distance between London (51.3N, 0.5W) and Tokyo (35.7N, 139.8E) in kilometers:

perl
use Math::Trig qw(great_circle_distance deg2rad);

sub NESW { deg2rad($_[0]), deg2rad(90 - $_[1]) }
my @L = NESW( -0.5, 51.3);
my @T = NESW(139.8, 35.7);
my $km = great_circle_distance(@L, @T, 6378); # About 9600 km.
Direction from London to Tokyo (radians, 0 = north, π/2 = east):

perl
use Math::Trig qw(great_circle_direction);
my $rad = great_circle_direction(@L, @T); # About 0.547 or 0.174 π.
Midpoint between London and Tokyo:

perl
use Math::Trig qw(great_circle_midpoint);
my @M = great_circle_midpoint(@L, @T); # About 69 N 89 E (Siberia).
## Bugs

- `use Math::Trig;` exports many routines into the caller's namespace, overriding core `sin` and `cos`. This is by design.
- Code is not optimized for speed; uses `Math::Complex` even when arguments are real, to allow `asin(2)` to return a complex result instead of dying.
- Do not use these formulas for actual navigation.

## See Also

- [Math::Complex](https://www.chedong.com/phpMan.php/perldoc/Math%3A%3AComplex/markdown)