SFT-Torch

SFT-Torch is a Torch-native, data-agnostic compiler from structured data to spectral operator programs.

DataView -> Lift -> OperatorSpec -> SpectralProgram -> W / kappa / tail / codec

The core does not know about domains such as audio, images, astronomy, or text. It knows data topology and operator lifts:

• sequence(x).fourier_bands(...)
• grid(x).laplacian(...)
• graph(edge_index, n).laplacian(...)
• tokens(...).transition(...)
• operator(A0, basis)

Example:

import sft_torch as sft

program = sft.grid(blocks).laplacian(weight=0.3).compile("cuda")
kappa = program.kappa()
tail = program.tail()

This package is intentionally separate from sft while it is being developed. The Hermitian lane is the default production path. The non-Hermitian lane is now coverage-gated for the theory stands listed in THEORY_COVERAGE.md: biorthogonal W, Hessian/proxy diagnostics, projector branch tracking, EP/Puiseux/Jordan helpers, and conditioned continuation.

Install

From a local checkout:

python3 -m pip install -e ".[dev,parity]"

For a wheel/sdist release, the PyPI package name is sftransform and the Python import name is sft_torch:

python3 -m pip install sftransform

Build and install a local release artifact:

python3 -m pip install build
python3 -m build
python3 -m pip install dist/*.whl
python3 -c "import sft_torch; print(sft_torch.__version__)"

Install directly from the repository:

python3 -m pip install "git+ssh://git@github.com/dimaq12/spectral-flow-torch.git"

Quickstart

import torch
import sft_torch as sft

x = torch.sin(torch.linspace(0, 8, 256, dtype=torch.float64))
program = sft.sequence(x).fourier_bands(n_bands=16).compile("cpu")

W = program.W
predicted = program.predict(torch.zeros(program.M, dtype=program.dtype))
tail = program.tail(strict=False)

Production Readiness

The current Hermitian layer is a production candidate, not just a smoke demo. The test suite is split by intent:

• unit: fast deterministic contracts and guardrails.
• parity: numeric parity against the NumPy/SciPy sft.OperatorFamily.
• integration: cross-layer Omega/commonOperators and SFT x Omega gates.
• realdata: tiny deterministic fixtures for sequence, grid, graph, tokens, and explicit operator lifts.
• slow and cuda: optional paths for profiler/GPU validation.

Run the default CPU suite:

python3 -m pytest

Run targeted production groups:

python3 -m pytest -m parity
python3 -m pytest -m integration
python3 -m pytest -m realdata
python3 -m pytest -m "not slow and not cuda"

Run grouped theory coverage validation:

python3 -m sft_torch.validate --out-dir .benchmarks/validation

Run CUDA/profiler checks when a CUDA build is available:

python3 -m pytest -m cuda

Benchmarks

sft_torch.bench reports machine-readable metrics for CPU/CUDA runs:

python3 -m sft_torch.bench core --json
python3 -m sft_torch.bench graph --n 1000 --k 64 --device cuda --json
python3 -m sft_torch.bench grid --n 32 --batch 2048 --device cuda --json
python3 -m sft_torch.bench tail --n 7680 --json
python3 -m sft_torch.bench nonhermitian --n 6 --k 3 --batch 4 --json

The installed console command is also available as:

sftransform-bench core --json

Each result includes time_ms, device, dtype, batch, N, M, eigh_count, svd_count, basis_kind, materialized_elements, peak_memory, throughput, accuracy where applicable, and the selected execution plan.

Store benchmark output outside source-controlled files:

python3 -m sft_torch.bench core --json --output .benchmarks/core.json

Release Docs

• RELEASE_NOTES.md records the 0.1.0 scope and validation commands.
• THEORY_COVERAGE.md maps theory/commonOperators stands to package coverage.
• NONHERMITIAN_ROADMAP.md tracks the remaining future biorthogonal / EP work.
• PUBLISHING.md records the PyPI build, upload, and install verification flow.

Known Gaps

• CUDA tests are skip-if-no-CUDA in this workspace.
• Multi-slice grid[B,H,W] batching is explicit via batch_mode="first", "mean", or "block"; richer temporal/video operators remain future work.
• Directed graph Laplacian is implemented as an explicit non-Hermitian out-degree lift. Normalized graph Laplacian is implemented for undirected graphs.
• The tail layer exposes strict Omega mode for k | N; convenience mode is explicit and should not be used as a proof gate.
• Pseudospectrum and numerical-range dashboards are optional diagnostics and are intentionally kept out of hot paths.
• Fully automatic global EP-safe inverse workflows remain roadmap work; local Puiseux/Jordan chart helpers are coverage-gated.