# Complex-Valued Basic Functions

This chapter describes built-in functions that operate on complex numbers, either as an argument type or a return type. This includes the arithmetic operators generalized to complex numbers.

## Complex assignment and promotion

Just as integers may be assigned to real variables, real variables may be assigned to complex numbers, with the result being a zero imaginary component.

```
int n = 5; // n = 5
real x = a; // x = 5.0
complex z1 = n; // z = 5.0 + 0.0i
complex z2 = x; // z = 5.0 + 0.0i
```

### Complex function arguments

Function arguments of type `int`

or `real`

may be promoted to type `complex`

. The complex version of functions in this chapter are only used if one of the arguments is complex. For example, if `z`

is complex, then `pow(z, 2)`

will call the complex version of the power function and the integer 2 will be promoted to a complex number with a real component of 2 and an imaginary component of 0. The same goes for binary operators like addition and subtraction, where `z + 2`

will be legal and produce a complex result. Functions such as `arg`

and `conj`

that are only available for complex numbers can accept integer or real arguments, promoting them to `complex`

before applying the function.

## Complex constructors and accessors

### Complex constructors

Variables and constants of type `complex`

are constructed from zero, one, or two real numbers.

```
complex z1 = to_complex(); // z1 = 0.0 + 0.0i
real re = -2.9;
complex z2 = to_complex(re); // z2 = -2.9 + 0.0i
real im = 1.3;
complex z3 = to_complex(re, im); // z3 = -2.9 + 1.3i
```

`complex`

`to_complex`

`()`

Return complex number with real part 0.0 and imaginary part 0.0.

*Available since 2.28*

`complex`

`to_complex`

`(real re)`

Return complex number with real part `re`

and imaginary part 0.0.

*Available since 2.28*

`complex`

`to_complex`

`(real re, real im)`

Return complex number with real part `re`

and imaginary part `im`

.

*Available since 2.28*

`Z`

`to_complex`

`(T1 re, T2 im)`

Vectorized implementation of the `to_complex`

function.

`T1`

and `T2`

can either be real containers of the same size, or a real container and a real, in which case the real value is used for the corresponding component in all elements of the output.

*Available since 2.30*

### Complex accessors

Given a complex number, its real and imaginary parts can be extracted with the following functions.

`real`

`get_real`

`(complex z)`

Return the real part of the complex number `z`

.

*Available since 2.28*

`real`

`get_imag`

`(complex z)`

Return the imaginary part of the complex number `z`

.

*Available since 2.28*

## Complex arithmetic operators

The arithmetic operators have the same precedence for complex and real arguments. The complex form of an operator will be selected if at least one of its argument is of type `complex`

. If there are two arguments and only one is of type `complex`

, then the other will be promoted to type `complex`

before performing the operation.

### Unary operators

`complex`

`operator+`

`(complex z)`

Return the complex argument `z`

, \[\begin{equation*} +z = z. \end{equation*}\]

*Available since 2.28*

`complex`

`operator-`

`(complex z)`

Return the negation of the complex argument `z`

, which for \(z = x + yi\) is \[\begin{equation*} -z = -x - yi. \end{equation*}\]

*Available since 2.28*

`T`

`operator-`

`(T x)`

Vectorized version of `operator-`

. If `T x`

is a (possibly nested) array of complex numbers, `-x`

is the same shape array where each individual value is negated.

*Available since 2.31*

### Binary operators

`complex`

`operator+`

`(complex x, complex y)`

Return the sum of x and y, \[\begin{equation*} (x + y) = \text{operator+}(x, y) = x + y. \end{equation*}\]

*Available since 2.28*

`complex`

`operator-`

`(complex x, complex y)`

Return the difference between x and y, \[\begin{equation*} (x - y) =
\text{operator-}(x, y) = x - y. \end{equation*}\]

*Available since 2.28*

`complex`

`operator*`

`(complex x, complex y)`

Return the product of x and y, \[\begin{equation*} (x \, * \, y) = \text{operator*}(x, y) = x
\times y. \end{equation*}\]

*Available since 2.28*

`complex`

`operator/`

`(complex x, complex y)`

Return the quotient of x and y, \[\begin{equation*} (x / y) = \text{operator/}(x,y) =
\frac{x}{y} \end{equation*}\]

*Available since 2.28*

`complex`

`operator^`

`(complex x, complex y)`

Return x raised to the power of y, \[\begin{equation*}
(x^\mathrm{\wedge}y)= \text{operator}^\mathrm{\wedge}(x,y)
= \textrm{exp}(y \, \log(x)).
\end{equation*}\]

*Available since 2.28*

## Complex comparison operators

Complex numbers are equal if and only if both their real and imaginary components are equal. That is, the conditional

` z1 == z2`

is equivalent to

` get_real(z1) == get_real(z2) && get_imag(z1) == get_imag(z2)`

As with other complex functions, if one of the arguments is of type `real`

or `int`

, it will be promoted to type `complex`

before comparison. For example, if `z`

is of type `complex`

