Installation¶

BitLogic is a pure-Python PyTorch library (no custom CUDA kernels). We ship it with uv — a fast, reproducible package manager that handles virtual environments, dependency resolution, and the CPU/GPU PyTorch indexes in one tool.

1. Prerequisites¶

Component	Minimum	Notes
Python	3.10+	Type-hint syntax requires it
PyTorch	2.6+	Installed automatically via an extra
NumPy	1.19+	Installed automatically
CUDA	Optional	Only needed for GPU builds; you don't install CUDA yourself — the right torch wheel brings it

Install uv first (one-time, takes a few seconds):

curl -LsSf https://astral.sh/uv/install.sh | sh

See the uv install docs for Windows / alternative methods.

2. Installing BitLogic¶

Clone the repo and sync with one of the hardware extras. uv sync creates a .venv/, resolves the dependency graph, pulls the right torch wheel from the PyTorch index, and installs BitLogic in editable mode — all in one step.

git clone https://github.com/aplesner/bitlogic.git
cd bitlogic

# --- pick ONE of these ---
uv sync --extra cpu         # CPU-only torch (Linux/macOS/Windows)
uv sync --extra cu128       # CUDA 12.8 torch (Linux/Windows + NVIDIA GPU)

Then activate the env and check it works:

source .venv/bin/activate
python -c "import bitlogic, torch; print(bitlogic.__version__, torch.__version__, torch.cuda.is_available())"

You can also run one-off commands without activating the env:

uv run python -c "import bitlogic; print(bitlogic.__version__)"

Development install¶

Add the dev extra on top of the hardware extra you picked:

uv sync --extra cpu --extra dev         # or: --extra cu128 --extra dev

That pulls in pytest and ruff (version bumps use uv version --bump, no separate tool needed). See Contributing for the full workflow.

Docs install¶

uv sync --extra cpu --extra docs
uv run mkdocs serve        # preview at http://localhost:8000

3. Without uv (classic pip)¶

If you really can't use uv, pip still works — you just have to pick the right torch index manually:

# CPU
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -e .

# CUDA 12.8
pip install torch --index-url https://download.pytorch.org/whl/cu128
pip install -e .

The [cpu] / [cu128] extras in pyproject.toml are wired up through [tool.uv.sources], so they only work under uv. Plain pip install .[cu128] will fall back to PyPI torch (CPU wheels) — which is why we recommend uv.

4. Publishing (maintainers)¶

bitlogic itself is a platform-independent pure-Python wheel. Build and publish with --no-sources so the pytorch-index routing isn't baked into the published metadata:

uv build --no-sources          # creates dist/bitlogic-X.Y.Z-py3-none-any.whl
uv publish                      # to PyPI (configure credentials first)

5. Troubleshooting¶

"No solution found when resolving dependencies" — you probably forgot to pass --extra cpu or --extra cu128. Torch isn't in the core deps; it only comes in via an extra.

Mixing CPU and CUDA extras — not allowed; they're declared as conflicts. Delete .venv/ and uv sync --extra <other> if you want to switch.

CUDA version mismatch with the cluster driver — pick a matching torch wheel. If the cluster has older drivers, use --extra cpu instead.

Old setup.py / requirements.txt — gone; everything lives in pyproject.toml now. If you have an existing .venv from before, nuke it with rm -rf .venv and re-run uv sync.