RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

What does the imag function do in MATLAB / RunMat?

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.

imag Function GPU Execution Behaviour

When RunMat Accelerate is active, tensors that already reside on the GPU stay on the device. The runtime checks whether the active provider implements the unary_imag hook:

  • 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.

Examples of using the imag function 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);

When the provider implements unary_imag, res stays on the GPU. Otherwise RunMat transparently gathers the data, computes the result on the host, and continues execution.

GPU residency in RunMat (Do I need gpuArray?)

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).

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