, then `z == 0`

will be true if `z`

has real component equal to 0.0 and complex component equal to 0.0.

*Warning:* As with real values, it is usually a mistake to compare complex numbers for equality because their parts are implemented using floating-point arithmetic, which suffers from precision errors, rendering algebraically equivalent expressions not equal after evaluation.

`int`

`operator==`

`(complex x, complex y)`

Return 1 if x is equal to y and 0 otherwise, \[\begin{equation*}
(x \,\text{==}\, y)
\ = \ \text{operator==}(x,y)
\ = \ \begin{cases} 1 & \text{if $x = y$}, \ \text{and} \\ 0 & \text{otherwise.}
\end{cases}
\end{equation*}\]

*Available since 2.28*

`int`

`operator!=`

`(complex x, complex y)`

Return 1 if x is not equal to y and 0 otherwise, \[\begin{equation*}
(x \,\text{!=}\, y)
\ = \ \text{operator!=}(x,y)
\ = \ \begin{cases} 1 & \text{if $x \neq y$}, \ \text{and} \\ 0 &
\text{otherwise.} \end{cases}
\end{equation*}\]

*Available since 2.28*

## Complex (compound) assignment operators

The assignment operator only serves as a component in the assignment statement and is thus not technically a function in the Stan language. With that caveat, it is documented here for completeness.

Assignment of complex numbers works elementwise. If an expression of type `int`

or `real`

is assigned to a complex number, it will be promoted before assignment as if calling `to_complex()`

, so that the imaginary component is 0.0.

`void`

`operator=`

`(complex x, complex y)`

`y = x;`

assigns a (copy of) the value of `y`

to `x`

.

*Available since 2.28*

`void`

`operator+=`

`(complex x, complex y)`

`x += y;`

is equivalent to `x = x + y;`

.

*Available since 2.28*

`void`

`operator-=`

`(complex x, complex y)`

`x -= y;`

is equivalent to `x = x - y;`

.

*Available since 2.28*

`void`

`operator*=`

`(complex x, complex y)`

`x *= y;`

is equivalent to `x = x * y;`

.

*Available since 2.28*

`void`

`operator/=`

`(complex x, complex y)`

`x /= y;`

is equivalent to `x = x / y;`

.

*Available since 2.28*

## Complex special functions

The following functions are specific to complex numbers other than absolute value, which has a specific meaning for complex numbers.

`real`

`abs`

`(complex z)`

Return the absolute value of z, also known as the modulus or magnitude, which for \(z = x + yi\) is \[\begin{equation*}
\textrm{abs}(z) = \sqrt{x^2 + y^2}.
\end{equation*}\]

This function works elementwise over containers, returning the same shape and kind of the input container but holding reals. For example, a `complex_vector[n]`

input will return a `vector[n]`

output, with each element transformed by the above equation.

*Available since 2.28, vectorized in 2.30*

`real`

`arg`

`(complex z)`

Return the phase angle (in radians) of z, which for \(z = x + yi\) is \[\begin{equation*}
\textrm{arg}(z) = \textrm{atan2}(y, x) = \textrm{atan}(y / x).
\end{equation*}\]

*Available since 2.28*

`real`

`norm`

`(complex z)`

Return the Euclidean norm of z, which is its absolute value squared, and which for \(z = x + yi\) is \[\begin{equation*}
\textrm{norm}(z) = \textrm{abs}^2(z) = x^2 + y^2.
\end{equation*}\]

*Available since 2.28*

`complex`

`conj`

`(complex z)`

Return the complex conjugate of z, which negates the imaginary component, so that if \(z = x + yi\), \[\begin{equation*}
\textrm{conj}(z) = x - yi.
\end{equation*}\]

*Available since 2.28*

`Z`

`conj`

`(Z z)`

Vectorized version of `conj`

. This will apply the `conj`

function to each element of a complex array, vector, or matrix.

*Available since 2.31*

`complex`

`proj`

`(complex z)`

Return the projection of `z`

onto the Riemann sphere, which for \(z = x
+ yi\) is \[\begin{equation*}
\textrm{proj}(z)
= \begin{cases}
z & \textrm{if} \ z \ \textrm{is finite, and} \\
0 + \textrm{sign}(y)i & \textrm{otherwise,}
\end{cases}
\end{equation*}\] where \(\textrm{sign}(y)\) is -1 if \(y\) is negative and 1 otherwise.

*Available since 2.28*

`complex`

`polar`

`(real r, real theta)`

Return the complex number with magnitude (absolute value) `r`

and phase angle `theta`

.

*Available since 2.28*

## Complex exponential and power functions

The exponential, log, and power functions may be supplied with complex arguments with specialized meanings that generalize their real counterparts. These versions are only called when the argument is complex.

`complex`

`exp`

`(complex z)`

Return the complex natural exponential of `z`

, which for \(z = x + yi\) is \[\begin{equation*}
\exp z = \exp(x) \textrm{cis}(y) = \exp(x) (\cos(y) + i \sin(y)).
\end{equation*}\]

