circshift — Rotate array elements circularly along one or more dimensions in MATLAB and RunMat.
circshift(A, K) circularly rotates elements of A. Positive shifts move toward higher indices with wraparound, and shifts can be supplied per-dimension or with explicit dimension arguments, consistent with MATLAB and RunMat.
Syntax
B = circshift(A, K)
B = circshift(A, K, dim)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input array. |
K | Any | Yes | — | Shift scalar or vector. |
dim | Any | Yes | — | Dimension index scalar or dimension vector. |
Returns
| Name | Type | Description |
|---|---|---|
B | Any | Array with elements circularly shifted. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:circshift:TooManyInputs | More than three input arguments are supplied. | circshift: too many input arguments |
RunMat:circshift:InvalidShift | Shift argument is not a finite real integer scalar/vector. | circshift: invalid shift argument |
RunMat:circshift:InvalidDimensions | Dimension argument is invalid or not compatible with shift argument. | circshift: invalid dimension argument |
RunMat:circshift:UnsupportedInput | Input value type is unsupported for circshift. | circshift: unsupported input type |
RunMat:circshift:Internal | Internal conversion/allocation/provider operations fail. | circshift: internal operation failed |
How circshift works
circshift(A, k)shifts bykpositions 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.Kanddimsmust have the same length; each entry indimsis 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.
Does RunMat run circshift 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 6Shifting 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 6Rotating 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 3Shifting 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 1Rotating 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 1Using circshift with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how circshift changes the result.
Run a small circshift example, explain the result, then change one input and compare the output.
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 Array functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how circshift is executed, line by line, in Rust.
- View the source for circshift in Rust on GitHub
- Learn how the RunMat 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 blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.