Skip to content
TREB Docs

Complex Numbers

TREB supports complex numbers as an intrinsic type. You can use complex numbers anywhere you would use real numbers. You can type them in cells and use them as arguments to functions. See below for a list of functions that work with complex numbers.

Complex number support is very much a work in progress. If you have questions, comments, or feature requests, please let us know.

Parsing

When entering a complex number, you must use the token i (lower-case ASCII “i”, unicode U+0069) for the imaginary component. The token i on its own implies a value of 1i. The magnitude must precede the token, for example 3i or 1.2i.

When entering a formula, complex numbers are not automatically treated as atomic units. Normal precendence rules apply, so

=B3 * 2-3i

=B3 * 2-3i

is the equivalent of

=(B3 * 2) - 3i

=(B3 * 2) - 3i

You can of course use parentheses to group them explicitly.

=B3 * (2 - 3i)

=B3 * (2 - 3i)

Rendering and Formatting

When displaying complex numbers, TREB uses an italic character 𝑖 (mathematical italic small i, unicode U+1D456). We believe this character is available in the default fonts on all platforms we support. If necessary, you can change this character using a run-time option.

Generally speaking we try to render complex numbers in the simplest possible way.

If a complex value has no imaginary value (or if it would render as 0 in the current number format), when displaying the value we will omit the imaginary component. The same goes for the real component, if there is an imaginary component. So complex numbers may render as

  • 3.2
  • 2𝑖
  • 0.00

Number formatting is not well defined for complex numbers. At the moment, we use the currently selected number format and apply it to both the real and imaginary components.

We recommend that you use only basic number formats like “General” or “Number”. Fractional number formats also work well. Increasing or decreasing the decimal (or fractional) precision works as expected.

TREB only displays complex numbers in rectangular form, but you can use the Abs and Arg functions to get components for the polar form.

Import & Export

We don’t (for now) supporing importing or exporting complex numbers in XLSX files. The XLSX format doesn’t have a complex type. Excel has a number of functions that work with complex numbers, but the actual values they use are strings.

For the time being, we’re just punting on this issue, but we are open to suggestions.

Functions and Operators

The following functions and operators support complex numbers:

Unary operators

  • - (negation)

Binary operators

  • + (addition)
  • - (subtraction)
  • / (division)
  • * (multiplication)
  • ^ (exponentiation) (see note)

Equalities

  • = (equality)
  • <> (inequality)

Functions specifically written for complex numbers

  • ComplexLog - the complex Log function
  • Arg - returns the principal argument of a complex number
  • Real - returns the real component of a complex number
  • Imaginary - returns the coefficient of the imaginary component
  • Conjugate - returns the complex conjugate
  • Complex - treats real values as complex for function purposes (see note)

Functions updated to support complex arguments

  • Exp
  • Abs
  • Sum
  • MMult
  • MInverse
  • MDeterm
  • Power (see note)
  • Sqrt (see note)

 

Note

Most people aren’t expecting imaginary numbers to pop up in their spreadsheets. Typically, the function =SQRT(-1) would return an error (Not a Number, or #NaN). The same applies to the POWER function and the exponentiation operator ^.

We don’t want to change existing behavior (at least not right now), so we are leaving this as-is for real values. If the argument to SQRT is complex, e.g. SQRT(-1 + 0i) it will return the complex result 𝑖. If the argument is real, however, SQRT(-1) will return a #NaN error.

This presents a problem for values returned from functions which may be in either real or complex domain. To resolve this, and create a pattern for consistent behavior, we provide the function COMPLEX. This function coerces real values to the complex domain.

  • =SQRT(-1) returns NaN
  • =SQRT(-1 + 0i) returns 𝑖
  • =SQRT(COMPLEX(-1)) returns 𝑖

The function REAL can be used for the converse, i.e. ensuring a number is treated as real, although this may lose information if a number has an imaginary compnent.

If you don’t want to bother with that, you can enable complex results for all functions regardless of inputs, using the complex configuration option.