tensorstudio 1.5.0__tar.gz → 1.6.0__tar.gz

{tensorstudio-1.5.0 → tensorstudio-1.6.0}/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## Unreleased
 
+## 1.6.0 - 2026-07-07
+
+- Completed the ordered CPU Performance Core roadmap section as one release
+  batch.
+- Added optional CBLAS/Accelerate-backed `matmul` for contiguous `float32` and
+  `float64` matrices when the source build environment exposes a compatible
+  BLAS library and header; portable C++ kernels remain the fallback path.
+- Added a small native C++ CPU thread pool, configurable with
+  `tensorstudio.set_num_threads()` and `TENSORSTUDIO_NUM_THREADS`, and used it
+  for large contiguous elementwise ops, reductions, matrix multiplication,
+  convolution, and pooling forward kernels.
+- Added SIMD-friendly typed `float32`/`float64` contiguous kernels for common
+  elementwise arithmetic and activations, while preserving mixed-dtype fallback
+  behavior.
+- Added a bounded C++ storage reuse pool for tensor allocations, with
+  `TENSORSTUDIO_DISABLE_STORAGE_POOL=1` and
+  `TENSORSTUDIO_STORAGE_POOL_MAX_BLOCK_BYTES` controls.
+- Added `tensorstudio.performance_info()`, `get_num_threads()`, and
+  `set_num_threads()` diagnostics/configuration helpers.
+- Added benchmark threshold support via `benchmark_all.py --check-thresholds`
+  and `benchmarks/thresholds.json`.
+- Expanded performance, CPU backend, and platform docs for BLAS selection,
+  threading, storage reuse, benchmark thresholds, and honest interpretation.
+
+## 1.5.1 - 2026-07-07
+
+- Completed the next ordered correctness-roadmap item with clearer native
+  shape, dtype, and indexing error messages.
+- Broadcasting errors now include the mismatched axis and dimensions.
+- Reshape errors now include requested element counts and inferred-shape
+  context.
+- DType errors now validate Python dtype inputs and list supported dtype names
+  and aliases.
+- Indexing errors now include tensor shape/rank context and the unsupported
+  Python index type/value where practical.
+- Added focused regression tests for the improved diagnostics.
+
 ## 1.5.0 - 2026-07-07
 
 - Completed the next ordered correctness-roadmap item with native C++ view and

{tensorstudio-1.5.0 → tensorstudio-1.6.0}/CMakeLists.txt

@@ -1,11 +1,13 @@
 cmake_minimum_required(VERSION 3.18)
 
-project(tensorstudio VERSION 1.5.0 LANGUAGES CXX)
+project(tensorstudio VERSION 1.6.0 LANGUAGES CXX)
 
 find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)
 set(PYBIND11_FINDPYTHON ON)
 find_package(pybind11 CONFIG REQUIRED)
 
