RunMat
GitHub

View all functions

CategoryLogical
GPUYes

What does the logical function do in MATLAB / RunMat?

logical(X) converts numeric, logical, character, and gpuArray inputs into MATLAB logical values (booleans). Any non-zero (or NaN/Inf) element maps to true, while zero maps to false. Logical inputs are returned unchanged.

How does the logical function behave in MATLAB / RunMat?

  • logical accepts scalars, dense arrays, N-D tensors, and gpuArrays. Shapes are preserved bit-for-bit.
  • Non-zero numeric values, NaN, and Inf map to true; 0 and -0 map to false.
  • Complex inputs are considered true when either the real or imaginary component is non-zero.
  • Character arrays are converted elementwise by interpreting code points (so 'A' becomes true, '\0' becomes false).
  • Strings, structs, cells, objects, and other non-numeric types raise MATLAB-compatible errors ("Conversion to logical from <type> is not possible").
  • Scalar results become logical scalars (true/false); higher-rank arrays produce dense logical arrays.

logical Function GPU Execution Behaviour

  • When a GPU provider implements elem_ne and zeros_like, RunMat performs the conversion in-place on the device by evaluating elem_ne(X, 0), then marks the resulting handle as logical so predicates like islogical work without downloads.
  • If the provider cannot service the request (missing hooks, unsupported dtype, or allocation failure), the value is transparently gathered to the host, converted, and—when a provider is still available—re-uploaded as a logical gpuArray. The fallback is documented so users understand potential host/device transitions.
  • 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.

Examples of using the logical function in MATLAB / RunMat

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     0

Building 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     0

Treating NaN and Inf values as true

flags = logical([NaN Inf 0]);

Expected output:

flags =
  1×3 logical array
     1     1     0

Converting complex numbers to logical scalars

z = logical(3 + 4i);
w = logical(0 + 0i);

Expected output:

z =
     1
w =
     0

Converting character arrays to logical values

chars = ['A' 0 'C'];
mask = logical(chars);

Expected output:

mask =
  1×3 logical array
     1     0     1

Keeping 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     1

Preserving empty shapes through logical conversion

emptyVec = zeros(0, 3);
logicalEmpty = logical(emptyVec);

Expected output:

logicalEmpty =
  0×3 logical array
     []

GPU residency in RunMat (Do I need gpuArray?)

You rarely need to call gpuArray manually. When the acceleration provider is active, RunMat keeps logical conversions on the GPU by issuing elem_ne(X, 0) kernels (backed by zeros_like allocations) and flagging the handle as logical metadata. Explicit gpuArray calls are available for MATLAB compatibility or when you want to pin residency before interacting with external libraries. When the provider lacks the necessary hook, RunMat documents the fallback: it gathers the data, converts it on the host, and—if a provider is still available—re-uploads the logical mask so downstream GPU code continues to work without residency surprises.

FAQ

Which input types does logical support?

Numeric, logical, complex, character, and gpuArray values are accepted. Strings, structs, cells, objects, and function handles are rejected with MATLAB-compatible error messages.

How are NaN or Inf values treated?

They evaluate to true. MATLAB defines logical conversion as “non-zero”, and NaN / Inf both satisfy that rule.

How does logical handle complex numbers?

The result is true when either the real or imaginary component is non-zero (or NaN/Inf). Only 0 + 0i converts to false.

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?

No. MATLAB rejects string inputs, and RunMat mirrors that behaviour: "logical: conversion to logical from string is not possible".

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?

Only when the provider cannot operate in-place. The preferred path performs elem_ne against a zero tensor and reuses the resulting buffer. Fallback paths allocate a new gpuArray after gathering to the host.

Where can I learn more?

See the references below and the RunMat source for implementation details.

See Also

islogical, gpuArray, gather, find

Source & Feedback