RunMat
GitHub

View all functions

CategoryArray: Shape
GPUYes

What does the flip function do in MATLAB / RunMat?

flip(A) reverses the order of elements in A along one or more dimensions. With no dimension argument, RunMat (like MATLAB) flips along the first dimension whose extent is greater than one. Positive integer dimensions or dimension vectors allow you to mirror data along any axis, and direction keywords such as 'horizontal' or 'vertical' provide a readable alternative to numeric indices.

How does the flip function behave in MATLAB / RunMat?

  • Works for numeric arrays, logical masks, complex arrays, and string or character arrays.
  • flip(A) locates the first non-singleton dimension and reverses that axis.
  • flip(A, dim) flips along the dimension dim (1-based, MATLAB-compatible).
  • flip(A, dims) accepts a vector of dimensions, flipping each axis in order.
  • Dimension vectors must be numeric row or column vectors of positive integers.
  • flip(A, 'horizontal') and flip(A, 'vertical') map to dimensions 2 and 1 respectively. 'both' flips along the first two dimensions.
  • Dimensions larger than ndims(A) are allowed. RunMat pads trailing singleton axes so the request becomes a no-op, matching MATLAB semantics.
  • Reversing an empty dimension (extent zero) is a no-op.
  • gpuArray inputs stay on the device: the runtime calls provider flip hooks when available and otherwise gathers, flips, and re-uploads the data.

flip Function GPU Execution Behaviour

When RunMat Accelerate is active, the runtime first checks whether the selected provider implements the flip hook (ProviderHook::Custom("flip")). Providers may specialise the operation using device-side kernels. If the hook is missing (common for the simple provider or builds without GPU support), RunMat gathers the tensor once, performs the flip on the host, and uploads the result back to the device. The returned value is still a gpuArray, ensuring residency is preserved for downstream fused expressions.

Examples of using the flip function in MATLAB / RunMat

Reversing a Row Vector

row = 1:5;
rev = flip(row);

Expected output:

rev = [5 4 3 2 1];

Reversing Matrix Rows (Vertical Flip)

A = [1 2 3; 4 5 6; 7 8 9];
B = flip(A);

Expected output:

B =
     7     8     9
     4     5     6
     1     2     3

Flipping Columns with the Horizontal Direction Keyword

A = magic(3);
H = flip(A, 'horizontal');

Expected output:

H =
     2     7     6
     9     5     1
     4     3     8

Flipping Along Multiple Dimensions

T = reshape(1:8, [2 2 2]);
F = flip(T, [1 3]);

Expected output:

F(:,:,1) =
     3     4
     1     2

F(:,:,2) =
     7     8
     5     6

Flipping Character Data

C = ['r','u','n'; 'm','a','t'];
Ct = flip(C, 'horizontal');

Expected output:

Ct =
    'nur'
    'tam'

Flipping gpuArray Data While Staying on the Device

G = gpuArray(rand(4, 4));
V = flip(G, 'vertical');
isgpuarray(V)

Expected output:

ans = logical 1

GPU residency in RunMat (Do I need gpuArray?)

No additional steps are required. RunMat keeps tensors on the GPU across fused expressions. You can opt-in explicitly with gpuArray for MATLAB compatibility, but the auto-offload planner already tracks residency and minimises host/device copies even when a provider falls back to the gather → flip → upload pathway.

FAQ

Which dimension does flip(A) use by default?

The first dimension whose size is greater than one. Column vectors flip along dimension 1, row vectors flip along dimension 2.

What happens if I pass a dimension larger than ndims(A)?

Nothing changes; RunMat pads missing axes with singleton dimensions, so the flip becomes a no-op, just like MATLAB.

Do direction keywords work with any array type?

Yes. 'horizontal' maps to dimension 2, 'vertical' to dimension 1, and 'both' applies both flips in sequence.

Can I flip logical or string arrays?

Absolutely. Logical results stay logical, and string arrays preserve string elements while reordering their positions.

Does flipping modify gpuArray data in place?

No. The builtin returns a new gpuArray handle. Providers may recycle buffers, but the original value remains unchanged.

What about complex inputs?

Complex scalars and arrays are reversed just like real data. Scalars remain complex scalars after the operation.

See Also

Source & Feedback