numel — Count elements in MATLAB and RunMat.
numel(A) returns the number of elements contained in A. Supported value classes and return-type behavior follow MATLAB semantics.
Syntax
n = numel(A)
n = numel(A, dim, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input value to inspect. |
dim | SizeArg | Variadic | — | Dimension selectors (scalar or vector forms). |
Returns
| Name | Type | Description |
|---|---|---|
n | NumericScalar | Number of elements selected from input. |
Errors
| Identifier | When | Message |
|---|---|---|
| — | Dimension arguments are not numeric scalars/vectors. | numel: dimension arguments must be numeric scalars or vectors |
| — | Dimension vector argument has zero elements. | numel: dimension vector must contain at least one element |
| — | Dimension vector argument is not vector-shaped. | numel: dimension vector must be a vector of positive integers |
| — | A dimension selector is non-finite. | numel: dimension must be finite |
| — | A dimension selector is non-integer. | numel: dimension must be an integer |
| — | A dimension selector is less than one. | numel: dimension must be >= 1 |
| — | No dimensions are provided after parsing. | numel: dimension list must contain at least one element |
RunMat:numel:CountNotExactDouble | The element count cannot be represented exactly by the documented double scalar output. | numel: result exceeds exact double range |
How numel works
numel(A)counts every stored element; for matrices this isprod(size(A)).- MATLAB's public syntax is
numel(A)only. RunMat's additionalnumel(A, dim1, dim2, ...)and dimension-vector forms are one named RunMat extension and reject in MATLAB-compatible modes. - When the RunMat dimension extension is enabled, all eight typed integer dimension classes parse exactly as positive structural selectors; dimensions beyond the array rank contribute a factor of
1. - Scalars return
1, character arrays reportrows × cols, and cell arrays count the number of cells. - Empty arrays return
0when any dimension is zero. - GPU-resident arrays use coherent shape metadata stored on the device handle; payload elements are not gathered for the documented form. The exact structural count is returned as a host double only when representable without rounding.
Does RunMat run numel on the GPU?
numel does not launch GPU kernels or register provider hooks. When the input is a GPU tensor, the runtime consults the shape metadata stored in the handle to compute the count. If the active provider omits this metadata, RunMat downloads the tensor once to recover the correct answer. The builtin always returns a host double scalar and never allocates device memory, so it can safely be used inside fused GPU expressions without breaking residency.
Examples
Counting elements in a matrix
A = [1 2 3; 4 5 6];
n = numel(A)Expected output:
n = 6Checking the number of elements in a cell array
C = {1, 2, 3; 4, 5, 6};
cells = numel(C)Expected output:
cells = 6Getting the number of elements along selected dimensions
T = rand(4, 3, 2);
plane = numel(T, 1, 2); % product of the first two dimensionsExpected output:
plane = 12Using numel with gpuArray data
G = gpuArray(ones(256, 4));
count = numel(G)Expected output:
count = 1024Confirming the number of characters in a char array
name = ['R' 'u' 'n' 'M' 'a' 't'];
chars = numel(name)Expected output:
chars = 6Using numel with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how numel changes the result.
Run a small numel example, explain the result, then change one input and compare the output.
FAQ
How is numel different from length?⌄
numel(A) counts every element in A, whereas length(A) returns the size of the largest single dimension.
What happens when I specify dimensions?⌄
MATLAB documents only numel(A). RunMat can multiply selected extents with numel(A, dim1, dim2, ...) when RunMat extensions are enabled; missing dimensions contribute a factor of 1.
Does numel gather GPU data?⌄
Usually no. The runtime reads shape metadata from the GPU tensor handle. It gathers only when the provider fails to populate that metadata.
What does numel return for empty arrays?⌄
If any dimension is zero, numel returns 0. This behaviour matches MATLAB for empty matrices, cell arrays, and logical arrays.
Can I use numel on strings and character arrays?⌄
Yes. Character arrays return the total number of characters (rows × cols). String arrays are treated as ordinary arrays with MATLAB-compatible dimensions.
Is numel safe inside fused GPU expressions?⌄
Yes. The builtin returns a host double scalar and does not allocate device buffers, so fusion plans remain intact.
Does numel accept non-integer dimensions?⌄
Dimension arguments belong to a RunMat-only syntax. When extensions are enabled they must be positive integers; fractional, negative, or non-numeric values raise an error.
What does numel do in MATLAB?⌄
numel(A) returns the total number of elements in array A. It is equivalent to prod(size(A)). In RunMat, numel works identically and supports GPU arrays.
Is numel the same as length in MATLAB?⌄
No. numel returns the total element count across all dimensions, while length returns the size of the largest dimension. For a 3×4 matrix, numel returns 12 but length returns 4.
Can I use numel with cell arrays and structs?⌄
Yes. numel counts the number of cells in a cell array or the number of elements in a struct array. It does not recurse into cell contents or struct fields.
What is the difference between numel and length?⌄
— numel counts every element across all dimensions, while length returns the size of the largest dimension. For example, numel(rand(3,4,5)) returns 60, but length(rand(3,4,5)) returns 5 (the largest dim). Use numel whenever you want the total element count.
Should I use numel or size to count elements?⌄
— Use numel(A) when you want the total number of elements (a single scalar). Use size(A, dim) when you need the length of a specific dimension, and size(A) when you need the full shape vector. numel(A) is equivalent to prod(size(A)).
Related Array functions
Grouping
accumarray · combinations · discretize · findgroups · groupcounts · grp2idx · splitapply
Sorting Sets
argsort · intersect · ismember · ismembertol · issorted · issortedrows · setdiff · setxor · sort · sortrows · union · unique
Shape
blkdiag · cat · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · permute · repelem · repmat · reshape · rot90 · squeeze · toeplitz · tril · triu · vertcat
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how numel is executed, line by line, in Rust.
- View the source for numel 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.