@wollybeard/kit

Appearance

Num.Complex ​

Num / Complex

Import ​

typescript
import { Num } from '@wollybeard/kit'

// Access via namespace
Num.Complex.someFunction()
typescript
import * as Num from '@wollybeard/kit/num'

// Access via namespace
Num.Complex.someFunction()

Functions ​

[F] is ​

typescript
(value: unknown): boolean
Source

Parameters:

  • value - The value to check

Returns: True if value is a Complex number

Type predicate to check if value is a Complex number.

[F] from ​

typescript
(real: number, imaginary?: number = 0): Complex
Source

Parameters:

  • real - The real part
  • imaginary - The imaginary part (default: 0)

Returns: The complex number

Construct a Complex number from real and imaginary parts.

[F] real ​

typescript
(real: number): Complex
Source

Parameters:

  • real - The real value

Returns: Complex number with zero imaginary part

Create a real complex number (imaginary part = 0).

[F] imaginary ​

typescript
(imaginary: number): Complex
Source

Parameters:

  • imaginary - The imaginary value

Returns: Complex number with zero real part

Create a pure imaginary complex number (real part = 0).

[F] add ​

typescript
(a: Complex, b: Complex): Complex
Source

Parameters:

  • a - First complex number to add
  • b - Second complex number to add

Returns: A new complex number that is the sum of a and b

Add two complex numbers together.

When adding complex numbers, you add the real parts together and the imaginary parts together. Formula: (a + bi) + (c + di) = (a + c) + (b + d)i

[F] subtract ​

typescript
(a: Complex, b: Complex): Complex
Source

Parameters:

  • a - First complex number (minuend)
  • b - Second complex number (subtrahend)

Returns: The difference

Subtract two complex numbers. (a + bi)

  • (c + di) = (a
  • c) + (b
  • d)i

[F] multiply ​

typescript
(a: Complex, b: Complex): Complex
Source

Parameters:

  • a - First complex number
  • b - Second complex number

Returns: The product

Multiply two complex numbers. (a + bi)(c + di) = (ac

  • bd) + (ad + bc)i

[F] divide ​

typescript
(a: Complex, b: Complex): Complex
Source

Parameters:

  • a - First complex number (dividend)
  • b - Second complex number (divisor)

Returns: The quotient

Throws:

  • Error if divisor is zero

Divide two complex numbers. (a + bi) / (c + di) = [(a + bi)(c

  • di)] / (c² + d²)

[F] conjugate ​

typescript
(z: Complex): Complex
Source

Parameters:

  • z - The complex number

Returns: The complex conjugate with imaginary part sign flipped

Get the complex conjugate by flipping the sign of the imaginary part.

The complex conjugate is useful for:

  • Converting division into multiplication (z/w = z*w̄/|w|²)
  • Finding the magnitude squared (z*z̄ = |z|²)
  • Extracting real parts from complex expressions

If z = a + bi, then z* = a

  • bi

[F] abs ​

typescript
(z: Complex): number
Source

Parameters:

  • z - The complex number

Returns: The magnitude as a non-negative real number

Get the absolute value (magnitude/modulus) of a complex number.

The magnitude represents the distance from the origin to the point in the complex plane. This is always a non-negative real number, calculated using the Pythagorean theorem.

Formula: |a + bi| = √(a² + b²)

[F] arg ​

typescript
(z: Complex): number
Source

Parameters:

  • z - The complex number

Returns: The argument in radians, ranging from -π to π

Throws:

  • Error if z is zero (argument is undefined for zero)

Get the argument (phase/angle) of a complex number in radians.

The argument is the angle from the positive real axis to the line connecting the origin to the complex number, measured counterclockwise. This is essential for polar form representation and rotation operations.

Formula: arg(a + bi) = atan2(b, a)

[F] toPolar ​

typescript
(z: Complex): { magnitude: number; angle: number; }
Source

Parameters:

  • z - The complex number to convert

