mat2cell — Split arrays into cell-array blocks in MATLAB and RunMat.
mat2cell(A, ...) partitions A along dimensions using block-size vectors and returns blocks in a cell array. Partition validation and output layout follow MATLAB semantics.
Syntax
C = mat2cell(A, dim1dist)
C = mat2cell(A, dim1dist, dim2dist, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input array to partition. |
dim1dist | SizeArg | Yes | — | Partition sizes for the first dimension. |
dimdist | SizeArg | Variadic | — | One partition vector per dimension. |
Returns
| Name | Type | Description |
|---|---|---|
C | Any | Cell array of extracted blocks. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:mat2cell:InvalidInput | Input array type or argument count is invalid. | mat2cell: invalid input arguments |
RunMat:mat2cell:InvalidPartition | Partition vectors are malformed or inconsistent with input dimensions. | mat2cell: invalid partition sizes |
RunMat:mat2cell:SizeExceeded | Partitioning or output shape exceeds platform limits. | mat2cell: size exceeds platform limits |
| — | Internal partitioning, indexing, or allocation failed. | mat2cell: internal error |
How mat2cell works
- Supply one size vector per dimension you want to split. Their elements must be non-negative integers that sum to the corresponding dimension of the input array.
- If you omit trailing size vectors, RunMat assumes the remaining dimensions stay intact (
size(A, dim)). - Zero-sized blocks are allowed and produce empty matrices (or empty arrays of the input type).
- N-dimensional inputs are supported; the output cell array has one dimension per supplied size vector.
- Inputs can be numeric, complex, logical, string, or character arrays. Struct, object, and cell arrays are not yet supported.
Does RunMat run mat2cell on the GPU?
When the input is a gpuArray, RunMat gathers it back to the host before performing the partition, and the resulting cells contain host tensors. This matches MATLAB semantics except for the residency—providers do not yet offer on-device block-splitting hooks. Once such hooks become available, RunMat can keep results on the GPU with no user code changes.
GPU memory and residency
The current implementation gathers GPU inputs to the host, produces host cell arrays, and returns CPU-resident tensors inside each cell. Explicit gpuArray calls are not required; once GPU providers offer block-splitting hooks, mat2cell will keep results on the device automatically.
Examples
Splitting a matrix into four quadrants
A = reshape(1:16, 4, 4);
C = mat2cell(A, [2 2], [1 3])Expected output:
size(C) % => [2 2]
double(C{2,2}) % => [7 11 15; 8 12 16]Splitting a column vector with only row sizes
v = (1:6)';
blocks = mat2cell(v, [2 1 3])Expected output:
cellfun(@numel, blocks) % => [2; 1; 3]
blocks{3} % => [4; 5; 6]Partitioning a 3-D tensor
T = reshape(1:24, [3 4 2]);
C = mat2cell(T, [1 2], [2 2], [1 1])Expected output:
size(C) % => [2 2 2]
double(C{2,1,2}(:,:,1)) % => [14 17; 15 18]Using zero-sized blocks
E = zeros(3, 2);
C = mat2cell(E, [0 3], [1 1]);
cellfun(@size, C, 'UniformOutput', false)Expected output:
ans{1,1} = [0 1]
ans{1,2} = [0 1]
ans{2,1} = [3 1]
ans{2,2} = [3 1]Splitting a character matrix into rows
names = ['foo '; 'bar '; 'baz '];
C = mat2cell(names, [1 2], size(names, 2))Expected output:
C{1,1} % => 'foo '
C{2,1} % => ['bar '; 'baz ']Working with logical arrays
mask = logical([1 0 1; 0 1 0]);
cells = mat2cell(mask, 2, [1 1 1])Expected output:
cells{1,2} % => logical column vector [0; 1]
class(cells{1,2}) % => 'logical'Using mat2cell with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how mat2cell changes the result.
Run a small mat2cell example, explain the result, then change one input and compare the output.
FAQ
Do the partition vectors have to sum exactly to the dimension size?⌄
Yes. Each size vector must consist of non-negative integers whose sum matches the corresponding dimension of the input array. RunMat raises an error when the sums differ.
What happens if I omit trailing dimension vectors?⌄
RunMat mirrors MATLAB: omitted trailing vectors are treated as a single block that covers the entire dimension (size(A, dim)), so many common 2-D use cases only need two vectors.
Are zero-sized blocks allowed?⌄
Yes. A zero entry in a partition vector produces an empty array in the corresponding cell. This is useful when you need placeholders that preserve grid structure.
What element types are supported?⌄
Numeric, complex, logical, string, and character arrays are supported today. Struct arrays, object arrays, and cell arrays will gain support in a future update.
Does mat2cell copy the data?⌄
Yes. Each cell receives its own copy of the underlying block so that you can modify the cell contents without affecting other cells or the original array.
What does mat2cell do in MATLAB?⌄
mat2cell(X, rowSizes, colSizes) divides matrix X into a cell array of sub-matrices. The partition vectors specify the row and column sizes of each block, and must sum to the dimension sizes of X.
How is mat2cell different from num2cell?⌄
num2cell splits a matrix into individual scalar cells (one element per cell), while mat2cell splits into sub-matrices of specified sizes. Use mat2cell when you need contiguous blocks.
Can I use mat2cell on 3-D arrays?⌄
Yes. Provide partition vectors for each dimension: mat2cell(X, rowSizes, colSizes, pageSizes). Omitted trailing dimensions are treated as a single partition equal to the full size.
How do I convert a cell array back to a matrix?⌄
Use cell2mat(C) to concatenate the cells back into a single matrix. Each cell must contain a numeric array, and the sizes must be consistent along concatenation dimensions.
Related Cells functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how mat2cell is executed, line by line, in Rust.
- View the source for mat2cell 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.