What does the ndims function do in MATLAB / RunMat?
ndims(A) returns the number of dimensions (rank) of A, following MATLAB conventions. Scalars,
vectors, matrices, and N-D tensors always report at least two dimensions; higher-rank arrays report
their full dimension count. This behaviour matches MathWorks MATLAB for numeric, logical, char,
string, cell, struct, and GPU arrays.
How does the ndims function behave in MATLAB / RunMat?
- Scalars and vectors return
2, because MATLAB treats them as1×1or1×N. - Matrices return
2unless they have trailing dimensions beyond the second. - N-D arrays return the length of their dimension vector after trailing singleton dimensions are preserved.
- Character arrays, string arrays, logical arrays, complex arrays, and cell arrays all follow their MATLAB array shape metadata.
- GPU tensors report their rank without gathering when the provider populates shape metadata on the handle. When metadata is missing, RunMat downloads the tensor once to preserve correctness.
- Objects, scalars, and other non-array values return
2, consistent with MATLAB's scalar rules.
ndims Function GPU Execution Behaviour
ndims is a metadata query. When the input resides on the GPU, RunMat inspects the shape stored in
GpuTensorHandle.shape. No kernels are launched, no buffers are allocated, and residency is not
altered. If a provider leaves the shape empty, the runtime downloads the tensor a single time to
reconstruct its dimensions before returning a host scalar. The builtin therefore preserves fusion
pipelines while still providing MATLAB-compatible answers.
Examples of using the ndims function in MATLAB / RunMat
Checking how many dimensions a scalar has
n = ndims(42);
Expected output:
n = 2;
Counting the dimensions of a matrix
A = rand(5, 3);
r = ndims(A);
Expected output:
r = 2;
Detecting 3-D array dimensionality
V = rand(4, 5, 6);
r = ndims(V);
Expected output:
r = 3;
Finding ndims for gpuArray data without gathering
G = gpuArray(ones(16, 32, 2));
r = ndims(G);
Expected output:
r = 3;
Understanding ndims with cell arrays
C = {1, 2, 3; 4, 5, 6};
r = ndims(C);
Expected output:
r = 2;
Verifying ndims on string arrays
S = ["alpha"; "beta"; "gamma"];
r = ndims(S);
Expected output:
r = 2;
FAQ
Why does ndims return 2 for scalars and vectors?
MATLAB treats scalars and vectors as 2-D arrays (1×1 or 1×N). RunMat mirrors this behaviour, so
ndims(5) and ndims([1 2 3]) both return 2.
Does ndims ignore trailing singleton dimensions?
No. MATLAB preserves trailing singletons when reporting the rank. If your tensor was explicitly
created with size 10×1×1×4, ndims returns 4.
How does ndims behave for GPU tensors?
The runtime inspects shape metadata stored in the GPU tensor handle. When the provider populates that field, no gathering occurs. If metadata is absent, RunMat downloads the tensor to keep the answer correct.
Can I call ndims on cell arrays and structs?
Yes. ndims inspects the MATLAB array shape of the container, so cell arrays and struct arrays
report their grid dimensions.
What about objects or scalars like strings and logical values?
Objects and scalar values follow MATLAB scalar rules and return 2. Use specialised functions (like
isobject) when you need more information about their type.
Does ndims participate in GPU fusion?
No. ndims returns a host scalar immediately and performs no computation on the GPU. It is safe to
use inside expressions that also run on the GPU because it does not allocate device memory.