RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

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 does the imag function behave in MATLAB / 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.

GPU behavior

**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 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 of using imag in MATLAB / RunMat

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.

See also

real, abs, sign, gpuArray, gather

Source & Feedback