# std/complex

Dark Mode

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

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

    func almostEqual(a, b: Complex): bool =
      almostEqual(a.re, b.re) and almostEqual(a.im, b.im)

    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)

# Imports

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: var Complex[T]; y: Complex[T])

  Multiplies `x` by `y`. 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])

  Adds `y` to `x`. 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])

  Subtracts `y` from `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])

  Divides `x` by `y` in place. 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, y: Complex[T]): bool

  Compares two complex numbers for equality. 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 abs[T](z: Complex[T]): T

  Returns the absolute value of `z`, that is the distance from (0, 0) to `z`. 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 complex32(re: float32; im: float32 = 0.0): Complex32 {....raises: [], tags: [].}

  Returns a `Complex32` with real part `re` and imaginary part `im`. Source Edit

    func complex64(re: float64; im: float64 = 0.0): Complex64 {....raises: [], tags: [].}

  Returns a `Complex64` with real part `re` and imaginary part `im`. 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 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`.

  See also:

  - ln func
  Source Edit

    func log10[T](z: Complex[T]): Complex[T]

  Returns the logarithm base 10 of `z`.

  See also:

  - ln func
  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)`

  See also:

  - rect func for the inverse operation
  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)`

  See also:

  - polar func for the inverse operation
  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 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