imag — Extract imaginary components in MATLAB and RunMat.
imag(X) returns the imaginary component of each element in X. Real inputs produce zeros with matching shape, consistent with MATLAB semantics.
Syntax
Y = imag(X)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Numeric, logical, char, or complex input. |
Returns
| Name | Type | Description |
|---|---|---|
Y | NumericArray | Imaginary component of X. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:imag:InvalidInput | Input cannot be interpreted as numeric, logical, char, or complex data. | imag: invalid input |
RunMat:imag:Internal | Internal tensor conversion/allocation/provider interaction failed. | imag: internal error |
How imag works
- Complex scalars, vectors, matrices, and higher-dimensional tensors return only their imaginary components.
- Purely real inputs (double, single, logical) produce zeros of type double that match the input size.
- Character arrays are converted to double and therefore produce zero-filled numeric arrays of the same size.
- String arrays are unsupported and raise an error (
imagexpects numeric, logical, or character data). - Sparse arrays are currently densified; native sparse support is planned.
Does RunMat run imag on the GPU?
Hook available: The provider materialises a zero-filled tensor directly on the GPU without any host transfers.
Hook missing or unsupported dtype: RunMat gathers the tensor to host memory, applies the CPU semantics (including the conversions for logical and character inputs), and resumes execution. Downstream fusion can still re-upload the result when profitable.
Complex GPU tensors are currently gathered to the host because GPU-side complex storage is not yet available; providers can add fused support later without changing this builtin.
GPU memory and residency
You usually do not need to call gpuArray explicitly. RunMat's fusion planner and Accelerate layer track residency automatically, keeping tensors on the GPU whenever device execution is profitable. Explicit gpuArray / gather calls remain available for MATLAB compatibility or when you need deterministic residency control (for example, when integrating with custom CUDA or OpenCL kernels).
Examples
Extracting the imaginary part of a complex scalar
z = 3 + 4i;
b = imag(z)Expected output:
b = 4Retrieving imaginary components of a complex matrix
Z = [1+2i 4-3i; -5+0i 7+8i];
Y = imag(Z)Expected output:
Y =
2 -3
0 8Verifying that real inputs yield zero
data = [-2.5 0 9.75];
values = imag(data)Expected output:
values = [0 0 0]Imaginary part of logical masks
mask = logical([0 1 0; 1 0 1]);
zerosOnly = imag(mask)Expected output:
zerosOnly =
0 0 0
0 0 0Working with GPU-resident tensors
G = rand(2048, 256, "gpuArray");
res = imag(G)Using imag with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how imag changes the result.
Run a small imag example, explain the result, then change one input and compare the output.
FAQ
Does imag modify purely real inputs?⌄
No. Purely real, logical, and character inputs become zero-valued doubles of the same size.
How does imag handle complex zeros?⌄
imag(0 + 0i) returns exactly 0. Imaginary zeros are preserved.
Can I call imag on string arrays?⌄
No. Like MATLAB, imag only accepts numeric, logical, or character arrays. Convert strings with double(string) first if you require numeric codes.
Does imag allocate a new array?⌄
Yes, in line with MATLAB semantics. Fusion may eliminate the allocation when the surrounding expression can be fused safely.
What happens on the GPU without unary_imag?⌄
RunMat gathers the tensor to host memory, applies the CPU semantics (producing zeros or extracting complex components), and allows subsequent operations to re-upload the data if doing so is worthwhile.
Is GPU execution numerically identical to CPU?⌄
Yes. For real tensors the result is exactly zero; for complex tensors the CPU path matches MATLAB's behaviour.
Does imag participate in fusion?⌄
Yes. The fusion planner can fold imag into neighbouring elementwise kernels, letting providers keep tensors on the GPU whenever possible.
Related Math functions
Elementwise
abs · angle · complex · conj · double · exp · expm1 · factorial · gamma · hypot · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · sign · single · sqrt · times
Trigonometry
acos · acosh · asin · asinh · atan · atan2 · atanh · cos · cosd · cosh · deg2rad · rad2deg · sin · sind · sinh · tan · tand · tanh
Reduction
all · any · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · mean · median · min · nnz · prod · std · sum · trapz · var
Structure
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how imag is executed, line by line, in Rust.
- View the source for imag 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.