Returns: Object with magnitude (distance from origin) and angle (in radians)

Convert complex number to polar form (magnitude, angle).

Polar form represents a complex number as r*e^(iθ) where r is the magnitude and θ is the angle. This form is especially useful for multiplication and power operations, as it turns them into simple arithmetic on the components.

[F] fromPolar ​

typescript
(magnitude: number, angle: number): Complex
Source

Parameters:

  • magnitude - The magnitude (r) - distance from origin, must be non-negative
  • angle - The angle in radians (θ) - measured counterclockwise from positive real axis

Returns: Complex number r * e^(iθ) = r(cos θ + i sin θ)

Create complex number from polar form (magnitude, angle).

This converts from polar coordinates (r, θ) to rectangular coordinates (a, bi) using Euler's formula: r*e^(iθ) = r(cos θ + i sin θ)

[F] power ​

typescript
(z: Complex, n: number): Complex
Source

Parameters:

  • z - The complex base number
  • n - The real exponent (can be fractional for roots)

Returns: z raised to the power n

Raise a complex number to a real power using De Moivre's theorem.

This uses the polar form to compute powers efficiently: If z = r*e^(iθ), then z^n = r^n * e^(inθ) This avoids the complexity of repeated multiplication for integer powers.

[F] sqrt ​

typescript
(z: Complex): Complex
Source

Parameters:

  • z - The complex number to find the square root of

Returns: The principal square root

Get the square root of a complex number.

Returns the principal (primary) square root using the power function. The principal root is the one with argument in the range (-π/2, π/2]. Note that every non-zero complex number has exactly two square roots.

[F] exp ​

typescript
(z: Complex): Complex
Source

Parameters:

  • z - The complex exponent

Returns: e raised to the complex power z

Natural exponential function for complex numbers.

Uses Euler's formula: e^(a + bi) = e^a * (cos b + i sin b) This fundamental function connects exponentials with trigonometry and is essential for signal processing, quantum mechanics, and many areas of mathematics.

[F] log ​

typescript
(z: Complex): Complex
Source

Parameters:

  • z - The complex number (must be non-zero)

Returns: The principal natural logarithm

Throws:

  • Error if z is zero (logarithm undefined)

Natural logarithm for complex numbers.

Uses the formula: log(z) = log|z| + i*arg(z) This gives the principal branch of the complex logarithm. Note that complex logarithms are multi-valued; this returns the principal value.

[F] equals ​

typescript
(a: Complex, b: Complex, tolerance?: number = 1e-9): boolean
Source

Parameters:

  • a - First complex number
  • b - Second complex number
  • tolerance - Maximum allowed difference for each component (default: 1e-9)

Returns: True if both real and imaginary parts are within tolerance

Check if two complex numbers are equal within a tolerance.

Due to floating-point arithmetic limitations, exact equality is rarely achievable for computed complex numbers. This function allows for small differences that arise from numerical precision issues.

[F] toString ​

typescript
(z: Complex, precision?: number = 6): string
Source

Parameters:

  • z - The complex number to convert
  • precision - Number of decimal places to display (default: 6)

Returns: String representation in mathematical notation

Convert complex number to string representation.

Creates a human-readable string in standard mathematical notation (a + bi). Handles special cases like pure real numbers, pure imaginary numbers, and the imaginary unit to provide clean, readable output.

Constants ​

[C] fromWith ​

typescript
;((real: number) => (imaginary?: number | undefined) => Complex)
Source

Create a function that constructs complex numbers with a fixed real part. Useful for creating pure imaginary numbers or series.

[C] fromOn ​

typescript
;((imaginary?: number | undefined) => (real: number) => Complex)
Source

Create a function that constructs complex numbers with a fixed imaginary part. Useful for creating real numbers or series with constant imaginary component.

[C] I ​

typescript
Complex
Source

The imaginary unit i (0 + 1i). Satisfies i² = -1.

[C] ZERO ​

typescript
Complex
Source

Zero complex number (0 + 0i).

