# man > Math::Complex

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

## Quick Reference

- `use Math::Complex;` — load the module
- `$z = Math::Complex->make(3, 4);` — create complex number from cartesian coordinates
- `$z = cplx(3, 4);` — shorthand for `make`
- `$z = 3 + 4*i;` — direct notation
- `$z = Math::Complex->emake(5, pi/3);` — create from polar coordinates (modulus, angle in radians)
- `$z = cplxe(5, pi/3);` — shorthand for `emake`
- `$j = (root(1, 3))[1];` — get the cube root of unity
- `$j->display_format('polar');` — set display style per number

## Name

complex numbers and associated mathematical functions

## Synopsis

perl
use Math::Complex;

$z = Math::Complex->make(5, 6);
$t = 4 - 3*i + $z;
$j = cplxe(1, 2*pi/3);
## Operations

### Arithmetic

- `+`, `-`, `*`, `/`, `**` — overloaded operators
- `~$z` — conjugate (`a - bi`)
- `abs($z)` — modulus (`sqrt(a*a + b*b)`)
- `sqrt($z)` — square root (principal value)
- `exp($z)`, `log($z)` — exponential and natural logarithm
- `atan2(y, x)` — angle from coordinates (complex arguments: `-i log((x+iy)/sqrt(x*x+y*y))`)

### Component extraction and mutators

- `Re($z)`, `Im($z)` — real and imaginary parts
- `arg($z)` (alias `theta`) — argument (angle in radians)
- `abs($z)` (alias `rho`) — modulus
- These can also be used as mutators: `$z->Re(3)`, `$j->arg(2)`

### Trigonometric

- `sin($z)`, `cos($z)`, `tan($z)`
- `csc($z)`, `sec($z)`, `cot($z)` (aliases: `cosec`, `cotan`)
- `asin($z)`, `acos($z)`, `atan($z)`
- `acsc($z)`, `asec($z)`, `acot($z)` (aliases: `acosec`, `acotan`)

### Hyperbolic

- `sinh($z)`, `cosh($z)`, `tanh($z)`
- `csch($z)`, `sech($z)`, `coth($z)` (aliases: `cosech`, `cotanh`)
- `asinh($z)`, `acosh($z)`, `atanh($z)`
- `acsch($z)`, `asech($z)`, `acoth($z)` (aliases: `acosech`, `acotanh`)

### Roots and logarithms

- `root($z, $n)` — returns list of all `n` roots; `root($z, $n, $k)` returns the `k`-th root directly
- `cbrt($z)` — cube root (principal)
- `log10($z)`, `logn($z, $n)` — base-10 and base-n logarithms

### Comparison

- `<=>` — spaceship operator; compares real part first, then imaginary part

## Creation

perl
$z = Math::Complex->make(3, 4);     # cartesian
$z = cplx(3, 4);                    # same
$z = 3 + 4*i;                       # direct

$z = Math::Complex->emake(5, pi/3); # polar (modulus, angle)
$z = cplxe(5, pi/3);               # same

$z = cplx("2-3i");                  # parse string
$z = cplx("[2,3]");                # parse polar string
## Display

Default display style is `cartesian` (`a+bi`). Use `polar` to show `[r,t]`.

- Class method: `Math::Complex::display_format('polar')`
- Instance method: `$z->display_format('polar')`

Additional parameters (Perl 5.6+):
- `style` — `'cartesian'` or `'polar'`
- `format` — `sprintf` format string (e.g., `'%.5f'`)
- `polar_pretty_print` — boolean (default true)

## Usage Examples

perl
use Math::Complex;

$j = cplxe(1, 2*pi/3);  # $j ** 3 == 1
print "j = $j, j**3 = ", $j ** 3, "\n";
print "1 + j + j**2 = ", 1 + $j + $j**2, "\n";

$z = -16 + 0*i;                 # Force complex
print "sqrt($z) = ", sqrt($z), "\n";

$k = exp(i * 2*pi/3);
print "$j - $k = ", $j - $k, "\n";

$z->Re(3);                      # Mutator
$j->arg(2);
## Constants

- `pi` — exported via `use Math::Complex ':pi';`
- `pi2`, `pi4`, `pip2` (pi/2), `pip4` (pi/4)
- `Inf()` — exported via `use Math::Complex qw(Inf);`

## Errors

- Division by zero or logarithm of zero causes fatal runtime errors.
- Singularities: `csc`, `cot`, `asec`, `acsc`, `acot`, `csch`, `coth`, `asech`, `acsch` cannot have argument 0.
- `log`, `ln`, `log10`, `logn`, `atanh`, `acoth` cannot have argument 1 or -1.
- `atan`, `acot` cannot have argument `i` or `-i`.
- `tan`, `sec`, `tanh` cannot have argument `pi/2 + k*pi`.
- `atan2(0, 0)` is undefined.

## See Also

[Math::Trig](https://perldoc.perl.org/Math::Trig)