# std/complex

Theme:

- 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

    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, strformat, strutils

# 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

    proc formatValue(result: var string; value: Complex; specifier: string)

  Standard format implementation for `Complex`. It makes little sense to call this directly, but it is required to exist by the `&` macro. For complex numbers, we add a specific 'j' specifier, which formats the value as (A+Bj) like in mathematics. 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 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