# std/complex

Search:
Source   Edit

This module implements complex numbers and basic mathematical operations on them.

Complex numbers are currently generic over 64-bit or 32-bit floats.

Example:

```import std/complex
from std/math import almostEqual, sqrt

let
z1 = complex(1.0, 2.0)
z2 = complex(3.0, -4.0)

assert almostEqual(z1 + z2, complex(4.0, -2.0))
assert almostEqual(z1 - z2, complex(-2.0, 6.0))
assert almostEqual(z1 * z2, complex(11.0, 2.0))
assert almostEqual(z1 / z2, complex(-0.2, 0.4))

assert almostEqual(abs(z1), sqrt(5.0))
assert almostEqual(conjugate(z1), complex(1.0, -2.0))

let (r, phi) = z1.polar
assert almostEqual(rect(r, phi), z1)```

math

# Types

```Complex[T] = object
re*, im*: T```
A complex number, consisting of a real and an imaginary part. Source   Edit
`Complex32 = Complex[float32]`
Alias for a complex number using 32-bit floats. Source   Edit
`Complex64 = Complex[float64]`
Alias for a complex number using 64-bit floats. Source   Edit

# Procs

`func `\$`(z: Complex): string`
Returns z's string representation as "(re, im)".

Example:

`doAssert \$complex(1.0, 2.0) == "(1.0, 2.0)"`
Source   Edit
`func `*`[T](x, y: Complex[T]): Complex[T]`
Multiplies two complex numbers. Source   Edit
`func `*`[T](x: Complex[T]; y: T): Complex[T]`
Multiplies a complex number with a real number. Source   Edit
`func `*`[T](x: T; y: Complex[T]): Complex[T]`
Multiplies a real number with a complex number. Source   Edit
`func `*=`[T](x: var Complex[T]; y: Complex[T])`
Multiplies x by y. Source   Edit
`func `+`[T](x, y: Complex[T]): Complex[T]`
Adds two complex numbers. Source   Edit
`func `+`[T](x: Complex[T]; y: T): Complex[T]`
Adds a complex number to a real number. Source   Edit
`func `+`[T](x: T; y: Complex[T]): Complex[T]`
Adds a real number to a complex number. Source   Edit
`func `+=`[T](x: var Complex[T]; y: Complex[T])`
Adds y to x. Source   Edit
`func `-`[T](x, y: Complex[T]): Complex[T]`
Subtracts two complex numbers. Source   Edit
`func `-`[T](x: Complex[T]; y: T): Complex[T]`
Subtracts a real number from a complex number. Source   Edit
`func `-`[T](x: T; y: Complex[T]): Complex[T]`
Subtracts a complex number from a real number. Source   Edit
`func `-`[T](z: Complex[T]): Complex[T]`
Unary minus for complex numbers. Source   Edit
`func `-=`[T](x: var Complex[T]; y: Complex[T])`
Subtracts y from x. Source   Edit
`func `/`[T](x, y: Complex[T]): Complex[T]`
Divides two complex numbers. Source   Edit
`func `/`[T](x: Complex[T]; y: T): Complex[T]`
Divides a complex number by a real number. Source   Edit
`func `/`[T](x: T; y: Complex[T]): Complex[T]`
Divides a real number by a complex number. Source   Edit
`func `/=`[T](x: var Complex[T]; y: Complex[T])`
Divides x by y in place. Source   Edit
`func `==`[T](x, y: Complex[T]): bool`
Compares two complex numbers for equality. Source   Edit
`func abs[T](z: Complex[T]): T`
Returns the absolute value of z, that is the distance from (0, 0) to z. Source   Edit
`func abs2[T](z: Complex[T]): T`
Returns the squared absolute value of z, that is the squared distance from (0, 0) to z. This is more efficient than abs(z) ^ 2. Source   Edit
`func almostEqual[T: SomeFloat](x, y: Complex[T]; unitsInLastPlace: Natural = 4): bool`

Checks if two complex values are almost equal, using the machine epsilon.

Two complex values are considered almost equal if their real and imaginary components are almost equal.

unitsInLastPlace is the max number of units in the last place difference tolerated when comparing two numbers. The larger the value, the more error is allowed. A 0 value means that two numbers must be exactly the same to be considered equal.

The machine epsilon has to be scaled to the magnitude of the values used and multiplied by the desired precision in ULPs unless the difference is subnormal.

