complex_num v1.1.0 ComplexNum

Complex Numbers.

Cartesian vs Polar

There are two kinds of representaions for Complex Numbers:

  • Cartesian, of the form a + bi. (Storing the real and imaginary parts of the complex number)
  • Polar, of the form r * e^(i*phi). (storing the magnitude and the angle of the complex number)

Polar form is very useful to perform fast multiplications, division and integer powers with. Also, it obviously allows for O(1) precise computation of the magnitude and the angle.

Cartesian form on the other hand, allows besides multiplication and division, precise addition and subtraction. Also, it obviously allows for O(1) precise computation of the real and imaginary parts.

Conversions between these two representations is possible, but lossy: This involves trigonometry and square roots, which means that precision is lost. (CompexNum converts the internal data types to floats and back to perform these oprations.)

Internal data types

ComplexNum uses the Numbers library, which means that the real/imaginary (resp. magnitude/angle) can be of any data type that implements Numbers’ Numeric behaviour. This means that Integers, Floats, arbitrary precision decimals defined by the Decimals package, rationals defined by the Ratio package, etc. can be used.

ComplexNum itself also follows the Numeric behaviour, which means that it can be used inside any container that uses Numbers. (Including inside ComplexNum itself, but who would do such a thing?)

Summary

Functions

The absolute value of a Complex Number ca has as real part the same magnitude as ca, but as imaginary part 0

Adds two ComplexNums together. If both are Cartesian, this is a precise operation

Returns the angle of the complex number

Divides ca by cb. This is a precise operation for numbers in both Cartesian and Polar forms

Returns the magnitude of the Complex Number

The squared magnitude of the Complex Number

The negation of a Complex Number: Both the real and imaginary parts are negated

Multiplies ca by cb. This is a precise operation for numbers in both Cartesian and Polar forms

Power function: computes base^exponent, where base is a Complex Number, and exponent has to be an integer

Subtracts one ComplexNum from another. If both are Cartesian, this is a precise operation

Converts a Complex Number to Cartesian Form

Converts a Complex Number to Polar Form

Functions

abs(complex)

The absolute value of a Complex Number ca has as real part the same magnitude as ca, but as imaginary part 0.

This is a precise operation for numbers in Polar form, but a lossy operation for numbers in Cartesian form.

add(ca, cb)

Adds two ComplexNums together. If both are Cartesian, this is a precise operation.

If one or both are Polar, this is a lossy operation, as they are first converted to Cartesian.

angle(complex)

Returns the angle of the complex number.

This is a precise operation for numbers in Polar form, but a lossy operation for numbers in Cartesian form.

coerce(ca, num)
div(ca, cb)

Divides ca by cb. This is a precise operation for numbers in both Cartesian and Polar forms.

magnitude(complex)

Returns the magnitude of the Complex Number.

This is a precise operation for numbers in Polar form, but a lossy operation for numbers in Cartesian form.

If you only need to e.g. sort on magnitudes, consider magnitude_squared/2 instead, which is also precise for numbers in Cartesian form.

magnitude_squared(complex)

The squared magnitude of the Complex Number.

This is a precise operation for both Cartesian and Polar form.

minus(complex)

The negation of a Complex Number: Both the real and imaginary parts are negated.

This is a precise operation for numbers in Cartesian form, but a lossy operation for numbers in Polar form.

mult(ca, cb)

Multiplies ca by cb. This is a precise operation for numbers in both Cartesian and Polar forms.

new(real, imaginary \\ 0, make_polar \\ :cartesian)
pow(base, exponent)

Power function: computes base^exponent, where base is a Complex Number, and exponent has to be an integer.

This means that it is impossible to calculate roots by using this function.

pow is fast (constant time) for numbers in Polar form. For numbers in Cartesian form, the Exponentiation by Squaring algorithm is used, which performs log n multiplications.

sub(ca, cb)

Subtracts one ComplexNum from another. If both are Cartesian, this is a precise operation.

If one or both are Polar, this is a lossy operation, as they are first converted to Cartesian.

to_cartesian(ca)

Converts a Complex Number to Cartesian Form.

This is a lossy operation (unless the number already is in Cartesian form).

to_polar(pa)

Converts a Complex Number to Polar Form.

This is a lossy operation (unless the number already is in Polar form).