Environment & Installation¶

This guide covers setting up a pytanga development environment and using pytanga as a dependency in your own project.

Prerequisites¶

Python ≥ 3.12
uv (Python package manager and virtual‑environment tool)
C++ compiler — not needed for most users. pip / uv install precompiled wheels that work out of the box on Linux and Windows. A compiler is only required if you need an algebra configuration not covered by the precompiled set (e.g. a custom dimension or signature). See Compiler Setup for per-platform instructions.

Compiler Setup¶

pytanga compiles its C++ binding on-demand using CMake and a C++17 compiler. The [compile] extra (pip install "tanga-py[compile]") pulls in cmake, ninja, and pybind11 via pip — but you must provide the C++ compiler separately.

Choose your platform below.

Linux¶

Install GCC (recommended) or Clang via your package manager:

# Ubuntu / Debian
sudo apt install build-essential g++-13

# Fedora
sudo dnf install gcc-c++

# Arch
sudo pacman -S gcc

Verify:

g++ --version   # should show ≥ 13.x

Alternatively, install Clang:

# Ubuntu / Debian
sudo apt install clang-14

# Fedora
sudo dnf install clang

macOS¶

Install the Xcode Command Line Tools (provides clang++):

xcode-select --install

Or install GCC via Homebrew:

brew install gcc

Verify:

clang++ --version   # should show ≥ 14.x

Windows¶

You need the Microsoft Visual C++ (MSVC) toolchain. There are several ways to get it — pick whichever fits your setup:

Option A: Visual Studio Build Tools (recommended — lightest install)¶

The Build Tools are a standalone, IDE-free package that supplies just the MSVC compiler, linker, and headers (~2–3 GB). This is all pytanga needs.

Go to the Visual Studio downloads page.

Note: the page prominently shows full IDE editions (Community, Professional, Enterprise) at the top. Scroll down past those to the "Tools for Visual Studio" section — you'll find "Build Tools for Visual Studio 2022" there with its own download button.
Run the installer and select the "Desktop development with C++" workload.
After installation, open the "Developer Command Prompt for VS 2022" from the Start Menu and run all pip / uv commands from that terminal.

Option B: Full Visual Studio IDE (Community / Professional / Enterprise)¶

If you already have Visual Studio installed for other development work, or prefer the full IDE, any edition works — just make sure the "Desktop development with C++" workload is selected during installation (or added afterwards via the Visual Studio Installer).

The free Community Edition is available at visualstudio.microsoft.com/vs/community/.

Once installed, use the "Developer Command Prompt for VS 2022" or launch VS Code from it (code .).

Option C: VS Code with C++ Extension¶

Install the C/C++ extension (ms-vscode.cpptools) in VS Code.
Install the Build Tools from Option A (or the full IDE from Option B).
Open your project folder; VS Code should detect MSVC automatically.

Verify (from the Developer Command Prompt):

cl   :: should print the Microsoft C/C++ compiler version

Important: CMake on Windows must be run from a terminal that has MSVC in its PATH. The "Developer Command Prompt" configures this automatically. Without it, cmake will report No CMAKE_CXX_COMPILER could be found.

Alternative: WSL (Windows Subsystem for Linux)¶

If you prefer a Linux toolchain on Windows, install WSL and a Linux distribution (Ubuntu recommended), then follow the Linux instructions above inside the WSL terminal.

# From an Administrator PowerShell:
wsl --install -d Ubuntu

After installation, open the Ubuntu terminal and follow the Linux instructions.

Development Setup¶

Clone the repository and sync the dev dependency group:

git clone https://github.com/dodeka12/tanga.git
cd tanga

# Create .venv and install all dev tooling
uv sync --group dev

What `--group dev` installs¶

The dev group (defined in pyproject.toml under [dependency-groups]) pulls in:

Package	Purpose
`pytest>=9.1.1`	Test runner
`ruff>=0.14.0`	Linter and formatter
`tanga-py[compile,examples]`	The pytanga package itself plus its `compile` and `examples` extras

The extras in turn provide:

Extra	Packages	Needed for
`compile`	`pybind11`, `cmake`, `ninja`	Compiling the C++ binding from source
`examples`	`scipy`, `ipykernel`, `jupyter`, `ipython`	Running iterative solvers and jupyter notebooks in example scripts under `py/examples/`

After syncing you can run tests, lint, and execute example scripts:

uv run pytest
uv run ruff check py/
uv run python py/examples/ga/numerics/solver_rotor_estimation.py

Using pytanga as a Dependency¶

Pre-Compiled Wheels (recommended)¶

If a pre-compiled wheel exists for your platform, simply:

pip install tanga-py

No C++ compiler or build tools are needed. pytanga ships precompiled bindings for the five most common algebra configurations:

Algebra	dim	sig	dtype
E3 (Euclidean)	3	0	float64
P3 (Projective)	4	0	float64
N3 / PGA3 (Conformal/Plane-based)	5	16	float64
E3 modular (crypto)	3	0	int64
Sparse high-dim (crypto)	10	0	int64

Source Compilation (custom algebras)¶

If you need an algebra not covered by the precompiled set (e.g. a custom dimension, signature, or dtype), add the compile extra:

pip install "tanga-py[compile]"

This pulls in cmake, ninja, and pybind11 for on-the-fly compilation. You also need a C++ compiler — see Compiler Setup.

Note: precompiled wheels are available for Linux (x86_64) and Windows (win_amd64). If you are on one of these platforms and only need the five standard algebra configurations, you do not need the compile extra or a C++ compiler.

For the example scripts and iterative solvers, add the examples extra as well:

pip install "tanga-py[compile,examples]"

With uv¶

In your own project, add pytanga with uv:

uv add tanga-py
uv add "tanga-py[compile]"
uv add "tanga-py[compile,examples]"

Virtual environment¶

The uv commands above automatically create and manage a .venv/ for your project. There is nothing else to set up — uv handles the Python interpreter, package installation, and environment activation transparently via uv run.