RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

What does the real function do in MATLAB / RunMat?

real(x) returns the real component of each element in x. Real inputs are passed through unchanged, while complex inputs discard their imaginary component.

How does the real function behave in MATLAB / RunMat?

  • Complex scalars, vectors, matrices, and higher-dimensional tensors return only their real parts.
  • Real inputs (double, single, logical) are preserved exactly, but results are materialised as double precision when necessary (e.g., logical masks become doubles).
  • Character arrays are converted to their numeric code points and returned as doubles, matching MATLAB semantics.
  • String arrays are not supported and raise an error (real expects numeric, logical, or character data).
  • Sparse arrays are currently densified (sparse support is planned).

real 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_real hook:

  • Hook available: The real part is taken directly on the device with no host transfers (the WGPU provider and the in-process provider both implement this hook).
  • Hook missing or unsupported dtype: RunMat gathers the tensor to host memory, applies the CPU semantics (including logical and character promotion), and hands control back to the caller. Downstream fusion can still re-upload if the planner decides it is profitable.

Complex GPU tensors are currently gathered because device-side complex storage is not yet available; providers can add fused support later without changing this builtin.

Examples of using the real function in MATLAB / RunMat

Extract the real part of a complex scalar

z = 3 + 4i;
r = real(z);

Expected output:

r = 3;

Take the real part of a complex matrix

Z = [1+2i, 4-3i; -5+0i, 7+8i];
R = real(Z);

Expected output:

R =
     1     4
    -5     7

Confirm that real inputs remain unchanged

data = [-2.5 0 9.75];
result = real(data);

Expected output:

result = [-2.5 0 9.75];

Convert logical masks to doubles

mask = logical([0 1 0; 1 1 0]);
numeric = real(mask);

Expected output:

numeric =
     0     1     0
     1     1     0

Convert characters to numeric codes

chars = 'RunMat';
codes = real(chars);

Expected output:

codes = [82 117 110 77 97 116];

Keep GPU tensors device-resident when possible

G = rand(4096, 512, "gpuArray");
R = real(G);

R stays on the GPU when the provider implements unary_real; otherwise RunMat transparently gathers to the host, applies the CPU path, 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 beneficial. Explicit gpuArray / gather calls remain available for MATLAB compatibility or when you need deterministic residency control (e.g., integrating with third-party GPU kernels).

FAQ

Does real change purely real inputs?

No. Real, logical, and character inputs are preserved numerically, though logical and character values are returned as doubles to match MATLAB.

How does real handle complex zeros?

real(0 + 0i) returns exactly 0. Imaginary zeros are simply discarded.

Can I call real on string arrays?

No. Like MATLAB, real only accepts numeric, logical, or character arrays. Converting strings with double(string) first will produce numeric codes if required.

Does real allocate a new array?

Yes. The builtin returns a new tensor (or scalar). Fusion may combine kernels to avoid materialising intermediates when safe.

What happens on the GPU without unary_real?

RunMat gathers the tensor to host memory, applies the CPU semantics, and allows subsequent operations to re-upload if profitable. Providers are encouraged to implement unary_real for zero-copy behaviour.

Is GPU execution numerically identical to CPU?

Yes—real is an identity for real tensors. Results match within the provider's precision (single or double).

Does real participate in fusion?

Yes. The fusion planner can fold real into neighbouring elementwise kernels, keeping data on the GPU when possible.

See Also

imag, abs, sign, gpuArray, gather

Source & Feedback