RunMat
GitHub

View all functions

CategoryArray: Shape
GPUYes

What does the circshift function do in MATLAB / RunMat?

circshift(A, K) rotates the elements of A circularly. Positive shifts move elements toward higher indices, wrapping values that fall off the end back to the beginning. Shifts can be specified per-dimension using vectors or paired with explicit dimension lists.

How does the circshift function behave in MATLAB / RunMat?

  • circshift(A, k) shifts by k positions along the first non-singleton dimension. Negative values shift in the opposite direction.
  • circshift(A, shiftVec) accepts a numeric vector that supplies a shift per dimension. Missing dimensions default to zero. Extra dimensions are treated as size-one axes, so they have no effect unless an explicit reshape added those dimensions previously.
  • circshift(A, K, dims) lets you target specific dimensions. K and dims must have the same length; each entry in dims is 1-based.
  • Works for numeric tensors, logical masks, complex arrays, string arrays, and character matrices. Character arrays only support dimensions one and two, mirroring MATLAB limitations.
  • Empty dimensions remain empty; shifting them is a no-op. Scalars are returned unchanged.
  • Shifts that are integer multiples of a dimension’s extent leave that axis unchanged. RunMat reduces each shift modulo the axis length, matching MATLAB.

circshift Function GPU Execution Behaviour

When RunMat Accelerate is active, the runtime first asks the selected provider for a native circshift implementation. Providers that implement the hook perform the rotation entirely on the device, preserving residency metadata and enabling fusion with subsequent GPU kernels. If the hook is missing, RunMat downloads the tensor once, rotates it on the host using the same semantics, and uploads the result back to the GPU so downstream work continues without manual intervention.

Examples of using the circshift function in MATLAB / RunMat

Shifting matrix rows downward by one location

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

Expected output:

B =
     7     8     9
     1     2     3
     4     5     6

Shifting columns left by two positions

A = reshape(1:12, [3 4]);
C = circshift(A, [0 -2]);

Expected output:

C =
     7    10     1     4
     8    11     2     5
     9    12     3     6

Rotating a 3-D tensor along multiple dimensions

T = reshape(1:8, [2 2 2]);
U = circshift(T, [1 0 -1]);
U(:, :, 1)
U(:, :, 2)

Expected output:

ans(:,:,1) =
     6     8
     5     7

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

Shifting along specific dimensions using the dims argument

A = reshape(1:12, [3 4]);
V = circshift(A, [2 -1], [1 2]);

Expected output:

V =
     6     7     8     5
     9    10    11    12
     3     4     1     2

Rotating a character matrix to cycle through rows and columns

C = ['r','u','n'; 'm','a','t'];
R = circshift(C, [0 1]);

Expected output:

R =
    'nru'
    'tma'

Applying circshift to a gpuArray and keeping the result on the device

G = gpuArray(reshape(1:12, [3 4]));
H = circshift(G, [1 -2]);
isgpuarray(H)

Expected output:

ans = logical 1

GPU residency in RunMat (Do I need gpuArray?)

No additional steps are required. RunMat’s auto-offload planner keeps tensors on the GPU whenever the provider exposes native support. If a provider falls back to the host implementation, the runtime gathers and re-uploads the data transparently so subsequent operations can continue on the GPU. Explicit calls to gpuArray remain available for MATLAB compatibility but are not mandatory.

FAQ

Do K and dims need the same length?

Yes. When you supply the dims argument, the shift vector must have the same number of entries. Each shift is paired with the corresponding dimension.

Can I shift along dimensions that are currently size one?

You can, and the result matches MATLAB: the axis length is one so the shift has no visible effect.

How are negative shifts handled?

They rotate values toward lower indices. Internally RunMat reduces each shift modulo the axis length, so -1 on a length-4 dimension is equivalent to 3.

What happens with empty tensors?

The result remains empty with identical shape metadata. circshift never introduces new elements.

Are logical and string arrays supported?

Yes. Logical arrays stay logical, and string arrays preserve their individual strings while rotating their positions.

Can character arrays be shifted along the third dimension?

No. MATLAB character arrays are strictly two-dimensional; RunMat matches this restriction and raises an error if you request dimension three or higher.

Does circshift fuse with other GPU kernels?

When a provider supplies the hook, yes. Otherwise the rotation acts as a residency boundary in fused graphs.

How does circshift interact with complex numbers?

Real and imaginary parts move together. Scalars are unaffected, and arrays retain their complex entries without modification.

What if I pass non-integer shifts?

RunMat enforces MATLAB semantics: shifts must be finite integers. Fractional values raise an error.

Does the builtin allocate new GPU buffers?

Providers may reuse buffers internally, but from the user’s perspective the result is a fresh gpuArray handle that preserves residency information.

See Also

permute, rot90, flip, gpuArray, gather

Source & Feedback