np.roll()是numpy专为循环移位设计的函数，将数组沿指定轴整体平移，越界元素从另一端绕回；它返回新数组、不修改原数组，支持正负整数偏移（浮点自动取整）、自动模长处理，并通过axis参数控制多维数组的滚动方向。
numpy.roll 是什么，它到底怎么移动元素
numpy.roll 不是“旋转矩阵”或“翻转数组”，而是把数组沿指定轴整体平移：超出边界的元素会从另一端绕回来。比如 np.roll([1, 2, 3, 4], shift=1) 得到 [4, 1, 2, 3]（右移1位），shift=-2 就是左移2位 → [3, 4, 1, 2]。
关键点：它不修改原数组，而是返回新数组；shift 支持正负整数和浮点数（浮点会向下取整）；多维数组必须用 axis 明确指定操作轴，否则默认全展平再 roll，容易出错。
- 一维数组直接传
shift即可 - 二维数组若想按行滚动，加
axis=1；按列滚动则用axis=0 -
shift值可以大于数组长度，numpy.roll会自动对长度取模，np.roll(a, 10)和np.roll(a, 10 % len(a))等价
为什么 np.roll([1,2,3], 1) 返回 [3,1,2] 而不是 [2,3,1]
这是最常见的理解偏差：很多人以为“shift=1”是“每个元素向右挪一位”，实际逻辑是“整个数组向右滑动1格，右边掉出去的补到左边”。所以末尾元素 3 移出后，从左边插回 —— 效果就是 [3, 1, 2]。
如果你想要“每个元素往右走一位”的效果（即 [2, 3, 1]），那其实是 shift = -1：左移1位，首元素 1 掉出去，从右边补回。
- 右移 n 位 ⇔
shift = n - 左移 n 位 ⇔
shift = -n - 验证技巧：用
a[(-shift) % len(a):] + a[:(-shift) % len(a)]手动切片对比结果
在二维数组中 roll 某一行或某一列的正确写法
直接对二维数组调 np.roll(a, 1) 会先展平、roll、再 reshape 回原 shape，通常不是你想要的。真要 roll 第 2 行（索引为 1），得先切片再 roll：
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
import numpy as np
a = np.array([[1, 2, 3],
[4, 5, 6],
[7, 8, 9]])
# 错误：全局 roll
# np.roll(a, 1) → [[9, 1, 2], [3, 4, 5], [6, 7, 8]]（展平后 roll）
<h1>正确：只 roll 第 1 行（索引 1）</h1><p>a[1] = np.roll(a[1], shift=1) # → [6, 4, 5]</p><h1>或用 axis 参数 roll 所有行（每行独立右移 1）</h1><p>np.roll(a, shift=1, axis=1) # → [[3, 1, 2], [6, 4, 5], [9, 7, 8]]</p>
-
axis=0：对列操作，相当于每列独立 roll -
axis=1：对行操作，相当于每行独立 roll - 不能用
axis指定单行/单列，必须靠索引切片 + 单独 roll - 如果要 roll 多个特定行（如第 0 和第 2 行），得用循环或布尔索引配合
np.where
roll 和切片拼接性能差异大吗？什么时候该换方法
对小数组（np.roll 和手动切片（如 np.concatenate([a[-shift:], a[:-shift]])）性能差别不大；但对大数组，np.roll 内部用 C 实现，比 Python 层切片快 2–3 倍，且内存更友好（避免临时数组拷贝）。
- 当
shift是变量且可能为负时，切片写法容易越界，np.roll自动处理边界 - 滚动多个轴（如
axis=(0,1)）时，np.roll支持元组，切片几乎无法优雅实现 - 唯一要注意的是：
np.roll返回新数组，若需原地修改，必须显式赋值（如a[:] = np.roll(a, 1)）
真正容易被忽略的是 axis 的默认行为——不设 axis 就 flatten，这个隐式转换在调试时经常导致结果和预期差很远，尤其在函数封装里没写清楚 axis 参数时。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