Source   Edit
`func arccos[T](z: Complex[T]): Complex[T]`
Returns the inverse cosine of z. Source   Edit
`func arccosh[T](z: Complex[T]): Complex[T]`
Returns the inverse hyperbolic cosine of z. Source   Edit
`func arccot[T](z: Complex[T]): Complex[T]`
Returns the inverse cotangent of z. Source   Edit
`func arccoth[T](z: Complex[T]): Complex[T]`
Returns the inverse hyperbolic cotangent of z. Source   Edit
`func arccsc[T](z: Complex[T]): Complex[T]`
Returns the inverse cosecant of z. Source   Edit
`func arccsch[T](z: Complex[T]): Complex[T]`
Returns the inverse hyperbolic cosecant of z. Source   Edit
`func arcsec[T](z: Complex[T]): Complex[T]`
Returns the inverse secant of z. Source   Edit
`func arcsech[T](z: Complex[T]): Complex[T]`
Returns the inverse hyperbolic secant of z. Source   Edit
`func arcsin[T](z: Complex[T]): Complex[T]`
Returns the inverse sine of z. Source   Edit
`func arcsinh[T](z: Complex[T]): Complex[T]`
Returns the inverse hyperbolic sine of z. Source   Edit
`func arctan[T](z: Complex[T]): Complex[T]`
Returns the inverse tangent of z. Source   Edit
`func arctanh[T](z: Complex[T]): Complex[T]`
Returns the inverse hyperbolic tangent of z. Source   Edit
`func complex[T: SomeFloat](re: T; im: T = 0.0): Complex[T]`
Returns a Complex[T] with real part re and imaginary part im. Source   Edit
```func complex32(re: float32; im: float32 = 0.0): Complex32 {....raises: [],
tags: [], forbids: [].}```
Returns a Complex32 with real part re and imaginary part im. Source   Edit
```func complex64(re: float64; im: float64 = 0.0): Complex64 {....raises: [],
tags: [], forbids: [].}```
Returns a Complex64 with real part re and imaginary part im. Source   Edit
`func conjugate[T](z: Complex[T]): Complex[T]`
Returns the complex conjugate of z (complex(z.re, -z.im)). Source   Edit
`func cos[T](z: Complex[T]): Complex[T]`
Returns the cosine of z. Source   Edit
`func cosh[T](z: Complex[T]): Complex[T]`
Returns the hyperbolic cosine of z. Source   Edit
`func cot[T](z: Complex[T]): Complex[T]`
Returns the cotangent of z. Source   Edit
`func coth[T](z: Complex[T]): Complex[T]`
Returns the hyperbolic cotangent of z. Source   Edit
`func csc[T](z: Complex[T]): Complex[T]`
Returns the cosecant of z. Source   Edit
`func csch[T](z: Complex[T]): Complex[T]`
Returns the hyperbolic cosecant of z. Source   Edit
`func exp[T](z: Complex[T]): Complex[T]`
Computes the exponential function (e^z). Source   Edit
`func inv[T](z: Complex[T]): Complex[T]`
Returns the multiplicative inverse of z (1/z). Source   Edit
`func ln[T](z: Complex[T]): Complex[T]`
Returns the (principal value of the) natural logarithm of z. Source   Edit
`func log2[T](z: Complex[T]): Complex[T]`

Returns the logarithm base 2 of z.

Source   Edit
`func log10[T](z: Complex[T]): Complex[T]`

Returns the logarithm base 10 of z.

Source   Edit
`func phase[T](z: Complex[T]): T`
Returns the phase (or argument) of z, that is the angle in polar representation.

result = arctan2(z.im, z.re)

Source   Edit
`func polar[T](z: Complex[T]): tuple[r, phi: T]`
Returns z in polar coordinates.

result.r = abs(z)
result.phi = phase(z)

Source   Edit
`func pow[T](x, y: Complex[T]): Complex[T]`
x raised to the power of y. Source   Edit
`func pow[T](x: Complex[T]; y: T): Complex[T]`
The complex number x raised to the power of the real number y. Source   Edit
`func rect[T](r, phi: T): Complex[T]`
Returns the complex number with polar coordinates r and phi.

result.re = r * cos(phi)
result.im = r * sin(phi)

Source   Edit
`func sec[T](z: Complex[T]): Complex[T]`
Returns the secant of z. Source   Edit
`func sech[T](z: Complex[T]): Complex[T]`
Returns the hyperbolic secant of z. Source   Edit
`func sgn[T](z: Complex[T]): Complex[T]`
Returns the phase of z as a unit complex number, or 0 if z is 0. Source   Edit
`func sin[T](z: Complex[T]): Complex[T]`
Returns the sine of z. Source   Edit
`func sinh[T](z: Complex[T]): Complex[T]`
Returns the hyperbolic sine of z. Source   Edit
`func sqrt[T](z: Complex[T]): Complex[T]`
Computes the (principal) square root of a complex number z. Source   Edit
`func tan[T](z: Complex[T]): Complex[T]`
Returns the tangent of z. Source   Edit
`func tanh[T](z: Complex[T]): Complex[T]`
Returns the hyperbolic tangent of z. Source   Edit

# Templates

`template im(arg: float32): Complex32`
Returns arg as an imaginary number (complex32(0, arg)). Source   Edit
`template im(arg: float64): Complex64`
Returns arg as an imaginary number (complex64(0, arg)). Source   Edit
`template im(arg: typedesc[float32]): Complex32`
Returns the imaginary unit (complex32(0, 1)). Source   Edit
`template im(arg: typedesc[float64]): Complex64`
Returns the imaginary unit (complex64(0, 1)). Source   Edit