What does the cat function do in MATLAB / RunMat?

cat(dim, A1, A2, …) concatenates arrays along the dimension dim, producing a new array whose slices along that dimension are the input arrays. The result preserves column-major ordering and shares MATLAB's rules for implicit singleton expansion.

How does the cat function behave in MATLAB / RunMat?

• dim is 1-based and must be a positive integer.
• All inputs must be the same class (double, logical, complex, char, string, or cell).
• Dimensions other than dim must match exactly; missing higher dimensions are treated as size 1 automatically.
• The size along dim becomes the sum of the corresponding sizes from each input.
• Empty inputs participate naturally—if any dimension is zero, the result is empty.
• gpuArray inputs stay on the device when an acceleration provider is registered.
• Append an optional 'like', prototype pair to request output that matches the prototype's device residency; numeric prototypes may be host tensors or gpuArray handles, while logical prototypes must remain on the CPU.

cat Function GPU Execution Behaviour

When every input is a gpuArray, RunMat first calls the active provider's AccelProvider::cat hook to concatenate the buffers directly on the device. Providers that do not expose this hook trigger a transparent fallback: the operands are gathered to the host, concatenated with the same rules as CPU arrays, and uploaded back to the originating device so downstream work still sees a gpuArray. The 'like' prototype is honoured during fallback, ensuring the final residency matches your request. Mixing host arrays with gpuArray inputs is not supported—convert explicitly with gpuArray / gather to control residency.

Examples of using the cat function in MATLAB / RunMat

Concatenating matrices by stacking rows

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

Expected output:

C =
     1     2
     3     4
     5     6
     7     8

Concatenating matrices by appending columns

left = [1 3; 2 4];
right = [10 30; 20 40];
wide = cat(2, left, right);

Expected output:

wide =
     1     3    10    30
     2     4    20    40

Building a 3-D array from 2-D slices

slice1 = magic(3);
slice2 = eye(3);
cube = cat(3, slice1, slice2);

Expected behaviour: size(cube) is [3 3 2] with the original matrices in the third dimension.

Concatenating logical masks without type changes

row = logical([1 0 1]);
mask = cat(1, row, ~row);

Expected output:

mask =
   1   0   1
   0   1   0

Joining character arrays into wider text rows

lhs = ['Run' ; 'GPU'];
rhs = ['Mat'; 'Fun'];
words = cat(2, lhs, rhs);

Expected output:

words =
    RunMat
    GPUFun

Concatenating string arrays along rows

names = ["alpha" "beta"];
more = ["gamma" "delta"];
combined = cat(1, names, more);

Expected behaviour: combined is a 2×2 string array.

Appending cell array columns for table-like data

cols1 = {1, 2; 'a', 'b'};
cols2 = {3, 4; 'c', 'd'};
tableCells = cat(2, cols1, cols2);

Expected behaviour: tableCells is 2×4 with cells from both inputs interleaved by row.

Keeping gpuArray inputs on the device

G1 = gpuArray(rand(256, 256));
G2 = gpuArray(rand(256, 256));
stacked = cat(3, G1, G2);

Expected behaviour: stacked remains a gpuArray with shape [256 256 2].

Requesting GPU output with the 'like' prototype

G = gpuArray(rand(3, 3));
H = cat(3, zeros(3, 3), ones(3, 3), "like", G);

Expected behaviour: H remains a gpuArray and size(H) returns [3 3 2].

Concatenating complex arrays preserves imaginary parts

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

Expected behaviour: joined is complex and retains the real/imaginary components.

Combining empty inputs yields an empty result

emptyRow = zeros(0, 3);
combo = cat(1, emptyRow, emptyRow);

Expected behaviour: combo is still 0×3.

FAQ

How many input arrays do I need to provide? At least two—cat requires cat(dim, A, B, …).

Can I mix different classes (e.g. doubles and logicals)? No. MATLAB requires all inputs to share the same class. RunMat mirrors this requirement and raises an error when classes differ.

Does cat support higher dimensions automatically? Yes. Missing dimensions are treated as size 1, and the output length matches the largest dimension index used.

What happens with empty inputs? Empty arrays participate naturally. If any shared dimension is zero, the output becomes empty as well.

How do I ensure the result lives on the GPU without converting every input? Append 'like', prototype to the argument list, where prototype is an existing gpuArray. RunMat uploads the concatenated result to the same device when the active provider lacks a native concatenation kernel.

Can I concatenate gpuArray inputs with regular arrays? No. Mixes of gpuArray and host arrays raise an error—convert explicitly with gpuArray or gather first.

Does concatenation copy data? Yes. Concatenation produces a new array; upstream values remain unchanged. GPU providers minimise transfers by running in place when possible.

How does concatenation interact with complex numbers? Complex inputs stay complex. Real inputs promoted during a complex concatenation receive zero imaginary parts.

Can I concatenate cell arrays or string arrays? Yes. cat supports both and enforces MATLAB's row/column rules for those container types.

What if the provider lacks a GPU implementation? RunMat gathers the operands, concatenates them on the host, uploads the result back to the device, and logs the fallback so residency stays consistent.

Is the result always at least two-dimensional? Scalars remain scalars. Otherwise, trailing singleton dimensions are trimmed unless required to preserve the specified dimension.

See Also

• reshape
• permute
• squeeze
• gpuArray
• gather

Source & Feedback

• Full implementation: crates/runmat-runtime/src/builtins/array/shape/cat.rs
• Found a bug or behavioural difference? Open an issue.