Getting Started

TensorPlay is built to be read: every step from the Python API down to the C++ core is code you can trace, run, and modify. This page gets a working installation on your machine and runs the first examples.

Install

Stable release (CPU wheels)

pip install tensorplay --upgrade

CUDA build

CUDA wheels are published to the TensorPlay wheel index and are picked per CUDA major version:

# CUDA 13.0
pip install tensorplay --index-url https://download.tensorplay.cn/whl/cu130/ --extra-index-url https://pypi.org/simple

Nightly builds

pip install --pre tensorplay --index-url https://download.tensorplay.cn/whl/nightly/cpu/ --extra-index-url https://pypi.org/simple

Nightly versions follow X.Y.0.dev<UTC date> with a +cpu or +cuXXX local tag.

Build from source

Prerequisites

Requirement	Version / Notes
Python	>= 3.10, < 3.14
CMake	>= 3.18, < 4.0
C++ compiler	C++20 capable (MSVC 2022, GCC, or Clang)
CUDA Toolkit	optional, auto-detected
ROCm	optional (7.2.x), mutually exclusive with CUDA
Ninja	required on Windows

Steps

git clone https://github.com/lexing-2026/TensorPlay.git
cd TensorPlay
pip install -r requirements-build.txt
pip install .                        # full build
pip install -e . --no-build-isolation  # editable install for kernel development

The version number comes from the single source of truth version.txt; development installs carry a +git<sha> suffix.

Build options

Options are passed as environment variables — no -D CMake flags needed:

Variable	Effect
USE_CUDA=OFF	CPU-only build
USE_ROCM=ON	AMD/HIP backend (exclusive with CUDA)
CMAKE_CUDA_ARCHITECTURES	e.g. "70;75;86"
BUILD_TESTS=ON	also build the C++ test suite
MAX_JOBS	cap compile parallelism
DEBUG	debug build

Quick start

Automatic differentiation

import tensorplay as tp

x = tp.Tensor([[1.0, 2.0], [3.0, 4.0]], requires_grad=True)
y = tp.Tensor([[5.0, 6.0], [7.0, 8.0]], requires_grad=True)

z = x.matmul(y) + tp.ones_like(x)
loss = z.sum()
loss.backward()

print(x.grad)  # [[6., 6.], [6., 6.]]

Under the hood, TPX records each operation into an explicit DAG and replays the chain rule node by node — every edge of that graph is code you can step through. See Architecture.

Defining a neural network

import tensorplay as tp
from tensorplay.nn import Module, Linear, ReLU, Sigmoid

class MLP(Module):
    def __init__(self, input_dim: int, hidden_dim: int, output_dim: int):
        super().__init__()
        self.fc1 = Linear(input_dim, hidden_dim)
        self.relu = ReLU()
        self.fc2 = Linear(hidden_dim, output_dim)
        self.sigmoid = Sigmoid()

    def forward(self, x: tp.Tensor) -> tp.Tensor:
        x = self.relu(self.fc1(x))
        return self.sigmoid(self.fc2(x))

model = MLP(10, 32, 1)
print(model)  # auto-generated architecture visualization

Training loop

from tensorplay.data import DataLoader, TensorDataset

train_data = TensorDataset(tp.randn(100, 10), tp.randn(100, 1))
train_loader = DataLoader(dataset=train_data, batch_size=8, shuffle=True)

for batch_x, batch_y in train_loader:
    predictions = model(batch_x)
    # ... compute loss, call loss.backward(), step the optimizer

Next steps

• Structured tutorials (linear regression from scratch, MNIST CNN, custom datasets, .mega serialization): tensorplay.cn
• Component deep dives: Architecture
• Common issues: FAQ
• Contribution workflow: CONTRIBUTING.md