isreal — Test real-valued storage in MATLAB and RunMat.
tf = isreal(x) returns true when x uses real storage without an imaginary component. Complex-storage behavior follows MATLAB semantics.
Syntax
tf = isreal(A)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input value to test. |
Returns
| Name | Type | Description |
|---|---|---|
tf | LogicalArray | True when input uses real storage without imaginary components. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:isreal:InternalError | Internal gather/dispatch path fails. | isreal: internal error |
How isreal works
- Real numeric scalars and dense tensors return
true. - Logical arrays,
duration,calendarDuration, and character arrays always returntrue. - Complex scalars and
ComplexTensorvalues returnfalse, even when every imaginary component equals zero, because the data uses complex storage. string,table,cell,struct,datetime,function_handle, and object values always returnfalse, matching MATLAB's documented rules.- The return value is always a logical scalar;
isrealdoes not produce per-element masks.
Does RunMat run isreal on the GPU?
When RunMat Accelerate is active, the runtime asks the registered provider for the logical_isreal hook. A provider can answer the query using device metadata without downloading the tensor. If the hook is unavailable, RunMat gathers the value once and performs the storage check on the host, so the builtin always returns a result.
GPU memory and residency
Normally you do not need to call gpuArray explicitly. RunMat's auto-offload planner tracks when tensors already reside on the GPU and keeps them there. isreal simply inspects storage metadata and returns a host logical scalar, gathering device data only as a fallback.
Examples
Checking if a real-valued matrix is stored as real
A = [7 3 2; 2 1 12; 52 108 78];
tf = isreal(A)Expected output:
tf =
1Detecting complex entries inside an array
B = [1 3+4i 2; 2i 1 12];
tf = isreal(B)Expected output:
tf =
0Complex storage with zero-valued imaginary parts still reports false
C = complex(12); % Stored as complex double with 0 imaginary part
tf = isreal(C)Expected output:
tf =
0Logical and character data are considered real
mask = logical([1 0 1]);
chars = ['R' 'u' 'n'];
tf_mask = isreal(mask);
tf_chars = isreal(chars)Expected output:
tf_mask =
1
tf_chars =
1Strings, cells, and structs are never real
txt = "RunMat";
vec = {1, 2};
person = struct("name", "Ada");
tf_txt = isreal(txt);
tf_vec = isreal(vec);
tf_person = isreal(person)Expected output:
tf_txt =
0
tf_vec =
0
tf_person =
0Querying gpuArray storage without gathering data
G = gpuArray(rand(1024, 1024));
tf_gpu = isreal(G)Expected output:
tf_gpu =
1Using isreal with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how isreal changes the result.
Run a small isreal example, explain the result, then change one input and compare the output.
FAQ
Does isreal inspect each element of the array?⌄
No. It is a storage-level predicate. Use imag(A) == 0 or A == real(A) if you need per-element checks.
Why does isreal return false for complex(5) or 1 + 0i?⌄
Those expressions allocate complex storage even though the imaginary part is zero. MATLAB and RunMat both treat that storage as complex, so isreal returns false.
What about logical arrays, durations, or character data?⌄
They always return true because those types never allocate an imaginary component.
Why do strings, cells, structs, or objects return false?⌄
MATLAB documents that isreal returns false for those container and object types. RunMat follows the same rules for compatibility.
Will isreal trigger GPU computation or kernel launches?⌄
No. It is a metadata query. Providers can answer it without dispatching kernels, and the runtime falls back to a single host download only when necessary.
How can I check whether each element is real on the GPU?⌄
Use elementwise predicates such as imag/real combined with comparison (imag(A) == 0) or express the logic with fused operations. isreal is intentionally scalar.
Related Logical functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how isreal is executed, line by line, in Rust.
- View the source for isreal 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.