tensorstudio 1.0.0rc2

TensorStudio is a compact C++ tensor and autograd engine with a Python API for learning, experimentation, and lightweight ML workloads.

TensorStudio

TensorStudio is a compact C++ tensor and autograd engine with a Python API for learning, experimentation, and lightweight ML workloads.

TensorStudio 1.0.0rc2 is a release candidate for a CPU-only stable API foundation. It is eager-only, intentionally small, and not a replacement for mature ML frameworks. The final 1.0.0 version should only be tagged after the Windows, Linux, and macOS release checklist passes.

Install

From PyPI, once release-candidate wheels are published:

python -m pip install tensorstudio

From a source checkout:

python -m pip install -U pip
python -m pip install -e ".[dev]"

Build source and wheel distributions:

python -m build
python -m twine check dist/*

End users should install wheels and should not need CMake. Source builds require a C++20 compiler because the native extension is implemented in C++.

Platform Setup

Windows is the primary release target. Use Python from python.org and install Microsoft C++ Build Tools or Visual Studio with the Desktop development with C++ workload before building from source:

python -m pip install -U pip
python -m pip install -e ".[dev]"
pytest -q

Linux source builds need GCC or Clang, CMake, and Python development headers:

python -m pip install -U pip
python -m pip install -e ".[dev]"
pytest -q

macOS source builds need Xcode Command Line Tools:

xcode-select --install
python -m pip install -U pip
python -m pip install -e ".[dev]"
pytest -q

Quickstart

import tensorstudio as ts

x = ts.tensor([[1.0, 2.0], [3.0, 4.0]])
y = ts.ones((2, 2))

print((x + y).tolist())
print((x @ y).numpy())
print(x.reshape((4,)).tolist())

Tensor API

TensorStudio supports CPU tensors with float32, float64, int32, int64, and bool dtypes.

import tensorstudio as ts

ts.manual_seed(7)

a = ts.zeros((2, 3))
b = ts.rand((2, 3))
c = ts.eye(3)
d = ts.linspace(0.0, 1.0, 5)

print(a.shape, a.strides, a.device, a.is_contiguous)
print((b.clamp(0.2, 0.8) + 1).mean().item())
print(c.tolist(), d.tolist())
print(ts.zeros_like(b).shape, ts.randn_like(b, seed=11).dtype)

Autograd

import tensorstudio as ts

x = ts.tensor([1.0, 2.0, 3.0], requires_grad=True)
loss = (x * x).mean()
loss.backward()

print(x.grad.tolist())

Use no_grad() when you want eager computation without recording a graph:

with ts.no_grad():
    y = x * 2

Neural Networks

import tensorstudio as ts
from tensorstudio import nn, optim

ts.manual_seed(0)

model = nn.Sequential(nn.Linear(1, 8), nn.Tanh(), nn.Linear(8, 1))
optimizer = optim.SGD(model.parameters(), lr=0.05, momentum=0.9)
scheduler = optim.StepLR(optimizer, step_size=50, gamma=0.5)
criterion = nn.MSELoss()

x = ts.tensor([[0.0], [1.0], [2.0], [3.0]])
y = ts.tensor([[1.0], [3.0], [5.0], [7.0]])

for _ in range(100):
    optimizer.zero_grad()
    loss = criterion(model(x), y)
    loss.backward()
    optim.clip_grad_norm_(model.parameters(), max_norm=10.0)
    optimizer.step()
    scheduler.step()

print(loss.item())
print(model.state_dict().keys())
print(model.parameter_count())

DataLoader

import tensorstudio as ts
from tensorstudio.data import DataLoader, TensorDataset

dataset = TensorDataset(ts.arange(6).reshape((6, 1)), ts.arange(6))
loader = DataLoader(dataset, batch_size=2, shuffle=True, seed=42)

for features, targets in loader:
    print(features.shape, targets.shape)

The v1 release candidate DataLoader is intentionally single-process so it works cleanly on Windows without multiprocessing setup.

Performance

TensorStudio is optimized for small-to-medium CPU eager workloads, but performance is still experimental. Benchmarks live in benchmarks/ and can be run locally:

python benchmarks/benchmark_report.py

On one Windows CPython 3.10 run for 1.0.0rc2, TensorStudio beat NumPy on 11 small activation/reduction benchmark cases and lost on 78 NumPy-comparable cases. The strongest local wins were small sigmoid, sum, and mean cases; medium elementwise operations and matrix multiplication remain slower than NumPy. The C++ contiguous matmul fast path is much faster than the original naive storage-access loop, but it is not a BLAS replacement. See benchmarks/results.md for the full table, platform details, and exact timings.

Snapshot from that local run:

operation	shape	TensorStudio median	NumPy median	speedup	result
sigmoid	(1,)	0.0016 ms	0.0036 ms	2.2170x	win
mean	(1,)	0.0014 ms	0.0081 ms	5.8562x	win
mean	(8,)	0.0016 ms	0.0079 ms	5.0005x	win
add	(16384,)	0.0100 ms	0.0037 ms	0.3682x	loss
matmul	(256, 256)	4.1393 ms	0.4222 ms	0.1020x	loss

Speedup is NumPy median / TensorStudio median, so values above 1.0x favor TensorStudio. The matmul result is from the optimized C++ contiguous path; a pre-optimization run was about 259 ms for the same (256, 256) case on this machine.

Do not treat these results as universal. TensorStudio does not currently claim to be faster than NumPy, TensorFlow, PyTorch, or JAX overall.

Save And Load

import tensorstudio as ts
from tensorstudio import nn

model = nn.Linear(2, 1)
ts.save({"model": model.state_dict()}, "checkpoint.tsmodel")
checkpoint = ts.load("checkpoint.tsmodel")

Serialization uses pickle. Loading pickle files from untrusted sources is unsafe because pickle can execute arbitrary code.

Development

python -m pip install -e ".[dev,docs]"
ruff check .
mypy python/tensorstudio
pytest -q
python -m build
python -m twine check dist/*

The native extension module is tensorstudio._C, built with CMake, pybind11, scikit-build-core, and C++20.

Release Checklist

• ruff check . passes.
• mypy python/tensorstudio passes.
• pytest -q passes on Windows, Linux, and macOS.
• python -m build passes.
• python -m twine check dist/* passes.
• Benchmarks are generated and performance claims match the data.
• Clean wheel installs pass on Windows, Linux, and macOS.
• Clean sdist installs pass on Windows, Linux, and macOS.
• Examples run on all platforms.
• Docs match the implemented feature set.
• No PyPI tokens are committed or printed.
• TestPyPI is verified before a real PyPI release.

Publishing

GitHub Actions build wheels with cibuildwheel. The publish workflow is designed for PyPI trusted publishing with id-token: write; it should not hardcode PyPI tokens or print secrets.

Current Limitations

• CPU backend only.
• Eager execution only.
• No CUDA or Metal backend yet.
• No graph compiler or distributed runtime.
• No convolution layers yet.
• No sparse tensors or advanced indexing.
• Limited dtype casting.
• Experimental performance; benchmarks are local references only.
• Pickle serialization is for trusted TensorStudio objects only.

Roadmap

• CUDA backend
• Graph/JIT mode
• Convolution ops
• Dataset utilities
• Model zoo examples
• ONNX import/export
• Improved memory allocator
• SIMD kernels
• Multithreaded ops

License

TensorStudio is licensed under the MIT License.