What does the `vertcat` function do in MATLAB / RunMat?

vertcat(A1, A2, …) vertically concatenates its inputs, matching the behavior of MATLAB's semicolon array construction [A1; A2; …]. It is the standard way to stack matrices, vectors, or higher-dimensional slices on top of each other.

How does the `vertcat` function behave in MATLAB / RunMat?

Hard-codes dim = 1. All inputs must agree on every dimension except the first.
Accepts numeric, logical, complex, character, string, and cell arrays with MATLAB-compatible type checking. Mixing classes is an error.
Scalars are treated as 1×1, enabling concise row-building such as vertcat(1, 2, 3).
Empty inputs participate naturally. If any shared dimension is zero, the result is empty with the expected shape.
The optional trailing 'like', prototype pair forces the output to match the prototype's data residency (CPU vs GPU) and numeric flavour.
Mixing gpuArray inputs with host inputs is disallowed. Convert explicitly via gpuArray or gather to control residency.

`vertcat` function GPU execution behaviour

vertcat delegates to cat(dim = 1, …). When the active acceleration provider implements the cat hook, concatenation happens entirely on the GPU, keeping gpuArray inputs resident and avoiding costly round-trips. Providers that lack this hook trigger a transparent fallback: RunMat gathers the operands to the host, concatenates them with MATLAB semantics, and uploads the result back to the originating device so downstream code still sees a gpuArray. This mirrors MATLAB's explicit GPU workflows while keeping RunMat's auto-offload planner informed.

Examples of using the `vertcat` function in MATLAB / RunMat

Stacking matrices by adding rows

A = [1 2; 3 4];
B = [5 6; 7 8];
C = vertcat(A, B);

Expected output:

Building a column vector from scalars

col = vertcat(1, 2, 3, 4);

Expected output:

Combining character arrays into taller text blocks

top = ['RunMat'];
bottom = ['Rocks!'];
banner = vertcat(top, bottom);

Expected behavior: banner is a 2×6 character array containing both rows.

Joining string arrays into multi-row tables

header = ["Name" "Score"];
rows = ["Alice" "98"; "Bob" "92"];
table = vertcat(header, rows);

Expected behavior: size(table) returns [3 2] with the header on top.

Preserving logical masks when stacking

mask1 = logical([1 0 1]);
mask2 = logical([0 1 0]);
stacked = vertcat(mask1, mask2);

Expected behavior: stacked is 2×3 logical with rows from both masks.

Extending cell arrays downwards

row1 = {1, "low"};
row2 = {2, "high"};
grid = vertcat(row1, row2);

Expected behavior: grid is a 2×2 cell array with each original row preserved.

Keeping gpuArray inputs resident on the device

G1 = gpuArray(rand(128, 256));
G2 = gpuArray(rand(64, 256));
stacked = vertcat(G1, G2);

Expected behavior: stacked remains a gpuArray with size [192 256].

Requesting GPU output with the `'like'` prototype

proto = gpuArray.zeros(1, 3);
result = vertcat([1 2 3], [4 5 6], "like", proto);

Expected behavior: even though the inputs are on the CPU, result is uploaded to the GPU.

Working with empty rows without surprises

empty = zeros(0, 3);
combo = vertcat(empty, empty);

Expected behavior: size(combo) returns [0 3].

Stacking complex matrices preserves imaginary parts

z1 = complex([1 2], [3 4]);
z2 = complex([5 6], [7 8]);
joined = vertcat(z1, z2);

Expected behavior: joined is 4×1 complex with both sets of values.

FAQ

Does vertcat require at least one input?
No. Calling it with no inputs returns the canonical 0×0 double, just like [].

Can I mix numeric and logical types?
Numeric inputs (real or complex) and logicals must all share the same class. Mixing with strings, chars, or cells is not allowed.

How strict are dimension checks?
All dimensions except the first must match exactly. RunMat reports the mismatch using MATLAB-style error messages sourced from cat.

How do I concatenate along other dimensions?
Use cat(dim, …) directly. vertcat is simply cat(1, …) with additional ergonomics.

What happens if I pass a gpuArray and a CPU array?
RunMat raises an error mirroring MATLAB. Convert everything to the same residency before calling.

Does vertcat participate in fusion pipelines?
No. Concatenation materialises results immediately and is treated as a fusion sink.

Source & Feedback

Implementation: crates/runmat-runtime/src/builtins/array/shape/vertcat.rs
Found an issue or behavioral difference? Open a RunMat issue.

What does the vertcat function do in MATLAB / RunMat?

How does the vertcat function behave in MATLAB / RunMat?

vertcat function GPU execution behaviour

Examples of using the vertcat function in MATLAB / RunMat