tensorstudio 1.0.1

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.1 is a CPU-only stable API foundation. It is eager-only, intentionally small, and not a replacement for mature ML frameworks.

Install

From PyPI:

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 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 benchmark_all.py
python benchmarks/benchmark_report.py

benchmark_all.py writes benchmarks/results.md and includes explicit win columns for NumPy, TensorFlow, PyTorch, and JAX when those libraries are available locally.

On one Windows CPython 3.10 run for 1.0.1, TensorStudio beat NumPy on 13 small activation/reduction benchmark cases and lost on 76 NumPy-comparable cases. Against PyTorch CPU 2.12.1+cpu, TensorStudio won 71 local cases and lost 23. The strongest local wins were small eager operations where framework dispatch overhead dominates; larger matrix multiplication, larger transcendental activations, and larger autograd workloads remain faster in PyTorch and NumPy. See benchmarks/results.md for the full table, platform details, and exact timings.

Snapshot from that local run:

operation	shape	TensorStudio	NumPy	PyTorch CPU	TS vs NumPy	TS vs PyTorch
sigmoid	(32,)	0.0018 ms	0.0036 ms	0.0575 ms	2.0414x	32.2110x
mean	(32,)	0.0016 ms	0.0069 ms	0.0112 ms	4.4051x	7.1262x
chain_relu	(128,)	0.0086 ms	0.0039 ms	0.0567 ms	0.4488x	6.5977x
matmul	(256, 256)	2.4215 ms	0.4027 ms	0.0832 ms	0.1663x	0.0343x
elementwise_backward	(1024,)	2.3527 ms	n/a	0.1887 ms	n/a	0.0802x

Speedup is competitor median / TensorStudio median, so values above 1.0x favor TensorStudio.

Do not treat these results as universal. TensorStudio does not 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]"
python test_all.py --skip-build
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

• python test_all.py passes locally.
• 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 BLAS-backed matrix multiplication 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.