cell2mat — Convert cell arrays of blocks into dense arrays in MATLAB and RunMat.
cell2mat(C) concatenates numeric, logical, complex, or character blocks stored in cell array C into one dense array. Cells must form a rectangular block layout with compatible extents, matching MATLAB and RunMat rules.
Syntax
A = cell2mat(C)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
C | Any | Yes | — | Input cell array. |
Returns
| Name | Type | Description |
|---|---|---|
A | Any | Dense array assembled from cell contents. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:cell2mat:InvalidInput | The input is not a cell array. | cell2mat: expected a cell array input |
RunMat:cell2mat:InvalidContents | Cell contents cannot be concatenated to a dense array. | cell2mat: cell contents are not compatible for concatenation |
RunMat:cell2mat:SizeExceeded | Resulting output exceeds supported platform limits. | cell2mat: resulting matrix exceeds platform limits |
| — | Internal cell2mat allocation or conversion failed. | cell2mat: internal error |
How cell2mat works
- Works for cell arrays whose elements are numeric, logical, complex, or character arrays (including scalars and empties). Mixed types are rejected.
- RunMat currently represents cell arrays as 2-D grids. The first dimension tiles rows, the second tiles columns, and any higher dimensions inside each element must agree exactly across all cells.
- Empty cells contribute zero extent in their tiling dimension while preserving type information.
- The output array uses column-major layout for numeric, logical, and complex data, and matches MATLAB character array semantics for text.
- Calling
cell2maton an empty cell array returns the empty double matrix0×0.
Does RunMat run cell2mat on the GPU?
cell2mat is inherently a host operation because MATLAB cell arrays live on the CPU heap. If a cell element is a GPU tensor (gpuArray) RunMat gathers it to host memory before concatenating. Providers do not need to implement bespoke kernels: the builtin terminates GPU fusion groups, materialises the inputs on the host, and returns a host-resident array.
GPU memory and residency
You usually do NOT need to call gpuArray before cell2mat. The builtin always gathers GPU-resident elements to the host so it can stitch the resulting matrix in CPU memory. Explicitly wrapping each cell in gpuArray is harmless, but there is no residency benefit because the final result is a standard CPU array.
Examples
Converting a 2-by-2 cell array of scalars into a matrix
C = {1, 2; 3, 4};
A = cell2mat(C)Expected output:
A =
1 2
3 4Concatenating blocks of different column widths
C = {[1 2], [3 4 5]; [6 7], [8 9 10]};
A = cell2mat(C)Expected output:
A =
1 2 3 4 5
6 7 8 9 10Converting logical cell contents into a logical matrix
C = {true(2,1), false(2,1)};
M = cell2mat(C)Expected output:
M =
2×2 logical array
1 0
1 0Handling complex-valued blocks
C = {1+2i, [3+4i 5+6i]};
Z = cell2mat(C)Expected output:
Z =
1.0000 + 2.0000i 3.0000 + 4.0000i 5.0000 + 6.0000iProducing character matrices from cell arrays of character rows
C = {'foo', 'bar'; 'baz', 'qux'};
S = cell2mat(C)Expected output:
S =
'foobar'
'bazqux'Tiling higher-dimensional numeric blocks
C = {ones(2,2,3), 2*ones(2,1,3)};
X = cell2mat(C);
size(X)Expected output:
ans =
2 3 3Working with empty cells
C = {[], []; [], []};
A = cell2mat(C);
size(A)Expected output:
ans =
0 0Gathering GPU tensors stored inside cells
G = gpuArray(ones(4,1));
C = {G, 2*G};
H = cell2mat(C); % gathered back to host automatically
classUnderlying(H)Expected output:
ans =
'double'Using cell2mat with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how cell2mat changes the result.
Run a small cell2mat example, explain the result, then change one input and compare the output.
FAQ
What element types does cell2mat support?⌄
Numeric doubles (scalars or arrays), complex doubles, logical values, and character arrays. Mixed types are not allowed; every populated cell must have the same fundamental type.
Can I convert a cell array that contains structs or strings?⌄
No. cell2mat requires array-like contents. Use specialised functions such as string or char converters for string data, or bespoke logic for structs and tables.
Do the cell contents need identical shapes?⌄
Cells in the same row must share the same number of rows. Cells in the same column must share the same number of columns. Any higher dimensions must agree across all cells. Violations produce a descriptive error that mirrors MATLAB's behaviour.
What happens with empty cells?⌄
Empty cells contribute zero extent along their tiling dimension. For example, if every element in a row is empty, the resulting matrix has zero rows for that block. Completely empty cell arrays produce the 0×0 empty double matrix.
Does cell2mat return GPU arrays when inputs are gpuArray elements?⌄
Not yet. RunMat gathers GPU elements to the host before concatenating. Future releases may introduce GPU-resident cell storage, at which point providers can supply dedicated kernels.
Related Cells functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how cell2mat is executed, line by line, in Rust.
- View the source for cell2mat 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.