[C] ONE ​

typescript
Complex
Source

One complex number (1 + 0i).

[C] addOn ​

typescript
;((a: Complex) => (b: Complex) => Complex)
Source

Create a function that adds its input to a specific complex number.

This is the data-first curried version where the input becomes the first parameter. Useful for operations where you want to add various numbers to a fixed base value.

[C] addWith ​

typescript
;((b: Complex) => (a: Complex) => Complex)
Source

Create a function that adds a specific complex number to other complex numbers.

This is the data-second curried version where the fixed value is added to various inputs. Useful when you want to add the same complex number to many different values.

[C] subtractWith ​

typescript
;((a: Complex) => (b: Complex) => Complex)
Source

Create a function that subtracts from a specific complex number.

[C] subtractOn ​

typescript
;((a: Complex) => (b: Complex) => Complex)
Source

Create a function that subtracts from a specific complex number.

This is the data-first curried version where the input becomes the subtrahend. Useful for operations where you want to subtract various numbers from a fixed value.

[C] multiplyOn ​

typescript
;((a: Complex) => (b: Complex) => Complex)
Source

Create a function that multiplies a specific complex number by others.

This is the data-first curried version where the input becomes the second factor. Useful for operations where you want to multiply a fixed base by various values.

[C] multiplyWith ​

typescript
;((b: Complex) => (a: Complex) => Complex)
Source

Create a function that multiplies with a specific complex number.

This is the data-second curried version where the fixed multiplier is applied to various inputs. Useful when you want to scale or rotate many complex numbers by the same amount. In 2D graphics, multiplying by a complex number rotates and scales points around the origin.

[C] divideWith ​

typescript
;((a: Complex) => (b: Complex) => Complex)
Source

Create a function that divides from a specific complex number.

This creates a function where the provided complex number is the dividend (numerator) and the function's input becomes the divisor (denominator).

[C] divideOn ​

typescript
;((a: Complex) => (b: Complex) => Complex)
Source

Create a function that divides a specific complex number by others.

This is the data-first curried version where the input becomes the divisor. Useful for operations where you want to divide a fixed dividend by various values.

[C] powerOn ​

typescript
;((z: Complex) => (n: number) => Complex)
Source

Create a function that raises a specific complex number to various powers.

This is the data-first curried version where the input becomes the exponent. Useful for operations where you want to raise a fixed base to different powers.

[C] powerWith ​

typescript
;((n: number) => (z: Complex) => Complex)
Source

Create a function that raises complex numbers to a specific power.

This is the data-second curried version where the fixed exponent is applied to various bases. Useful for applying the same power operation to multiple complex numbers, such as when processing arrays or in mathematical transformations.

[C] equalsOn ​

typescript
;((a: Complex) => (b: Complex) => (tolerance?: number | undefined) => boolean)
Source

Create a function that checks if its input equals a specific complex number.

This is the data-first curried version where the reference value is the first parameter. Useful for checking if various numbers equal a fixed reference value.

[C] equalsWith ​

typescript
;((b: Complex) => (a: Complex) => (tolerance?: number | undefined) => boolean)
Source

Create a function that checks equality with a specific complex number.

This is the data-second curried version where the comparison value is fixed. Useful for filtering, validation, or when you need to check many numbers against the same reference value.

Types ​

[∩] Complex ​

typescript
type Complex = {
  readonly real: number
  readonly imaginary: number
} & { [ComplexBrand]: true }
Source

Complex number

  • a number with both real and imaginary parts, written as a + bi.

The 'i' represents the imaginary unit, which is the square root of -1. Complex numbers extend regular numbers to solve problems that regular numbers can't, like finding the square root of negative numbers.

Common uses:

  • Signal processing: Analyzing sound waves and digital signals
  • Electrical engineering: Calculating power in AC circuits
  • Physics: Describing quantum states and wave behavior
  • Computer graphics: Rotating points and creating fractals
  • Control systems: Analyzing system stability