ds2-toolkit 0.1.0__tar.gz

ds2_toolkit-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, David Tom Foss
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ds2_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+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).

ds2_toolkit-0.1.0/README.md

@@ -0,0 +1,85 @@
+# 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).

ds2_toolkit-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ds2-toolkit"
+version = "0.1.0"
+description = "Algebraic toolkit for 2x2 doubly stochastic matrices: cascade, entropy, correction, phase recovery, and compilation"
+readme = "README.md"
+license = "BSD-3-Clause"
+requires-python = ">=3.10"
+authors = [
+    {name = "David Tom Foss", email = "david@foss.com.de"},
+]
+keywords = [
+    "doubly stochastic",
+    "scattering matrix",
+    "cascade analysis",
+    "Birkhoff polytope",
+    "insertion loss",
+    "Landauer principle",
+    "error correction",
+    "two-port network",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Typing :: Typed",
+]
+dependencies = [
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+rf = ["scikit-rf>=0.30"]
+test = ["pytest>=7.0", "pytest-cov>=4.0"]
+docs = ["sphinx>=7.0", "sphinx-book-theme", "myst-nb"]
+dev = ["ds2[rf,test,docs]", "ruff", "pre-commit"]
+
+[project.urls]
+Homepage = "https://github.com/davidtomfoss/ds2"
+Documentation = "https://ds2.readthedocs.io"
+"Bug Tracker" = "https://github.com/davidtomfoss/ds2/issues"
+"Paper (Foundations)" = "https://doi.org/TBD"
+"Paper (Toolkit)" = "https://doi.org/TBD"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=ds2 --cov-report=term-missing -v"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "NPY"]

ds2_toolkit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ds2_toolkit-0.1.0/src/ds2/__init__.py

@@ -0,0 +1,70 @@
+"""DS2: Algebraic toolkit for 2x2 doubly stochastic matrices.
+
+The DS2 monoid: every 2x2 doubly stochastic matrix is P(lambda) for a unique
+lambda in [-1, 1], and P(a) * P(b) = P(ab). This single-scalar parameterization
+replaces four complex scattering parameters for power-level two-port analysis.
+
+Five core tools:
+    1. Cascade-by-multiplication (cascade)
+    2. Thermodynamic analysis (thermo)
+    3. Analog error correction (correction)
+    4. Phase recovery (phase)
+    5. Cascade compiler (compiler)
+
+Universal across 13 domains (domains).
+
+Example::
+
+    >>> import ds2
+    >>> P = ds2.matrix(0.7)
+    >>> ds2.cascade([0.9, 0.8, -0.5, 0.95])
+    CascadeResult(eigenvalue=-0.342, insertion_loss_db=...)
+    >>> ds2.correct(0.3, k=3)
+    0.4365...
+
+References:
+    D. T. Foss, "Algebraic Structure of Doubly Stochastic Power Matrices
+    in Electromagnetic Scattering," Proc. ICEAA/APWC, Toyama, 2026.
+
+    D. T. Foss, "The DS2 Toolkit: Algebraic Methods for Two-Port Network
+    Analysis Across Thirteen Domains," Proc. ICEAA/APWC, Toyama, 2026.
+"""
+
+__version__ = "0.1.0"
+
+from ds2.core import matrix, eigenvalue, insertion_loss, from_insertion_loss
+from ds2.cascade import cascade, CascadeResult
+from ds2.thermo import entropy, entropy_change, landauer_cost, landauer_efficiency
+from ds2.correction import correct, correction_polynomial, duality_fixed_points
+from ds2.phase import recover_phase_2port
+from ds2.compiler import compile, CompilerResult, STANDARD_LIBRARY
+from ds2 import domains
+
+__all__ = [
+    "__version__",
+    # core
+    "matrix",
+    "eigenvalue",
+    "insertion_loss",
+    "from_insertion_loss",
+    # cascade
+    "cascade",
+    "CascadeResult",
+    # thermo
+    "entropy",
+    "entropy_change",
+    "landauer_cost",
+    "landauer_efficiency",
+    # correction
+    "correct",
+    "correction_polynomial",
+    "duality_fixed_points",
+    # phase
+    "recover_phase_2port",
+    # compiler
+    "compile",
+    "CompilerResult",
+    "STANDARD_LIBRARY",
+    # domains
+    "domains",
+]

ds2_toolkit-0.1.0/src/ds2/cascade.py

@@ -0,0 +1,138 @@
+"""Cascade-by-multiplication: reduce k-device chain to scalar arithmetic.
+
+The DS2 monoid product P(a) * P(b) = P(ab) means cascading k lossless
+two-port devices with eigenvalues lambda_1, ..., lambda_k gives:
+
+    lambda_total = prod(lambda_i)
+    IL_total = sum(IL_i)       [in dB]
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Sequence
+
+import numpy as np
+
+from ds2.core import insertion_loss, matrix
+
+
+@dataclass(frozen=True)
+class CascadeResult:
+    """Result of cascading multiple DS2 devices.
+
+    Attributes
+    ----------
+    eigenvalue : float
+        Product eigenvalue of the cascade.
+    insertion_loss_db : float
+        Total insertion loss in dB.
+    matrix : np.ndarray
+        The 2x2 doubly stochastic matrix P(eigenvalue).
+    individual : tuple[float, ...]
+        Individual eigenvalues in cascade order.
+    cumulative : tuple[float, ...]
+        Cumulative eigenvalue after each stage.
+    """
+
+    eigenvalue: float
+    insertion_loss_db: float
+    matrix: np.ndarray = field(repr=False)
+    individual: tuple[float, ...] = field(repr=False)
+    cumulative: tuple[float, ...] = field(repr=False)
+
+    def __repr__(self) -> str:
+        return (
+            f"CascadeResult(eigenvalue={self.eigenvalue:.6f}, "
+            f"insertion_loss_db={self.insertion_loss_db:.4f}, "
+            f"stages={len(self.individual)})"
+        )
+
+
+def cascade(eigenvalues: Sequence[float]) -> CascadeResult:
+    """Cascade k devices by multiplying their eigenvalues.
+
+    Parameters
+    ----------
+    eigenvalues : sequence of float
+        Eigenvalues lambda_i in [-1, 1] for each device.
+
+    Returns
+    -------
+    CascadeResult
+        Contains product eigenvalue, total IL, cumulative trace.
+
+    Raises
+    ------
+    ValueError
+        If any eigenvalue is outside [-1, 1] or sequence is empty.
+
+    Examples
+    --------
+    >>> r = cascade([0.9, 0.8, 0.7])
+    >>> abs(r.eigenvalue - 0.9 * 0.8 * 0.7) < 1e-15
+    True
+    """
+    evs = list(eigenvalues)
+    if not evs:
+        raise ValueError("Need at least one eigenvalue")
+    for i, lam in enumerate(evs):
+        if not -1.0 <= lam <= 1.0:
+            raise ValueError(f"eigenvalue[{i}] = {lam} outside [-1, 1]")
+
+    cum = []
+    prod = 1.0
+    for lam in evs:
+        prod *= lam
+        cum.append(prod)
+
+    lam_total = cum[-1]
+    il_db = insertion_loss(lam_total)
+    P = matrix(lam_total)
+
+    return CascadeResult(
+        eigenvalue=lam_total,
+        insertion_loss_db=il_db,
+        matrix=P,
+        individual=tuple(evs),
+        cumulative=tuple(cum),
+    )
+
+
+def link_budget(
+    devices: Sequence[tuple[str, float]],
+) -> list[dict[str, float | str]]:
+    """Compute a link budget table for named devices.
+
+    Parameters
+    ----------
+    devices : sequence of (name, eigenvalue) tuples
+        Each device with its name and eigenvalue.
+
+    Returns
+    -------
+    list of dict
+        Each dict has keys: 'device', 'eigenvalue', 'cumulative_eigenvalue',
+        'cumulative_il_db'.
+
+    Examples
+    --------
+    >>> budget = link_budget([("coupler", -0.002), ("mismatch", -0.589)])
+    >>> budget[1]['cumulative_il_db']  # doctest: +SKIP
+    3.01...
+    """
+    rows = []
+    prod = 1.0
+    for name, lam in devices:
+        if not -1.0 <= lam <= 1.0:
+            raise ValueError(f"eigenvalue for '{name}' = {lam} outside [-1, 1]")
+        prod *= lam
+        rows.append(
+            {
+                "device": name,
+                "eigenvalue": lam,
+                "cumulative_eigenvalue": prod,
+                "cumulative_il_db": insertion_loss(prod),
+            }
+        )
+    return rows

ds2_toolkit-0.1.0/src/ds2/compiler.py

@@ -0,0 +1,137 @@
+"""Cascade compiler: find exact device chains for target insertion loss.
+
+Since IL values add in dB under cascade (log|lambda| is additive),
+cascade design reduces to subset-sum on IL values.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Sequence
+
+import numpy as np
+
+
+# Standard component library (name, IL in dB)
+STANDARD_LIBRARY: list[tuple[str, float]] = [
+    ("20dB", 20.0),
+    ("10dB", 10.0),
+    ("6dB", 6.0),
+    ("3dB", 3.0),
+    ("1dB", 1.0),
+    ("0.5dB", 0.5),
+    ("0.1dB", 0.1),
+]
+
+
+@dataclass(frozen=True)
+class CompilerResult:
+    """Result of cascade compilation.
+
+    Attributes
+    ----------
+    chain : tuple[str, ...]
+        Device names in the compiled chain.
+    target_il_db : float
+        Requested insertion loss.
+    achieved_il_db : float
+        Achieved insertion loss.
+    error_db : float
+        |target - achieved| in dB.
+    eigenvalue : float
+        Equivalent eigenvalue of the chain.
+    """
+
+    chain: tuple[str, ...]
+    target_il_db: float
+    achieved_il_db: float
+    error_db: float
+    eigenvalue: float
+
+    def __repr__(self) -> str:
+        chain_str = " + ".join(self.chain)
+        return (
+            f"CompilerResult(chain=[{chain_str}], "
+            f"target={self.target_il_db:.2f}dB, "
+            f"achieved={self.achieved_il_db:.2f}dB, "
+            f"error={self.error_db:.2f}dB)"
+        )
+
+
+def compile(
+    target_il: float,
+    library: Sequence[tuple[str, float]] | None = None,
+    tolerance: float = 0.05,
+) -> CompilerResult:
+    """Find a device chain achieving the target insertion loss.
+
+    Uses a greedy algorithm on a sorted library. For practical libraries
+    (< 20 component types), this achieves exact solutions.
+
+    Parameters
+    ----------
+    target_il : float
+        Target insertion loss in dB (> 0).
+    library : sequence of (name, IL_dB) tuples, optional
+        Component library. Defaults to STANDARD_LIBRARY.
+    tolerance : float
+        Acceptable error in dB.
+
+    Returns
+    -------
+    CompilerResult
+        Compiled chain with achieved IL and error.
+
+    Examples
+    --------
+    >>> r = compile(7.0)
+    >>> r.chain
+    ('6dB', '1dB')
+    >>> r.error_db
+    0.0
+    """
+    if target_il <= 0.0:
+        raise ValueError(f"target_il must be > 0, got {target_il}")
+    if library is None:
+        library = STANDARD_LIBRARY
+
+    # Sort by IL descending
+    lib = sorted(library, key=lambda x: x[1], reverse=True)
+
+    chain: list[str] = []
+    current_il = 0.0
+
+    while abs(current_il - target_il) > tolerance:
+        remaining = target_il - current_il
+        if remaining <= 0:
+            break
+
+        # Find best component
+        best_name = None
+        best_il = 0.0
+        best_gap = float("inf")
+
+        for name, il in lib:
+            if il <= remaining + tolerance:
+                gap = abs(remaining - il)
+                if gap < best_gap:
+                    best_gap = gap
+                    best_name = name
+                    best_il = il
+
+        if best_name is None:
+            break
+
+        chain.append(best_name)
+        current_il += best_il
+
+    error = abs(current_il - target_il)
+    lam = 1.0 - 2.0 * 10.0 ** (-current_il / 10.0) if current_il > 0 else 1.0
+
+    return CompilerResult(
+        chain=tuple(chain),
+        target_il_db=target_il,
+        achieved_il_db=round(current_il, 10),
+        error_db=round(error, 10),
+        eigenvalue=lam,
+    )