Metadata-Version: 2.4
Name: sftransform
Version: 0.2.0
Summary: Torch-native Spectral Flow Transform for data-to-operator spectral programming
Author: Dmitry Sierikov
License-Expression: LicenseRef-SFT-Permissive-Attribution
Project-URL: Homepage, https://github.com/dimaq12/spectral-flow-torch
Project-URL: Repository, https://github.com/dimaq12/spectral-flow-torch
Project-URL: Documentation, https://github.com/dimaq12/spectral-flow-torch
Keywords: spectral-flow,sftransform,torch,operators,spectral-geometry,omega
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: parity
Requires-Dist: numpy>=1.24; extra == "parity"
Requires-Dist: scipy>=1.10; extra == "parity"
Dynamic: license-file

# SFT-Torch

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

```text
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:

```python
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:

```bash
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`:

```bash
python3 -m pip install sftransform
```

Build and install a local release artifact:

```bash
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:

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

## Quickstart

```python
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:

```bash
python3 -m pytest
```

Run targeted production groups:

```bash
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:

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

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

```bash
python3 -m pytest -m cuda
```

## Benchmarks

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

```bash
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:

```bash
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:

```bash
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.
