RunMat
GitHub

View all functions

CategoryArray: Shape
GPUYes

cat — Concatenate arrays along a specified dimension while preserving MATLAB semantics.

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.

GPU behavior

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 cat 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)

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)

Appending cell array columns for table-like data

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

Keeping gpuArray inputs on the device

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

Requesting GPU output with the 'like' prototype

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

Concatenating complex arrays preserves imaginary parts

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

Combining empty inputs yields an empty result

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

See also

reshape, permute, squeeze, gpuArray, gather

Source & Feedback