*Available since 2.28*

`complex`

`log`

`(complex z)`

Return the complex natural logarithm of `z`

, which for \(z = \textrm{polar}(r,
\theta)\) is \[\begin{equation*}
\log z = \log r + \theta i.
\end{equation*}\]

*Available since 2.28*

`complex`

`log10`

`(complex z)`

Return the complex common logarithm of `z`

, \[\begin{equation*}
\log_{10} z = \frac{\log z}{\log 10}.
\end{equation*}\]

*Available since 2.28*

`complex`

`pow`

`(complex x, complex y)`

Return x raised to the power of y, \[\begin{equation*}
\text{pow}(x,y) = \textrm{exp}(y \, \log(x)).
\end{equation*}\]

*Available since 2.28*

`Z`

`pow`

`(T1 x, T2 y)`

Vectorized implementation of the `pow`

function

*Available since 2.30*

`complex`

`sqrt`

`(complex x)`

Return the complex square root of x with branch cut along the negative real axis. For finite inputs, the result will be in the right half-plane.

*Available since 2.28*

## Complex trigonometric functions

The standard trigonometric functions are supported for complex numbers.

`complex`

`cos`

`(complex z)`

Return the complex cosine of z, which is \[\begin{equation*}
\cos(z)
= \textrm{cosh}(z \, i)
= \frac{\displaystyle \exp(z \, i) + \exp(-z \, i)}
{\displaystyle 2}.
\end{equation*}\]

*Available since 2.28*

`complex`

`sin`

`(complex z)`

Return the complex sine of z, \[\begin{equation*}
\sin(z)
= -\textrm{sinh}(z \, i) \, i
= \frac{\displaystyle \exp(z \, i) - \exp(-z \, i)}
{\displaystyle 2 \, i}.
\end{equation*}\]

*Available since 2.28*

`complex`

`tan`

`(complex z)`

Return the complex tangent of z, \[\begin{equation*}
\tan(z)
= -\textrm{tanh}(z \, i) \, i
= \frac{(\exp(-z \, i) - \exp(z \, i)) \, i}
{\exp(-z \, i) + \exp(z \, i)}.
\end{equation*}\]

*Available since 2.28*

`complex`

`acos`

`(complex z)`

Return the complex arc (inverse) cosine of z, \[\begin{equation*}
\textrm{acos}(z)
= \frac{1}{2} \pi + \log (z \, i + \sqrt{1 - z^2}) \, i.
\end{equation*}\]

*Available since 2.28*

`complex`

`asin`

`(complex z)`

Return the complex arc (inverse) sine of z, \[\begin{equation*}
\text{asin}(z)
= -\log(z \, i + \sqrt{1 - z^2}) \, i.
\end{equation*}\]

*Available since 2.28*

`complex`

`atan`

`(complex z)`

Return the complex arc (inverse) tangent of z, \[\begin{equation*}
\text{atan}(z)
= - \frac{1}{2} (\log(1 - z \, i) - \log(1 + z \, i)) \, i.
\end{equation*}\]

*Available since 2.28*

## Complex hyperbolic trigonometric functions

The standard hyperbolic trigonometric functions are supported for complex numbers.

`complex`

`cosh`

`(complex z)`

Return the complex hyperbolic cosine of z, \[\begin{equation*}
\textrm{cosh}(z)
= \frac{\exp(z) + \exp(-z)}
{2}.
\end{equation*}\]

*Available since 2.28*

`complex`

`sinh`

`(complex z)`

Return the complex hyperbolic sine of z, \[\begin{equation*}
\textrm{sinh}(z)
= \frac{\displaystyle \exp(z) - \exp(-z)}
{\displaystyle 2}.
\end{equation*}\]

*Available since 2.28*

`complex`

`tanh`

`(complex z)`

Return the complex hyperbolic tangent of z, \[\begin{equation*}
\textrm{tanh}(z)
\ = \ \frac{\textrm{sinh}(z)}
{\textrm{cosh}(z)}
\ = \ \frac{\displaystyle \exp(z) - \exp(-z)}
{\displaystyle \exp(z) + \exp(-z)}.
\end{equation*}\]

*Available since 2.28*

`complex`

`acosh`

`(complex z)`

Return the complex hyperbolic arc (inverse) cosine of z, \[\begin{equation*}
\textrm{acosh}(z)
= \log(z + \sqrt{(z + 1)(z - 1)}).
\end{equation*}\]

*Available since 2.28*

`complex`

`asinh`

`(complex z)`

Return the complex hyperbolic arc (inverse) sine of z, \[\begin{equation*}
\textrm{asinh}(z)
= \log(z + \sqrt{1 + z^2}).
\end{equation*}\]

*Available since 2.28*

`complex`

`atanh`

`(complex z)`

Return the complex hyperbolic arc (inverse) tangent of z, \[\begin{equation*}
\textrm{atanh}(z)
= \frac{\log(1 + z) - \log(1 - z)}
{2}.
\end{equation*}\]

*Available since 2.28*