logical — Convert values to logical type in MATLAB and RunMat.
logical(X) converts supported real numeric and character inputs into logical values. Zero maps to false and nonzero maps to true. NaN and complex numeric inputs are rejected. When RunMat extensions are enabled, string arrays and symbolic numeric constants are additionally accepted.
Syntax
tf = logical(A)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input value to convert. |
Returns
| Name | Type | Description |
|---|---|---|
tf | LogicalArray | Logical-converted result. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:logical:TooManyInputs | More than one input argument is provided. | logical: too many input arguments |
RunMat:logical:ConversionNotPossible | Input type cannot be converted to logical. | logical: conversion to logical is not possible for this input type |
RunMat:logical:GpuGatherFailed | GPU input gather fails during host fallback. | logical: failed to gather gpuArray input |
RunMat:logical:InternalError | Internal logical buffer materialization fails. | logical: internal conversion error |
How logical works
logicalaccepts scalars, dense arrays, N-D tensors, and gpuArrays. Shapes are preserved bit-for-bit.- Finite non-zero real numeric values and real infinities map to
true;0and-0map tofalse. - NaN and complex numeric inputs raise conversion errors rather than being coerced.
- Character arrays are converted elementwise by interpreting code points (so
'A'becomestrue,'\0'becomesfalse). - When RunMat extensions are enabled, string arrays convert elementwise by whether each element is nonempty; scalar strings remain unsupported.
- Structs, cells, objects, and other unsupported types raise conversion errors.
- Scalar results become logical scalars (
true/false); dense higher-rank arrays produce dense logical arrays, and sparse inputs preserve sparse storage.
Does RunMat run logical on the GPU?
When a GPU provider implements elem_ne and zeros_like, RunMat evaluates elem_ne(X, 0) into a new device result and marks that result as logical. The result is validated before use and does not alias the input.
If the provider cannot service the request, RunMat converts through the host. Automatically resident inputs may remain on the host; explicit gpuArray inputs are re-uploaded to the same owner or return an error.
Handles that are already flagged as logical (gpuArray.logical) are returned without modification.
Scalars remain scalars: converting a gpuArray scalar preserves the residency and returns a logical gpuArray scalar.
GPU memory and residency
When the acceleration provider supports the required hooks, RunMat creates a logical result on the input's exact GPU owner. If fallback is needed, automatically resident inputs may return a host logical value; explicitly resident inputs are restored to the originating owner or the operation fails rather than silently changing the residency contract.
Examples
Creating a logical mask from numeric data
values = [0 2 -3 0];
mask = logical(values)Expected output:
mask =
1×4 logical array
0 1 1 0Building a logical mask from a matrix
M = [-4 0 8; 0 1 0];
mask = logical(M)Expected output:
mask =
2×3 logical array
1 0 1
0 1 0Treating real infinities as true
flags = logical([-Inf Inf 0])Expected output:
flags =
1×3 logical array
1 1 0Rejecting complex numeric conversion
logical(3 + 4i)Expected output:
Error: conversion to logical from complex numeric data is not possibleConverting character arrays to logical values
chars = ['A' 0 'C'];
mask = logical(chars)Expected output:
mask =
1×3 logical array
1 0 1Keeping gpuArray inputs on the device
G = gpuArray([0 1 2]);
maskGPU = logical(G);
hostMask = gather(maskGPU)Expected output:
hostMask =
1×3 logical array
0 1 1Preserving empty shapes through logical conversion
emptyVec = zeros(0, 3);
logicalEmpty = logical(emptyVec)Expected output:
logicalEmpty =
0×3 logical array
[]Using logical with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how logical changes the result.
Run a small logical example, explain the result, then change one input and compare the output.
FAQ
Which input types does logical support?⌄
Real numeric, logical, character, sparse numeric, and supported gpuArray values are accepted. NaN and complex numeric values are rejected. Enabling RunMat extensions additionally accepts string arrays and symbolic numeric constants; structs, cells, objects, and function handles remain unsupported.
How are NaN or Inf values treated?⌄
Real positive and negative infinity evaluate to true. NaN is rejected with a conversion error.
How does logical handle complex numbers?⌄
Complex numeric inputs are rejected, including values whose imaginary component is zero.
Does the builtin change array shapes?⌄
No. Shapes are preserved exactly, including empty dimensions and higher-rank tensors.
What happens to existing logical arrays?⌄
They are returned verbatim. Logical gpuArrays remain on the device without triggering new allocations.
Can I convert strings with logical?⌄
Scalar strings are rejected. When RunMat extensions are enabled, string arrays are accepted as an extension: each nonempty element becomes true and each empty element becomes false.
What about structs, cells, or objects?⌄
They raise the same conversion error as MATLAB. Use functions like ~cellfun(@isempty, ...) to derive masks instead.
Does the GPU path allocate new buffers?⌄
Yes. The preferred device path computes elem_ne against a zero tensor into a distinct logical result. Fallback may create a host result, and explicit residency may require a new upload to the original owner.
Where can I learn more?⌄
See the references below and the RunMat source for implementation details.
Related Logical functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how logical is executed, line by line, in Rust.
- View the source for logical 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.