+option(TENSORSTUDIO_ENABLE_BLAS "Enable optional CBLAS-backed matmul when available" ON)
+
 set(TENSORSTUDIO_CORE_SOURCES
   src/core/tensor.cpp
   src/core/dtype.cpp
@@ -19,6 +21,7 @@ set(TENSORSTUDIO_CORE_SOURCES
   src/core/random.cpp
   src/core/serialization.cpp
   src/core/errors.cpp
+  src/core/perf.cpp
 )
 
 set(TENSORSTUDIO_BINDING_SOURCES
@@ -38,6 +41,20 @@ pybind11_add_module(_C MODULE
 target_include_directories(_C PRIVATE include src/bindings)
 target_compile_features(_C PRIVATE cxx_std_20)
 
+if(TENSORSTUDIO_ENABLE_BLAS)
+  find_package(BLAS)
+  if(BLAS_FOUND)
+    include(CheckIncludeFileCXX)
+    check_include_file_cxx(cblas.h TENSORSTUDIO_HAVE_CBLAS_H)
+    target_link_libraries(_C PRIVATE ${BLAS_LIBRARIES})
+    if(APPLE)
+      target_compile_definitions(_C PRIVATE TENSORSTUDIO_HAS_ACCELERATE=1)
+    elseif(TENSORSTUDIO_HAVE_CBLAS_H)
+      target_compile_definitions(_C PRIVATE TENSORSTUDIO_HAS_CBLAS=1)
+    endif()
+  endif()
+endif()
+
 if(MSVC)
   target_compile_options(_C PRIVATE /W4 /permissive-)
 else()

{tensorstudio-1.5.0 → tensorstudio-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: tensorstudio
-Version: 1.5.0
+Version: 1.6.0
 Summary: TensorStudio is a compact C++ tensor and autograd engine with a Python API for learning, experimentation, and lightweight ML workloads.
 Keywords: tensor,autograd,machine-learning,cpp,pybind11
 Author: TensorStudio contributors
@@ -71,8 +71,10 @@ Description-Content-Type: text/markdown
 TensorStudio is a compact C++ tensor and autograd engine with a Python API for
 learning, experimentation, and lightweight ML workloads.
 
-TensorStudio `1.5.0` is a CPU-only stable API foundation. It is eager-only,
-intentionally small, and not a replacement for mature ML frameworks.
+TensorStudio `1.6.0` is a CPU-only stable API foundation with native C++
+threading, storage reuse, SIMD-friendly typed kernels, and optional
+CBLAS/Accelerate matrix multiplication when available. It is eager-only,
+intentionally compact, and not a replacement for mature ML frameworks.
 
 ## Install
 
@@ -344,31 +346,46 @@ python benchmarks/benchmark_report.py
 columns for NumPy, TensorFlow, PyTorch, and JAX when those libraries are
 available locally.
 
-On one Windows CPython 3.10 development run reporting `1.2.0`, TensorStudio
-beat NumPy on 26 small operation benchmark cases and lost on 77
-NumPy-comparable cases. Against PyTorch CPU `2.12.1+cpu`, TensorStudio won 75
-local cases and lost 33. The strongest local wins were small eager operations,
-small contiguous axis reductions, and the simple NumPy convolution/pooling
-references where framework dispatch or Python loops dominate; larger matrix
-multiplication, PyTorch convolution and pooling, larger axis reductions, larger
-transcendental activations, and larger autograd workloads remain faster in
-PyTorch and NumPy.
+Useful runtime diagnostics:
+
+```python
+import tensorstudio as ts
+
+print(ts.performance_info())
+ts.set_num_threads(4)
+```
+
+Run the loose local regression thresholds with:
+
+```bash
+python benchmark_all.py --check-thresholds
+```
+
+On one Windows CPython 3.10 development run reporting `1.6.0`, with
+TensorStudio threads enabled, storage pooling enabled, SSE2 autovectorization
+reported, and no BLAS provider found, TensorStudio beat NumPy on 7 local
+benchmark cases and lost on 96 NumPy-comparable cases. JAX CPU dispatch was
+available on that machine; TensorStudio won 39 local cases and lost 59. The
+strongest local wins were the simple NumPy convolution/pooling reference loops
+and some small JAX-dispatch-heavy eager cases. NumPy and JAX were faster for
+many elementwise, reduction, matrix multiplication, larger activation, and
+autograd workloads.
 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 |
+| operation | shape | TensorStudio | NumPy | JAX CPU dispatch | TS vs NumPy | TS vs JAX |
 |---|---:|---:|---:|---:|---:|---:|
-| `sigmoid` | `(32,)` | 0.0017 ms | 0.0038 ms | 0.0614 ms | 2.1691x | 35.3154x |
-| `mean` | `(32,)` | 0.0029 ms | 0.0131 ms | 0.0186 ms | 4.5638x | 6.4709x |
-| `sum_axis1` | `(16, 16)` | 0.0027 ms | 0.0029 ms | 0.0085 ms | 1.0894x | 3.1408x |
-| `chain_relu` | `(128,)` | 0.0112 ms | 0.0051 ms | 0.0726 ms | 0.4575x | 6.4533x |
-| `matmul` | `(256, 256)` | 4.4121 ms | 0.3779 ms | 0.1669 ms | 0.0856x | 0.0378x |
-| `conv2d_3x3_padding1` | `(1, 1, 8, 8)` | 0.2374 ms | 1.7112 ms | 0.0186 ms | 7.2091x | 0.0784x |
-| `max_pool2d_2x2` | `(1, 1, 16, 16)` | 0.0237 ms | 0.2764 ms | 0.0082 ms | 11.6685x | 0.3462x |
-| `avg_pool2d_2x2` | `(1, 1, 16, 16)` | 0.0198 ms | 0.7431 ms | 0.0073 ms | 37.4930x | 0.3662x |
-| `elementwise_backward` | `(1024,)` | 3.0196 ms | n/a | 0.2254 ms | n/a | 0.0746x |
+| `sigmoid` | `(32,)` | 0.0173 ms | 0.0047 ms | 0.0719 ms | 0.2724x | 4.1608x |
+| `mean` | `(32,)` | 0.0157 ms | 0.0082 ms | 0.0119 ms | 0.5208x | 0.7587x |
+| `sum_axis1` | `(16, 16)` | 0.0159 ms | 0.0031 ms | 0.0131 ms | 0.1924x | 0.8231x |
+| `chain_relu` | `(128,)` | 0.0992 ms | 0.0063 ms | 0.1113 ms | 0.0636x | 1.1219x |
+| `matmul` | `(256, 256)` | 2.5261 ms | 0.3848 ms | 0.2288 ms | 0.1524x | 0.0906x |
+| `conv2d_3x3_padding1` | `(1, 1, 8, 8)` | 0.2120 ms | 1.2975 ms | 0.0959 ms | 6.1191x | 0.4524x |
+| `max_pool2d_2x2` | `(1, 1, 16, 16)` | 0.0286 ms | 0.1613 ms | n/a | 5.6321x | n/a |
+| `avg_pool2d_2x2` | `(1, 1, 16, 16)` | 0.0304 ms | 0.5601 ms | n/a | 18.4457x | n/a |
+| `elementwise_backward` | `(1024,)` | 2.7150 ms | n/a | n/a | n/a | n/a |
 
 Speedup is `competitor median / TensorStudio median`, so values above `1.0x`
 favor TensorStudio.
@@ -465,7 +482,9 @@ tokens or print secrets.
 - CPU backend only.
 - Eager execution only.
 - No CUDA or Metal backend yet.
-- No BLAS-backed matrix multiplication yet.
+- Optional BLAS-backed matrix multiplication depends on the build environment
+  exposing a compatible CBLAS/Accelerate interface; otherwise TensorStudio uses
+  a portable C++ fallback.
 - No graph compiler or distributed runtime.
 - Convolution and pooling support are currently limited to CPU NCHW
   `conv2d`, `max_pool2d`, and `avg_pool2d` style workloads.
@@ -495,9 +514,9 @@ tokens or print secrets.
 - Richer dataset utilities
 - Model zoo examples
 - ONNX import and broader export coverage
-- Improved memory allocator
-- SIMD kernels
-- Multithreaded ops
+- Runtime-dispatched SIMD kernels
+- Better non-BLAS matrix multiplication tiling
+- More threaded backward kernels
 
 ## License
 

{tensorstudio-1.5.0 → tensorstudio-1.6.0}/README.md

@@ -7,8 +7,10 @@
 TensorStudio is a compact C++ tensor and autograd engine with a Python API for
 learning, experimentation, and lightweight ML workloads.
 
-TensorStudio `1.5.0` is a CPU-only stable API foundation. It is eager-only,
-intentionally small, and not a replacement for mature ML frameworks.
+TensorStudio `1.6.0` is a CPU-only stable API foundation with native C++
+threading, storage reuse, SIMD-friendly typed kernels, and optional
+CBLAS/Accelerate matrix multiplication when available. It is eager-only,
+intentionally compact, and not a replacement for mature ML frameworks.
 
 ## Install
 
@@ -280,31 +282,46 @@ python benchmarks/benchmark_report.py
 columns for NumPy, TensorFlow, PyTorch, and JAX when those libraries are
 available locally.
 
-On one Windows CPython 3.10 development run reporting `1.2.0`, TensorStudio
-beat NumPy on 26 small operation benchmark cases and lost on 77
-NumPy-comparable cases. Against PyTorch CPU `2.12.1+cpu`, TensorStudio won 75
-local cases and lost 33. The strongest local wins were small eager operations,
-small contiguous axis reductions, and the simple NumPy convolution/pooling
-references where framework dispatch or Python loops dominate; larger matrix
-multiplication, PyTorch convolution and pooling, larger axis reductions, larger
-transcendental activations, and larger autograd workloads remain faster in
-PyTorch and NumPy.
+Useful runtime diagnostics:
+
+```python
+import tensorstudio as ts
+
+print(ts.performance_info())
+ts.set_num_threads(4)
+```
+
+Run the loose local regression thresholds with:
+
+```bash
+python benchmark_all.py --check-thresholds
+```
+
+On one Windows CPython 3.10 development run reporting `1.6.0`, with
+TensorStudio threads enabled, storage pooling enabled, SSE2 autovectorization
+reported, and no BLAS provider found, TensorStudio beat NumPy on 7 local
+benchmark cases and lost on 96 NumPy-comparable cases. JAX CPU dispatch was
+available on that machine; TensorStudio won 39 local cases and lost 59. The
+strongest local wins were the simple NumPy convolution/pooling reference loops
+and some small JAX-dispatch-heavy eager cases. NumPy and JAX were faster for
+many elementwise, reduction, matrix multiplication, larger activation, and
+autograd workloads.
 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 |
+| operation | shape | TensorStudio | NumPy | JAX CPU dispatch | TS vs NumPy | TS vs JAX |
 |---|---:|---:|---:|---:|---:|---:|
-| `sigmoid` | `(32,)` | 0.0017 ms | 0.0038 ms | 0.0614 ms | 2.1691x | 35.3154x |
-| `mean` | `(32,)` | 0.0029 ms | 0.0131 ms | 0.0186 ms | 4.5638x | 6.4709x |
-| `sum_axis1` | `(16, 16)` | 0.0027 ms | 0.0029 ms | 0.0085 ms | 1.0894x | 3.1408x |
-| `chain_relu` | `(128,)` | 0.0112 ms | 0.0051 ms | 0.0726 ms | 0.4575x | 6.4533x |
-| `matmul` | `(256, 256)` | 4.4121 ms | 0.3779 ms | 0.1669 ms | 0.0856x | 0.0378x |
-| `conv2d_3x3_padding1` | `(1, 1, 8, 8)` | 0.2374 ms | 1.7112 ms | 0.0186 ms | 7.2091x | 0.0784x |
-| `max_pool2d_2x2` | `(1, 1, 16, 16)` | 0.0237 ms | 0.2764 ms | 0.0082 ms | 11.6685x | 0.3462x |
-| `avg_pool2d_2x2` | `(1, 1, 16, 16)` | 0.0198 ms | 0.7431 ms | 0.0073 ms | 37.4930x | 0.3662x |
-| `elementwise_backward` | `(1024,)` | 3.0196 ms | n/a | 0.2254 ms | n/a | 0.0746x |
+| `sigmoid` | `(32,)` | 0.0173 ms | 0.0047 ms | 0.0719 ms | 0.2724x | 4.1608x |
+| `mean` | `(32,)` | 0.0157 ms | 0.0082 ms | 0.0119 ms | 0.5208x | 0.7587x |
+| `sum_axis1` | `(16, 16)` | 0.0159 ms | 0.0031 ms | 0.0131 ms | 0.1924x | 0.8231x |
+| `chain_relu` | `(128,)` | 0.0992 ms | 0.0063 ms | 0.1113 ms | 0.0636x | 1.1219x |
+| `matmul` | `(256, 256)` | 2.5261 ms | 0.3848 ms | 0.2288 ms | 0.1524x | 0.0906x |
+| `conv2d_3x3_padding1` | `(1, 1, 8, 8)` | 0.2120 ms | 1.2975 ms | 0.0959 ms | 6.1191x | 0.4524x |
+| `max_pool2d_2x2` | `(1, 1, 16, 16)` | 0.0286 ms | 0.1613 ms | n/a | 5.6321x | n/a |
+| `avg_pool2d_2x2` | `(1, 1, 16, 16)` | 0.0304 ms | 0.5601 ms | n/a | 18.4457x | n/a |
+| `elementwise_backward` | `(1024,)` | 2.7150 ms | n/a | n/a | n/a | n/a |
 
 Speedup is `competitor median / TensorStudio median`, so values above `1.0x`
 favor TensorStudio.
@@ -401,7 +418,9 @@ tokens or print secrets.
 - CPU backend only.
 - Eager execution only.
 - No CUDA or Metal backend yet.
-- No BLAS-backed matrix multiplication yet.
+- Optional BLAS-backed matrix multiplication depends on the build environment
+  exposing a compatible CBLAS/Accelerate interface; otherwise TensorStudio uses
+  a portable C++ fallback.
 - No graph compiler or distributed runtime.
 - Convolution and pooling support are currently limited to CPU NCHW
   `conv2d`, `max_pool2d`, and `avg_pool2d` style workloads.
@@ -431,9 +450,9 @@ tokens or print secrets.
 - Richer dataset utilities
 - Model zoo examples
 - ONNX import and broader export coverage
-- Improved memory allocator
-- SIMD kernels
-- Multithreaded ops
+- Runtime-dispatched SIMD kernels
+- Better non-BLAS matrix multiplication tiling
+- More threaded backward kernels
 
 ## License
 

{tensorstudio-1.5.0 → tensorstudio-1.6.0}/benchmark_all.py

@@ -3,7 +3,13 @@ from __future__ import annotations
 import argparse
 from pathlib import Path
 
-from benchmarks.benchmark_report import run_benchmarks
+from benchmarks.benchmark_report import (
+    evaluate_thresholds,
+    load_thresholds,
+    render_benchmark_report,
+    run_benchmark_data,
+    write_benchmark_report,
+)
 
 ALL_SECTIONS = {
     "elementwise",
@@ -36,14 +42,36 @@ def main() -> None:
         action="store_true",
         help="Print the full Markdown report after writing it.",
     )
+    parser.add_argument(
+        "--thresholds",
+        type=Path,
+        default=Path("benchmarks") / "thresholds.json",
+        help="Benchmark regression threshold file.",
+    )
+    parser.add_argument(
+        "--check-thresholds",
+        action="store_true",
+        help="Fail if TensorStudio median benchmark times exceed thresholds.",
+    )
     args = parser.parse_args()
 
     selected_sections = set(args.section or ALL_SECTIONS)
-    report = run_benchmarks(selected_sections, args.output)
+    cases, libraries, results = run_benchmark_data(selected_sections)
+    report = render_benchmark_report(cases, libraries, results)
+    write_benchmark_report(report, args.output)
     if args.print:
         print(report)
     else:
         print(f"Wrote benchmark report to {args.output}")
+    if args.check_thresholds:
+        thresholds = load_thresholds(args.thresholds)
+        failures = evaluate_thresholds(thresholds, results)
+        if failures:
+            print("Benchmark threshold failures:")
+            for failure in failures:
+                print(f"- {failure}")
+            raise SystemExit(1)
+        print(f"Benchmark thresholds passed using {args.thresholds}")
 
 
 if __name__ == "__main__":

{tensorstudio-1.5.0 → tensorstudio-1.6.0}/benchmarks/benchmark_report.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import argparse
 import importlib
 import io
+import json
 import os
 import platform
 import statistics
@@ -794,6 +795,12 @@ def _render_report(
     lines.append(f"- Processor: `{platform.processor() or 'unknown'}`")
     lines.append(f"- Python: `{sys.version.split()[0]}`")
     lines.append(f"- TensorStudio: `{ts.__version__}`")
+    with suppress(Exception):
+        perf_info = ts.performance_info()
+        lines.append(f"- TensorStudio threads: `{perf_info['num_threads']}`")
+        lines.append(f"- TensorStudio BLAS enabled: `{perf_info['blas_enabled']}`")
+        lines.append(f"- TensorStudio SIMD level: `{perf_info['simd_level']}`")
+        lines.append(f"- TensorStudio storage pool enabled: `{perf_info['storage_pool_enabled']}`")
     lines.append(f"- NumPy: `{np.__version__}`")
     for library in libraries:
         if library.name in {"TensorStudio", "NumPy"}:
@@ -925,14 +932,55 @@ def _render_report(
     return "\n".join(lines)
 
 
-def run_benchmarks(sections: set[str], output: Path | None) -> str:
+def run_benchmark_data(
+    sections: set[str],
+) -> tuple[list[BenchmarkCase], list[Library], dict[str, Stats]]:
     libraries = _load_libraries()
     cases = _build_cases(sections)
     results = _run_cases(cases, libraries)
-    report = _render_report(cases, libraries, results)
+    return cases, libraries, results
+
+
+def render_benchmark_report(
+    cases: list[BenchmarkCase],
+    libraries: list[Library],
+    results: dict[str, Stats],
+) -> str:
+    return _render_report(cases, libraries, results)
+
+
+def write_benchmark_report(report: str, output: Path | None) -> None:
     if output is not None:
         output.parent.mkdir(parents=True, exist_ok=True)
         output.write_text(report, encoding="utf-8")
+
+
+def load_thresholds(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def evaluate_thresholds(thresholds: dict[str, Any], results: dict[str, Stats]) -> list[str]:
+    failures: list[str] = []
+    for item in thresholds.get("cases", []):
+        category = str(item["category"])
+        operation = str(item["operation"])
+        shape = str(item["shape"])
+        max_ms = float(item["max_median_ms"])
+        key = f"{category}|{operation}|{shape}|TensorStudio"
+        stats = results.get(key)
+        label = f"{category}/{operation}/{shape}"
+        if stats is None:
+            failures.append(f"{label}: no TensorStudio benchmark result was recorded")
+            continue
+        if stats.median_ms > max_ms:
+            failures.append(f"{label}: median {stats.median_ms:.4f} ms exceeded {max_ms:.4f} ms")
+    return failures
+
+
+def run_benchmarks(sections: set[str], output: Path | None) -> str:
+    cases, libraries, results = run_benchmark_data(sections)
+    report = _render_report(cases, libraries, results)
+    write_benchmark_report(report, output)
     return report