sftransform 0.1.0

Torch-native Spectral Flow Transform for data-to-operator spectral programming

SFT-Torch

SFT-Torch is a Torch-native, data-agnostic compiler from structured data to Hermitian / real-symmetric 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. Version 0.1.0 is scoped to the Hermitian Torch lane: torch.linalg.eigh, orthonormal eigenvectors, Hellmann-Feynman W, and Omega tail diagnostics. It is not a full Torch port of sft 0.3 and does not yet implement the full non-Hermitian/EP production stack. Experimental support now includes biorthogonal W, small EP/Puiseux helpers, branch tracking utilities, and conditioned-continuation diagnostics; these APIs are guarded by tests but should still be treated as early theory-epic functionality.

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://[e-mail]/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 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

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.
• NONHERMITIAN_ROADMAP.md tracks the separate 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.
• Full multi-slice grid[B,H,W] batching is still a v1 limitation; the first slice is used by the current lift.
• Directed and normalized graph Laplacians intentionally raise NotImplementedError until their semantics are fixed.
• The tail layer exposes strict Omega mode for k | N; convenience mode is explicit and should not be used as a proof gate.
• Non-Hermitian support is experimental: left/right eigenvectors, biorthogonal W, EP2 topology, Puiseux inverse, and conditioned diagnostics exist, but full production branch tracking, Jordan fusion, and EP-safe inverse workflows remain v0.2+ roadmap items.