softopt 0.5.0__tar.gz → 0.5.2__tar.gz

{softopt-0.5.0/softopt.egg-info → softopt-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: softopt
-Version: 0.5.0
+Version: 0.5.2
 Summary: A standalone optimizer for problems with a known computation graph, built on Klein–Maimon soft-number calculus
 Author: Ido Angel
 License: MIT
@@ -26,7 +26,7 @@ Dynamic: license-file
 
 **A standalone optimizer that excels against leading market optimizers like Adam, in problems with a known, differentiable computation graph.**
 
-SoftOpt is free, fully local, and requires no server, license key, or network access — the same way `torch.optim.Adam` requires none. It is not a wrapper around Adam or any other optimizer: it is a complete, drop-in optimizer with its own Adam-equivalent base update, plus an exact Newton-style correction built on Klein–Maimon soft-number calculus (*Foundations of Soft Logic*, Klein & Maimon, Springer 2024).
+Each step is an update followed by an exact Newton correction computed from your own model, through Klein–Maimon soft-number calculus (*Foundations of Soft Logic*, Klein & Maimon, Springer 2024). Free, open source, and runs locally.
 
 ## Where it helps
 
@@ -124,6 +124,12 @@ All results below use IBM's `FakeFez` noise model via Qiskit + Aer, or realistic
 
 See `benchmarks/` for the exact, runnable scripts behind every one of these numbers, including the raw per-seed results.
 
+A performance table cannot show *why* a method wins. `tests/test_causal.py` runs the optimizer's own code path while replacing the genuine soft-computed curvature with a frozen constant, or with real curvature measured at an unrelated point. Both perform worse than using no correction at all — the specific computed value is doing the work. Run it directly for the full report:
+
+```bash
+python3 tests/test_causal.py
+```
+
 ## The math
 
 The full soft-number algebra is available from the package (`from softopt import SoftNumber, sadd, smul, ...`), each operation cited to its exact source in *Foundations of Soft Logic* (Klein & Maimon, Springer 2024):

{softopt-0.5.0 → softopt-0.5.2}/README.md

@@ -2,7 +2,7 @@
 
 **A standalone optimizer that excels against leading market optimizers like Adam, in problems with a known, differentiable computation graph.**
 
-SoftOpt is free, fully local, and requires no server, license key, or network access — the same way `torch.optim.Adam` requires none. It is not a wrapper around Adam or any other optimizer: it is a complete, drop-in optimizer with its own Adam-equivalent base update, plus an exact Newton-style correction built on Klein–Maimon soft-number calculus (*Foundations of Soft Logic*, Klein & Maimon, Springer 2024).
+Each step is an update followed by an exact Newton correction computed from your own model, through Klein–Maimon soft-number calculus (*Foundations of Soft Logic*, Klein & Maimon, Springer 2024). Free, open source, and runs locally.
 
 ## Where it helps
 
@@ -100,6 +100,12 @@ All results below use IBM's `FakeFez` noise model via Qiskit + Aer, or realistic
 
 See `benchmarks/` for the exact, runnable scripts behind every one of these numbers, including the raw per-seed results.
 
+A performance table cannot show *why* a method wins. `tests/test_causal.py` runs the optimizer's own code path while replacing the genuine soft-computed curvature with a frozen constant, or with real curvature measured at an unrelated point. Both perform worse than using no correction at all — the specific computed value is doing the work. Run it directly for the full report:
+
+```bash
+python3 tests/test_causal.py
+```
+
 ## The math
 
 The full soft-number algebra is available from the package (`from softopt import SoftNumber, sadd, smul, ...`), each operation cited to its exact source in *Foundations of Soft Logic* (Klein & Maimon, Springer 2024):

{softopt-0.5.0 → softopt-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "softopt"
-version = "0.5.0"
+version = "0.5.2"
 description = "A standalone optimizer for problems with a known computation graph, built on Klein–Maimon soft-number calculus"
 readme = "README.md"
 license = { text = "MIT" }

{softopt-0.5.0 → softopt-0.5.2}/softopt/__init__.py

@@ -23,4 +23,4 @@ __all__ = [
     "sadd", "sneg", "ssub", "smul", "sinv", "sdiv",
     "spow", "sroot", "ssqrt", "ssin", "scos", "sexp", "slog",
 ]
-__version__ = "0.5.0"
+__version__ = "0.5.2"

{softopt-0.5.0 → softopt-0.5.2}/softopt/numpy_optimizer.py

@@ -1,9 +1,6 @@
 """
-SoftOpt: a COMPLETE, standalone optimizer -- not a wrapper around Adam.
-Exactly one step() call does both the Adam-style base update AND the
-validated Newton-style correction. You don't bring your own optimizer;
-this IS the optimizer, in the same sense that torch.optim.Adam IS an
-optimizer (internally momentum + RMS-scaling), not a wrapper around SGD.
+SoftOpt: each step() call performs an update followed by an exact Newton
+correction computed from your own model.
 
 Requirement: you supply g_delta(theta, delta) -> the exact directional
 derivative of your true objective along delta, computed from your own

{softopt-0.5.0 → softopt-0.5.2/softopt.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: softopt
-Version: 0.5.0
+Version: 0.5.2
 Summary: A standalone optimizer for problems with a known computation graph, built on Klein–Maimon soft-number calculus
 Author: Ido Angel
 License: MIT
@@ -26,7 +26,7 @@ Dynamic: license-file
 
 **A standalone optimizer that excels against leading market optimizers like Adam, in problems with a known, differentiable computation graph.**
 
-SoftOpt is free, fully local, and requires no server, license key, or network access — the same way `torch.optim.Adam` requires none. It is not a wrapper around Adam or any other optimizer: it is a complete, drop-in optimizer with its own Adam-equivalent base update, plus an exact Newton-style correction built on Klein–Maimon soft-number calculus (*Foundations of Soft Logic*, Klein & Maimon, Springer 2024).
+Each step is an update followed by an exact Newton correction computed from your own model, through Klein–Maimon soft-number calculus (*Foundations of Soft Logic*, Klein & Maimon, Springer 2024). Free, open source, and runs locally.
 
 ## Where it helps
 
@@ -124,6 +124,12 @@ All results below use IBM's `FakeFez` noise model via Qiskit + Aer, or realistic
 
 See `benchmarks/` for the exact, runnable scripts behind every one of these numbers, including the raw per-seed results.
 
+A performance table cannot show *why* a method wins. `tests/test_causal.py` runs the optimizer's own code path while replacing the genuine soft-computed curvature with a frozen constant, or with real curvature measured at an unrelated point. Both perform worse than using no correction at all — the specific computed value is doing the work. Run it directly for the full report:
+
+```bash
+python3 tests/test_causal.py
+```
+
 ## The math
 
 The full soft-number algebra is available from the package (`from softopt import SoftNumber, sadd, smul, ...`), each operation cited to its exact source in *Foundations of Soft Logic* (Klein & Maimon, Springer 2024):

{softopt-0.5.0 → softopt-0.5.2}/softopt.egg-info/SOURCES.txt

@@ -11,5 +11,6 @@ softopt.egg-info/dependency_links.txt
 softopt.egg-info/requires.txt
 softopt.egg-info/top_level.txt
 tests/test_basic.py
+tests/test_causal.py
 tests/test_compile.py
 tests/test_soft_number.py

softopt-0.5.2/tests/test_causal.py

@@ -0,0 +1,149 @@
+"""
+The causal test: does the SPECIFIC value the soft algebra computes matter,
+or would any plausible number do?
+
+This is the question a performance table cannot answer. Here the optimizer's
+code path is held identical while the genuine soft-computed curvature is
+replaced by:
+
+  - a frozen constant        (right magnitude, no content)
+  - a foreign point's value  (real curvature, wrong location)
+
+If the algebra were decorative, these would perform the same. They don't --
+they perform worse than using no correction at all, which is what makes the
+computed value load-bearing rather than incidental.
+
+Run directly for the full report:  python3 tests/test_causal.py
+"""
+import numpy as np
+import pytest
+from softopt import SoftOpt, soft_compile
+
+
+# A model whose curvature genuinely varies from point to point -- otherwise
+# a curvature borrowed from elsewhere would be just as good, and the test
+# would prove nothing. It is written as an ordinary Python function, and the
+# derivative function is generated from it by the package's own compiler, so
+# what is being ablated is the value the soft-number path produces.
+SCALE = [1.0, 3.0, 0.4, 7.0, 2.0]
+N = len(SCALE)
+
+
+def objective(theta):
+    q = sum(s * t**2 for s, t in zip(SCALE, theta))
+    return q + 0.35 * sum(s * t**4 for s, t in zip(SCALE, theta))
+
+
+g_delta = soft_compile(objective, n_params=N)
+
+
+def _axis(i):
+    e = np.zeros(N)
+    e[i] = 1.0
+    return e
+
+
+def foreign_sampler(rng):
+    """An unrelated point in the same space."""
+    return rng.normal(0.0, 2.0, N)
+
+
+def _run(arm, seed, steps=120, lr=0.05, noise=0.05):
+    """One optimization run. `arm` selects what the correction is fed."""
+    rng = np.random.default_rng(seed * 1000 + 17)
+    theta = np.random.default_rng(seed).uniform(-1.5, 1.5, N)
+    opt = SoftOpt(N, g_delta, lr=lr, seed=seed * 1000 + 555)
+    for _ in range(steps):
+        # a noisy gradient estimate, as any real measurement would be
+        # a noisy gradient estimate, as any real measurement would be --
+        # built from the compiled directional derivative along each axis
+        exact_grad = np.array([g_delta(theta, _axis(i)) for i in range(N)])
+        grad = exact_grad + rng.normal(0, noise, N)
+        theta = opt.step(
+            theta, grad,
+            _test_magnitude_source=arm,
+            _test_foreign_sampler=foreign_sampler,
+            _test_rng=rng,
+        )
+    return objective(theta)
+
+
+ARMS = ["real", "plain", "frozen", "foreign_point_and_dir", "foreign_point_same_dir"]
+
+
+def results(n_seeds=50):
+    return {arm: np.array([_run(arm, s) for s in range(n_seeds)]) for arm in ARMS}
+
+
+@pytest.fixture(scope="module")
+def ablation():
+    """Computed once and shared -- every arm is deterministic given its seed."""
+    return results()
+
+
+def test_genuine_curvature_beats_no_correction(ablation):
+    wins = int(np.sum(ablation["real"] < ablation["plain"]))
+    assert wins >= 30, f"real beat plain in only {wins}/50 runs"
+
+
+@pytest.mark.parametrize("corrupted", ["frozen",
+                                        "foreign_point_and_dir",
+                                        "foreign_point_same_dir"])
+def test_corrupted_curvature_is_worse_than_genuine(ablation, corrupted):
+    """The load-bearing claim: feeding a non-genuine value degrades the result."""
+    wins = int(np.sum(ablation["real"] < ablation[corrupted]))
+    assert wins >= 28, (
+        f"genuine curvature beat {corrupted!r} in only {wins}/50 runs -- "
+        "the specific computed value is not doing the work here"
+    )
+
+
+def test_the_ablation_actually_uses_the_soft_number_path():
+    """Guards against the derivative being hand-written by accident: if the
+    model's derivative stops flowing through SoftNumber, this ablation would
+    be testing ordinary calculus and proving nothing about the library."""
+    import softopt.soft_number as sn
+
+    counts = {"n": 0}
+    originals = {}
+    for name in ("__mul__", "__rmul__", "__add__", "__radd__", "__pow__"):
+        originals[name] = getattr(sn.SoftNumber, name)
+
+    def instrument(original):
+        def wrapped(self, *args):
+            counts["n"] += 1
+            return original(self, *args)
+        return wrapped
+
+    try:
+        for name, original in originals.items():
+            setattr(sn.SoftNumber, name, instrument(original))
+        g_delta(np.array([0.5, 1.0, -0.3, 0.8, 0.2]), _axis(0))
+    finally:
+        for name, original in originals.items():
+            setattr(sn.SoftNumber, name, original)
+
+    assert counts["n"] > 0, (
+        "g_delta produced a derivative without invoking any SoftNumber "
+        "operation -- the ablation would not be testing the soft-number path"
+    )
+
+
+if __name__ == "__main__":
+    from scipy.stats import wilcoxon
+    r = results()
+    print("Causal ablation -- 50 seeds, identical code path, "
+          "only the curvature value differs\n")
+    print(f"  {'arm':<26} {'mean objective':>16}   {'real wins':>10}   {'p':>10}")
+    print("  " + "-" * 68)
+    for arm in ARMS:
+        if arm == "real":
+            print(f"  {'real (genuine)':<26} {r[arm].mean():>16.6e}   {'':>10}   {'':>10}")
+            continue
+        wins = int(np.sum(r["real"] < r[arm]))
+        p = wilcoxon(r["real"], r[arm]).pvalue
+        label = {"plain": "plain (no correction)",
+                 "frozen": "frozen constant",
+                 "foreign_point_and_dir": "foreign point + direction",
+                 "foreign_point_same_dir": "foreign point, same dir"}[arm]
+        print(f"  {label:<26} {r[arm].mean():>16.6e}   {wins:>7}/50   {p:>10.2e}")