ismatrix — Test whether values are matrices in MATLAB and RunMat.
ismatrix(A) returns true when A has at most two dimensions. Scalar/vector treatment and shape rules follow MATLAB semantics.
Syntax
tf = ismatrix(A)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input value to inspect. |
Returns
| Name | Type | Description |
|---|---|---|
tf | LogicalArray | True when input has at most two dimensions. |
How ismatrix works
- Returns
truefor scalars, row vectors, column vectors, and ordinary 2-D matrices. - Returns
falsefor arrays whose rank exceeds two, even if trailing dimensions are singleton (for example,1×1×1). - Empty arrays such as
0×0,1×0, and0×1are matrices; higher-rank empties such as0×0×3are not. - Character arrays, string arrays, and cell arrays honor their reported MATLAB dimensions.
- GPU tensors rely on their
GpuTensorHandlemetadata; if a provider omits the shape, RunMat gathers once to inspect it. - Objects, structs, numeric scalars, and logical scalars behave like their underlying dimensions (
1×1).
Does RunMat run ismatrix on the GPU?
ismatrix never launches GPU kernels. For gpuArray inputs, the builtin first inspects the shape metadata stored inside the GpuTensorHandle. Providers such as the WGPU backend fully populate that metadata so no data transfer occurs. If metadata is absent, RunMat gathers the tensor once to recover its dimensions and then evaluates the predicate on the host. The result is always a host logical scalar, so fusion treats ismatrix as a metadata query rather than a device-side operation.
GPU memory and residency
You do not need to move data between host and device to call ismatrix. The builtin respects existing residency and only downloads data when the provider fails to report shapes. Users who prefer MATLAB-compatible workflows can still call gpuArray explicitly, but it is not required for this metadata check.
Examples
Confirming that a 2-D matrix returns true
tf = ismatrix([1 2 3; 4 5 6])Expected output:
tf = logical(1)Showing that vectors and scalars count as matrices
scalar_tf = ismatrix(42);
row_tf = ismatrix(1:5);
col_tf = ismatrix((1:5)')Expected output:
scalar_tf = logical(1)
row_tf = logical(1)
col_tf = logical(1)Detecting that higher-dimensional arrays are not matrices
tf = ismatrix(ones(2,2,3))Expected output:
tf = logical(0)Working with empty arrays
tf_empty = ismatrix([]);
tf_row0 = ismatrix(zeros(1,0));
tf_col0 = ismatrix(zeros(0,1));
tf_3d_empty = ismatrix(zeros(0,0,3))Expected output:
tf_empty = logical(1)
tf_row0 = logical(1)
tf_col0 = logical(1)
tf_3d_empty = logical(0)Character and string arrays follow their visible dimensions
tf_char = ismatrix('RunMat');
tf_string = ismatrix(["a","b","c"])Expected output:
tf_char = logical(1)
tf_string = logical(1)Cell and struct arrays respect their grid layout
C = {1, 2; 3, 4};
S = repmat(struct("field", 1), 1, 3, 1);
tf_cell = ismatrix(C);
tf_struct = ismatrix(S)Expected output:
tf_cell = logical(1)
tf_struct = logical(0)Inspecting GPU arrays without explicit gathers
G = gpuArray(rand(4,4));
tf_gpu = ismatrix(G)Expected output:
tf_gpu = logical(1)Using ismatrix with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how ismatrix changes the result.
Run a small ismatrix example, explain the result, then change one input and compare the output.
FAQ
Does ismatrix treat scalars as matrices?⌄
Yes. Scalars occupy a 1-by-1 grid, which is a valid two-dimensional matrix in MATLAB semantics.
Are vectors considered matrices?⌄
Yes. Row and column vectors are 1-by-N and N-by-1 matrices, so ismatrix returns true.
Do trailing singleton dimensions change the result?⌄
Yes. Any array whose rank exceeds two returns false, even if the extra dimensions are size one (for example, 1×1×1).
How are empty arrays handled?⌄
Empty arrays with at most two dimensions (such as 0×0, 1×0, or 0×1) return true. Higher-rank empties return false.
What about character, string, or cell arrays?⌄
They follow their MATLAB-visible dimensions. A character row vector or 1-by-N string array returns true, whereas a 1-by-1-by-N cell array returns false.
Will ismatrix download GPU data?⌄
Only when the active provider fails to populate shape metadata on the GpuTensorHandle. Providers that supply the shape avoid any data transfer.
Does ismatrix participate in fusion or GPU kernels?⌄
No. The builtin is a metadata query, always returns a host logical scalar, and never dispatches GPU work.
How does ismatrix relate to isvector and isscalar?⌄
isscalar(A) and isvector(A) both imply ismatrix(A) because they describe special cases of 2-D arrays. The reverse implication does not necessarily hold.
Are objects and structs supported?⌄
Yes. Objects and structs are treated as 1-by-1 unless they represent arrays of instances, in which case the reported dimensions determine the answer.
Does sparse support change the behaviour?⌄
Future sparse tensors will report their dimensions through the same metadata, so the ismatrix predicate will remain unchanged.
Related Array functions
Shape
cat · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · permute · repelem · repmat · reshape · rot90 · squeeze · tril · triu · vertcat
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how ismatrix is executed, line by line, in Rust.
- View the source for ismatrix 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.