complex — Construct complex values from real and imaginary parts in MATLAB and RunMat.
z = complex(a, b) constructs a + 1i*b from real-valued inputs. z = complex(a) lifts real values into complex storage with zero imaginary part, following MATLAB semantics.
Syntax
Z = complex(A)
Z = complex(A, B)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Real numeric input to lift into complex storage. |
A | Any | Yes | — | Real part operand. |
B | Any | Yes | — | Imaginary part operand. |
Returns
| Name | Type | Description |
|---|---|---|
Z | NumericArray | Complex result. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:complex:InvalidArgument | Argument arity is invalid. | complex: invalid argument |
RunMat:complex:InvalidInput | Input value cannot be converted into real numeric tensor inputs. | complex: invalid input |
RunMat:complex:SizeMismatch | Real and imaginary parts are not compatible for scalar expansion. | complex: size mismatch |
RunMat:complex:Internal | Internal complex tensor construction failed. | complex: internal error |
RunMat:complex:IntegerClass | An integer input is paired with an unsupported unlike input class. | complex: integer inputs require matching integer classes or a scalar double |
How complex works
- With two inputs,
aandbmust be real numeric values. Complex inputs raise an error. - Two non-scalar inputs must have the same size. If either input is scalar, it expands across the other input.
- Integer inputs retain their integer class in exact complex integer storage. In the binary form, the peer must have the same integer class or be a full scalar double, and scalar-double conversion rounds and saturates to the integer class.
- If either floating input is single, the result is complex single; logical-only inputs produce complex double.
- String and character inputs are rejected because the constructor accepts numeric inputs only.
- Unary
complex(a)preserves existing complex scalars and complex tensors. Real inputs become complex values with zero imaginary parts. - Empty real tensors preserve their empty shape and return empty complex tensors.
- Real floating gpuArray inputs remain device-resident when the owning provider supports complex construction; typed-integer resident inputs preserve exact paired storage and return to the owning provider after exact fallback composition.
Does RunMat run complex on the GPU?
Unary complex(A) on a floating real gpuArray writes [real, 0] interleaved lanes when the owning-provider hook is available.
Binary complex(A, B) uses the owning-provider hook only when class and precision rules can be preserved; typed integers use exact native fallback and restore resident output to the selected owner.
If either two-argument operand is already complex, RunMat raises the same real-input error as the host path.
GPU memory and residency
complex keeps floating real gpuArray inputs resident when the owning provider supports the required precision and complex-construction hook. Typed-integer input uses exact owner-aware fallback and restores paired native storage to that owner.
Examples
Constructing a complex scalar from real and imaginary parts
z = complex(3, 4)Expected output:
z = 3+4iConstructing a complex row vector from matching real arrays
re = [1 2 3];
im = [4 5 6];
z = complex(re, im)Expected output:
z = [1+4i 2+5i 3+6i]Expanding a scalar imaginary part across an array
re = [1 2 3];
z = complex(re, -1)Expected output:
z = [1-1i 2-1i 3-1i]Forcing complex storage with a zero imaginary part
z = complex(12);
tf = isreal(z)Expected output:
z = 12+0i
tf =
0Leaving an existing complex value unchanged
z = complex(1 + 2i)Expected output:
z = 1+2iRejecting non-scalar implicit expansion
z = complex([1 2 3], [10; 20])Expected output:
error: complex: real and imaginary parts must have the same size, unless one input is scalarUsing complex with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how complex changes the result.
Run a small complex example, explain the result, then change one input and compare the output.
FAQ
Does complex(a, b) use MATLAB implicit expansion?⌄
Only scalar expansion is supported for this constructor. Two non-scalar operands must have identical sizes, matching MATLAB's documented complex size rules.
Can I pass complex values to complex(a, b)?⌄
No. The two-argument constructor requires real numeric inputs for both the real and imaginary parts. Use real, imag, or arithmetic if you need to transform existing complex values.
What does unary complex(a) do?⌄
It forces real input into complex storage with a zero imaginary part. If a is already complex, RunMat returns it unchanged.
Why does isreal(complex(5)) return false?⌄
complex(5) stores the value as complex double data with an explicit zero imaginary part. MATLAB and RunMat define isreal by storage, so it returns false.
Does complex accept logical inputs?⌄
Yes. Logical values produce complex double output. Integer values are different: all eight integer classes are documented inputs and retain their class in exact complex integer storage.
Does complex accept strings or character arrays?⌄
No. Strings and character arrays are rejected because the constructor is limited to numeric inputs.
Can complex run on GPU arrays?⌄
Floating real gpuArray inputs use owning-provider complex construction when precision and hooks support it. Typed-integer resident inputs use exact native transfer for fallback composition and restore paired complex-integer output to the same owner.
Related Math functions
Elementwise
abs · angle · bsxfun · conj · double · erf · erfcinv · exp · expm1 · factorial · flintmax · gamma · gammaln · heaviside · hypot · idivide · imag · intmax · intmin · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · swapbytes · times · typecast · uint16 · uint32 · uint8
Trigonometry
acos · acosh · asin · asinh · atan · atan2 · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
Reduction
all · any · bounds · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · maxk · mean · median · min · mink · movmax · movmean · movmedian · movmin · movprod · movstd · movsum · movvar · nnz · prod · rms · std · sum · trapz · var
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Signal
blackman · butter · buttord · cheb2ord · conv · conv2 · deconv · downsample · envelope · filter · filtfilt · fir1 · freqz · gauspuls · hamming · hann · hilbert · periodogram · pulstran · pwelch · rectpuls · resample · sawtooth · sinc · spectrogram · square · tripuls · unwrap · upsample · zplane
Optim
coneprog · fminbnd · fminunc · fsolve · fzero · integral · linprog · lsqcurvefit · lsqnonlin · optimoptions · optimset · quad · secondordercone
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how complex is executed, line by line, in Rust.
- View the source for complex in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.