circshift — Rotate arrays circularly along one or more dimensions.

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 circshift works in 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.

How circshift runs on the GPU

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.

GPU memory and residency

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.

Examples

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 =
     5     8    11     2
     6     9    12     3
     4     7    10     1

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

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.

What does circshift do in MATLAB?

circshift(A, K) circularly shifts the elements of array A by K positions. Elements shifted off one end wrap around to the other. Negative shifts move elements in the opposite direction.

How do I shift rows and columns separately with circshift?

Use circshift(A, [rowShift, colShift]) to shift rows and columns independently. For example, circshift(A, [1, -2]) shifts rows down by 1 and columns left by 2.

Does circshift support GPU arrays?

Yes. In RunMat, circshift works on GPU arrays and can fuse with other GPU kernels for efficient execution without extra memory allocations.

Related functions to explore

These functions work well alongside circshift. Each page has runnable examples you can try in the browser.

permute, rot90, flip, gpuArray, gather, cat, diag, fliplr, flipud, horzcat, ipermute, kron, repmat, reshape, squeeze, tril, triu, vertcat

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how circshift works, line by line, in Rust.

• View circshift.rs on GitHub
• Learn how the runtime works
• Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing