安装¶
pip / uv¶
从 PyPI 安装最新发布版:
或
可选扩展(extras)¶
核心安装保持轻量。较重的库作为可选扩展,按需延迟导入;调用缺少对应库的功能时,会抛出 ImportError 并给出确切的 pip install "btorch[...]" 命令。
| 扩展 | 安装内容 | 启用功能 |
|---|---|---|
| (核心) | torch, numpy, pandas, scipy, jaxtyping, matplotlib | 模型、连接组工具、静态绘图 |
btorch[io] |
xarray, zarr, numcodecs, h5py, hdf5plugin | btorch.io.serialization(xarray/Zarr 保存与加载)、btorch.utils.hdf5_utils |
btorch[config] |
omegaconf, pyyaml | btorch.utils.conf(OmegaConf 工具)、btorch.utils.yaml_utils |
btorch[fast] |
numba, polars | 可选加速器(六边形网格运算、use_polars 聚合);没有它们结果相同 |
btorch[gpu] |
triton | btorch.utils.bench.do_bench 中的 GPU 事件计时 |
btorch[analysis] |
powerlaw, nolds, fastdtw | 雪崩/DFA 临界性、Lyapunov 与熵估计、DTW 轨迹聚类 |
btorch[viz] |
networkx, plotly | 交互式六边形绘图(btorch.visualisation.hex.interactive)、图绘制 |
btorch[sparse] |
torch_scatter, torch_sparse | 可选、需显式选择的稀疏内核后端(见下文;需要 PyG wheel) |
btorch[examples] |
torchvision, seaborn, tqdm | examples/ 中的脚本 |
btorch[all] |
以上所有扩展 | 全部功能 |
CUDA 支持¶
btorch 依赖 PyTorch 2.3 或更新版本(torch.compiler.is_compiling)。PyPI 默认提供 CPU 版本的 torch。如需 CUDA,请先安装对应计算平台版本的 PyTorch,再安装 btorch:
或使用 uv:
详见 PyTorch Get Started 页面了解其他 CUDA / ROCm 版本。
conda / mamba¶
environment.yml 通过 conda-forge 和 PyG 通道捆绑了含 CUDA 的 PyTorch、pytorch_sparse 及所有依赖:
conda env create -n btorch -f https://github.com/Criticality-Cognitive-Computation-Lab/btorch/raw/refs/heads/main/environment.yml
conda activate btorch
或使用 mamba:
mamba env create -n btorch -f https://github.com/Criticality-Cognitive-Computation-Lab/btorch/raw/refs/heads/main/environment.yml
mamba activate btorch
从版本控制安装¶
Btorch 迭代快速。如需最新的未发布改动,直接从仓库安装:
Gitee 镜像:
可编辑安装(开发)¶
克隆仓库并以可编辑模式安装:
git clone https://github.com/Criticality-Cognitive-Computation-Lab/btorch.git
cd btorch
pip install -e . --config-settings editable_mode=strict
若使用 uv,克隆并同步 lockfile:
git clone https://github.com/Criticality-Cognitive-Computation-Lab/btorch.git
cd btorch
uv sync --group dev
source .venv/bin/activate
pip install -e . --config-settings editable_mode=strict
CUDA + uv,先安装对应后端版本的 torch:
uv venv .venv-cuda
uv pip install torch --torch-backend auto --python .venv-cuda/bin/python
uv pip install -e . --python .venv-cuda/bin/python
可选:torch_sparse 后端¶
稀疏连接(btorch.models.connection.SparseConnection)只依赖 PyTorch:无需 torch_sparse 即可训练、在 CPU 和 GPU 上运行,并通过 torch.compile(..., fullgraph=True) 编译。
若已安装 torch_sparse,btorch 会将其注册为额外的内核后端。它不会被自动选用;需通过 btorch.sparse.runtime.use_backend("torch_sparse") 显式选择(见稀疏连接指南)。
使用与 PyTorch 和 CUDA 版本匹配的 PyG 仓库 预编译 wheel:
# 以 PyTorch 2.7 + CUDA 12.6 为例
pip install torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-2.7.0+cu126.html
若未安装 torch_sparse,行为不变:使用默认后端。