imag — Extract the imaginary component of scalars, vectors, matrices, or N-D tensors.

imag(x) returns the imaginary component of every element in x. Complex inputs yield their imaginary part, while real inputs produce zero-valued results of matching shape.

How imag works in RunMat

• 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 (imag expects numeric, logical, or character data).
• Sparse arrays are currently densified; native sparse support is planned.

How imag runs 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 = 4

Retrieving imaginary components of a complex matrix

Z = [1+2i 4-3i; -5+0i 7+8i];
Y = imag(Z)

Expected output:

Y =
     2    -3
     0     8

Verifying 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     0

Working with GPU-resident tensors

G = rand(2048, 256, "gpuArray");
res = imag(G)

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 functions to explore

These functions work well alongside imag. Each page has runnable examples you can try in the browser.

real, abs, sign, gpuArray, gather, angle, conj, double, exp, expm1, factorial, gamma, hypot, ldivide, log, log10, log1p, log2, minus, plus, pow2, power, rdivide, single, sqrt, times

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how imag works, line by line, in Rust.

• View imag.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing