cuda-histogram

cuda-histogram 是一个用于 GPU 的直方图填充库。该库试图遵循 UHI，并保持其 API 与 boost-histogram 和 hist 类似。

cuda-histogram 的主要功能

• 使用 CuPy 实现了 boost-histogram 的一部分功能（详见 API 文档以获取完整列表）
  • 轴
    • Regular 和 Variable 轴
      • edges()
      • centers()
      • index(...)
      • ...
  • 直方图
    • fill(..., weight=...)（包括 Nan 流量）
    • 使用切片进行简单的索引（见下例）
    • values(flow=...)
    • variance(flow=...)
• 允许用户将生成的 GPU 直方图分离到 CPU -
  • to_boost() - 转换为 boost-histogram.Histogram
  • to_hist() - 转换为 hist.Hist

该库的近期目标 -

• 实现 Categorical 轴的支持（内部存在但需要重构以匹配 boost-histogram 的 API）
• 改进索引（__getitem__）以与 boost-histogram 的 API 完全匹配

安装

cua-histogram 可在 PyPI 以及 conda 上找到。可以使用 pip 安装该库 -

pip install cuda-histogram

或使用 conda -

conda install -c conda-forge cuda-histogram

用法

理想情况下，用户希望创建一个 cuda-histogram，在 GPU 上填充值，并将填充的直方图转换为 boost-histogram/Hist 对象以访问所有 UHI 功能。

创建直方图

import cuda_histogram; import cupy as cp

ax1 = cuda_histogram.axis.Regular(10, 0, 1)
ax2 = cuda_histogram.axis.Variable([0, 2, 3, 6])

h = cuda_histogram.Hist(ax1, ax2)

>>> ax1, ax2, h
(Regular(10, 0, 1), Variable([0. 2. 3. 6.]), Hist(Regular(10, 0, 1), Variable([0. 2. 3. 6.])))

填充直方图

API 中的差异（来自 boost-histogram） -

• 有一个额外的 NaN 流量
• 仅接受 CuPy 数组

h.fill(cp.random.normal(size=1_000_000), cp.random.normal(size=1_000_000))  # set weight=... for weighted fills

>>> h.values(), type(h.values())  # set flow=True for flow bins (underflow, overflow, nanflow)
(array([[28532.,  1238.,    64.],
       [29603.,  1399.,    61.],
       [30543.,  1341.,    78.],
       [31478.,  1420.,    98.],
       [32692.,  1477.,    92.],
       [32874.,  1441.,    96.],
       [33584.,  1515.,    88.],
       [34304.,  1490.,   114.],
       [34887.,  1598.,   116.],
       [35341.,  1472.,   103.]]), <class 'cupy.ndarray'>)

索引轴和直方图

API 中的差异（来自 boost-histogram） -

• underflow 索引为 0 而不是 -1
• ax[...] 将返回一个 cuda_histogram.Interval 对象
• 不执行插值
• Hist 索引应在 bin 边缘的范围内，而不是整数

>>> ax1.index(0.5)
array([6])

>>> ax1.index(-1)
array([0])

>>> ax1[0]
<Interval ((-inf, 0.0)) instance at 0x1c905208790>

>>> h[0, 0], type(h[0, 0])
(Hist(Regular(1, 0.0, 0.1), Variable([0. 2.])), <class 'cuda_histogram.hist.Hist'>)

>>> h[0, 0].values(), type(h[0, 0].values())
(array([[28532.]]), <class 'cupy.ndarray'>)

>>> h[0, :].values(), type(h[0, 0].values())
(array([[28532.,  1238.,    64.]]), <class 'cupy.ndarray'>)

>>> h[0.2, :].values(), type(h[0, 0].values()) # indices in range of bin edges
(array([[30543.,  1341.,    78.]]), <class 'cupy.ndarray'>)

>>> h[:, 1:2].values(), type(h[0, 0].values()) # no interpolation
C:\Users\Saransh\Saransh_softwares\OpenSource\Python\cuda-histogram\src\cuda_histogram\axis\__init__.py:580: RuntimeWarning: Reducing along axis Variable([0. 2. 3. 6.]): requested start 1 between bin boundaries, no interpolation is performed
  warnings.warn(
(array([[28532.],
       [29603.],
       [30543.],
       [31478.],
       [32692.],
       [32874.],
       [33584.],
       [34304.],
       [34887.],
       [35341.]]), <class 'cupy.ndarray'>)

转换为 CPU

可以在转换后的直方图上使用 boost-histogram 和 Hist 的所有现有功能。

h.to_boost()

>>> h.to_boost().values(), type(h.to_boost().values())
(array([[28532.,  1238.,    64.],
       [29603.,  1399.,    61.],
       [30543.,  1341.,    78.],
       [31478.,  1420.,    98.],
       [32692.,  1477.,    92.],
       [32874.,  1441.,    96.],
       [33584.,  1515.,    88.],
       [34304.,  1490.,   114.],
       [34887.,  1598.,   116.],
       [35341.,  1472.,   103.]]), <class 'numpy.ndarray'>)

h.to_hist()

>>> h.to_hist().values(), type(h.to_hist().values())
(array([[28532.,  1238.,    64.],
       [29603.,  1399.,    61.],
       [30543.,  1341.,    78.],
       [31478.,  1420.,    98.],
       [32692.,  1477.,    92.],
       [32874.,  1441.,    96.],
       [33584.,  1515.,    88.],
       [34304.,  1490.,   114.],
       [34887.,  1598.,   116.],
       [35341.,  1472.,   103.]]), <class 'numpy.ndarray'>)

获取帮助

• cuda-histogram 的代码托管在 GitHub 上。
• 如果某些功能无法按预期工作，或如果您想请求新功能，请在 GitHub 上创建一个新的 issue。
• 要讨论与 cuda-histogram 相关的内容，请使用 GitHub 上的 discussions 标签。

贡献

欢迎任何形式的贡献！有关设置开发环境的详细信息，请参阅 CONTRIBUTING.md。

致谢

该库最初由 Lindsey Gray、Saransh Chopra 和 Jim Pivarski 开发。

此工作的支持由美国国家科学基金会合作协议 OAC-1836650 和 PHY-2323298（IRIS-HEP）提供。在此材料中表达的意见、发现、结论或建议均为作者的意见，不一定反映美国国家科学基金会的观点。