Metadata-Version: 2.4
Name: ds2-toolkit
Version: 0.1.0
Summary: Algebraic toolkit for 2x2 doubly stochastic matrices: cascade, entropy, correction, phase recovery, and compilation
Author-email: David Tom Foss <david@foss.com.de>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/davidtomfoss/ds2
Project-URL: Documentation, https://ds2.readthedocs.io
Project-URL: Bug Tracker, https://github.com/davidtomfoss/ds2/issues
Project-URL: Paper (Foundations), https://doi.org/TBD
Project-URL: Paper (Toolkit), https://doi.org/TBD
Keywords: doubly stochastic,scattering matrix,cascade analysis,Birkhoff polytope,insertion loss,Landauer principle,error correction,two-port network
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: rf
Requires-Dist: scikit-rf>=0.30; extra == "rf"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-book-theme; extra == "docs"
Requires-Dist: myst-nb; extra == "docs"
Provides-Extra: dev
Requires-Dist: ds2[docs,rf,test]; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

# DS2 — Algebraic Toolkit for 2x2 Doubly Stochastic Matrices

[![PyPI version](https://img.shields.io/pypi/v/ds2)](https://pypi.org/project/ds2/)
[![Python](https://img.shields.io/pypi/pyversions/ds2)](https://pypi.org/project/ds2/)
[![License](https://img.shields.io/pypi/l/ds2)](https://github.com/davidtomfoss/ds2/blob/main/LICENSE)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)]()

**One scalar replaces four complex scattering parameters.**

Every 2x2 doubly stochastic matrix is uniquely determined by a single eigenvalue
`lambda in [-1, 1]`, and `P(a) * P(b) = P(a*b)`. This monoid structure reduces
cascade analysis to scalar multiplication — no matrix algebra needed.

## Installation

```bash
pip install ds2
```

## Quick Start

```python
import ds2

# Build a P(lambda) matrix
P = ds2.matrix(0.7)
# array([[0.85, 0.15],
#        [0.15, 0.85]])

# Cascade 4 devices: just multiply eigenvalues
result = ds2.cascade([0.9, 0.8, -0.5, 0.95])
print(result.eigenvalue)          # -0.342
print(result.insertion_loss_db)   # 3.33 dB

# Analog error correction (k=3 repetition code)
ds2.correct(0.3, k=3)  # 0.4365 — repels from 0

# Compile a target IL from standard components
r = ds2.compile(target_il=7.0)
print(r.chain)   # ('6dB', '1dB')
print(r.error_db) # 0.0

# Landauer efficiency (quasistatic erasure)
ds2.landauer_efficiency(delta_0=0.9, delta_f=0.1, k=100)
# {'eta': 0.982, 'delta_h': 0.469, 'dissipation': 0.009, ...}

# 13-domain universality
ds2.domains.bsc(epsilon=0.1)          # 0.8
ds2.domains.beam_splitter(reflectance=0.3)  # -0.4
ds2.domains.scattering(s11_sq=0.3)    # -0.4
```

## Five Tools

| Tool | What it does | Key result |
|------|-------------|------------|
| **Cascade** | `lambda_total = prod(lambda_i)` | Error < 10^-16 |
| **Thermodynamics** | Entropy budget + Landauer cost | eta -> 1 as k -> inf |
| **Correction** | `f_3(lambda) = (3*lambda - lambda^3)/2` | 26.5x capacity gain |
| **Phase recovery** | Interferometric S-matrix reconstruction | 100% on 1000 unitaries |
| **Compiler** | Target IL -> device chain | 0.00 dB error |

## Thirteen Domains

The DS2 monoid appears in: microwave scattering, quantum gates, Markov chains,
softmax/neural networks, optical beam splitters, population genetics, resistor
dividers, polarization (Malus's law), IIR filters, binary symmetric channels,
synaptic transmission, gene regulation, and epidemic transmission.

```python
from ds2.domains import DOMAIN_TABLE
for d in DOMAIN_TABLE:
    print(f"{d['domain']:30s} lambda = {d['lambda']}")
```

## References

- D. T. Foss, "Algebraic Structure of Doubly Stochastic Power Matrices in
  Electromagnetic Scattering," Proc. ICEAA/APWC, Toyama, Japan, Sep. 2026.
- D. T. Foss, "The DS2 Toolkit: Algebraic Methods for Two-Port Network Analysis
  Across Thirteen Domains," Proc. ICEAA/APWC, Toyama, Japan, Sep. 2026.

## License

BSD 3-Clause. See [LICENSE](LICENSE).
