What does the isreal function do in MATLAB / RunMat?
tf = isreal(x) returns a logical scalar that is true when the value x is stored without an imaginary component, and false otherwise. It mirrors MATLAB's storage-centric definition: any complex storage (even with zero-valued imaginary parts) is reported as not real.
How does the isreal function behave in MATLAB / RunMat?
- 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.
Examples of using the isreal function in MATLAB / RunMat
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 =
1
Detecting complex entries inside an array
B = [1 3+4i 2; 2i 1 12];
tf = isreal(B);
Expected output:
tf =
0
Complex 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 =
0
Logical 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 =
1
Strings, 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 =
0
Querying gpuArray storage without gathering data
G = gpuArray(rand(1024, 1024));
tf_gpu = isreal(G);
Expected output:
tf_gpu =
1
isreal Function GPU Execution Behaviour
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 residency in RunMat (Do I need gpuArray?)
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.
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.