What does the ismatrix function do in MATLAB / RunMat?

ismatrix(A) returns logical true when the input has two dimensions (m-by-n) and logical false otherwise. Scalars and vectors are considered matrices because they occupy a 1-by-1 or 1-by-n grid. The builtin mirrors MATLAB semantics across numeric, logical, character, string, cell, struct, and GPU-resident data.

How does the ismatrix function behave in MATLAB / RunMat?

• Returns true for scalars, row vectors, column vectors, and ordinary 2-D matrices.
• Returns false for arrays whose rank exceeds two, even if trailing dimensions are singleton (for example, 1×1×1).
• Empty arrays such as 0×0, 1×0, and 0×1 are matrices; higher-rank empties such as 0×0×3 are not.
• Character arrays, string arrays, and cell arrays honor their reported MATLAB dimensions.
• GPU tensors rely on their GpuTensorHandle metadata; 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).

ismatrix Function GPU Execution Behaviour

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 residency in RunMat (Do I need gpuArray?)

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 of using the ismatrix function in MATLAB / RunMat

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)

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.

See Also

isscalar, isvector, ndims, size, gpuArray, gather