softopt 0.6.0__tar.gz → 0.6.2__tar.gz

{softopt-0.6.0/softopt.egg-info → softopt-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: softopt
-Version: 0.6.0
+Version: 0.6.2
 Summary: A standalone optimizer for problems with a known computation graph, built on Klein–Maimon soft-number calculus
 Author: Ido Angel
 License: MIT
@@ -85,7 +85,7 @@ is the mechanism.
 But at 10 qubits both arms covered only a few percent of the way to the ground
 state. 1.5× of very little is still very little. **If the plateau is your
 problem, this is not the fix.** The scan and its replication are in
-`benchmarks/barren_plateau/`.
+`benchmarks_barren_plateau/`.
 
 ## Installation
 
@@ -122,6 +122,32 @@ The one thing to avoid is converting a traced value back to a plain number mid-m
 
 If you'd rather write the derivative function yourself — because your model lives in a simulator SoftOpt can't trace, or because you want the speed of a hand-tuned implementation — pass any `g_delta(theta, delta)` that returns the exact directional derivative, and skip `soft_compile` entirely.
 
+## Where the slope comes from: `slope="model"` or `slope="measured"`
+
+Every correction is a Newton step, `-slope / curvature`, taken along one direction. The curvature always comes from your model. The slope has two possible sources:
+
+| | `slope="model"` (default) | `slope="measured"` (new in 0.6.1) |
+|---|---|---|
+| slope from | your model's exact derivative | your readings, along the direction you probed |
+| converges to | the **model's** optimum | the **real system's** optimum |
+| choose it when | the model is accurate and the readings are very noisy | the model may be biased, and the readings are clean enough to show the slope |
+
+With `slope="model"`, a model whose optimum is in the wrong place pulls the answer to the wrong place. `slope="measured"` uses the model only for the shape of the landscape, so the readings decide where the optimum is. An SPSA probe already measures that slope, so the measured mode costs no extra readings:
+
+```python
+from softopt import SoftOpt, soft_compile, spsa_gradient
+
+opt = SoftOpt(n, soft_compile(my_model, n_params=n), lr=0.05, slope="measured")
+
+for step in range(num_steps):
+    grad, direction, slope = spsa_gradient(measure, theta, c=0.1)   # 2 readings
+    theta = opt.step(theta, grad, direction=direction, measured_slope=slope)
+```
+
+`measure(theta)` returns one reading of the real system. If you already compute your own SPSA estimate, pass its direction `d` and `(f(θ+cd) - f(θ-cd)) / 2c` as `measured_slope`.
+
+If your model is exact, you do not need either mode, or any readings: optimise the model directly.
+
 ## PyTorch
 
 If your known model is written in PyTorch, `SoftOptTorch` runs the same step as a `torch.optim.Optimizer`: an Adam update from the gradient, then the bounded Newton correction. The directional derivative and the curvature along the probe direction come from PyTorch's forward-mode AD (`torch.func.jvp`, nested once), which is single-axis soft-number propagation executed by PyTorch's own engine. It runs wherever your model runs: CPU, CUDA or Apple MPS.
@@ -169,6 +195,15 @@ All results below use IBM's `FakeFez` noise model via Qiskit + Aer, or realistic
 | BeH₂ | 94.7% | 5/5 |
 | HeH⁺ | 90.9% | 5/5 |
 
+**Quantum chemistry on a real molecule, and against COBYLA**
+
+| Test | Baseline | Result | Win rate |
+|---|---|---|---|
+| H₄ molecule (STO-3G, 8 qubits, 185 Pauli terms), 100 steps | Adam | 67% smaller gap to the ground state (409 vs 1227 mHa) | 10/10 |
+| H₂, same budget of 180 device readings | COBYLA | 0.11 vs 5.81 mHa above the ground state; chemical accuracy in 10/10 runs vs 3/10 | 10/10 |
+
+Both run SoftOpt with its default settings on IBM's `FakeFez` noise model: `benchmarks/vqe/h4_real_molecule.py`, `benchmarks/vqe/h2_vs_cobyla.py`.
+
 **Quantum control**
 
 | Domain | Improvement | Win rate |

{softopt-0.6.0 → softopt-0.6.2}/README.md

@@ -59,7 +59,7 @@ is the mechanism.
 But at 10 qubits both arms covered only a few percent of the way to the ground
 state. 1.5× of very little is still very little. **If the plateau is your
 problem, this is not the fix.** The scan and its replication are in
-`benchmarks/barren_plateau/`.
+`benchmarks_barren_plateau/`.
 
 ## Installation
 
@@ -96,6 +96,32 @@ The one thing to avoid is converting a traced value back to a plain number mid-m
 
 If you'd rather write the derivative function yourself — because your model lives in a simulator SoftOpt can't trace, or because you want the speed of a hand-tuned implementation — pass any `g_delta(theta, delta)` that returns the exact directional derivative, and skip `soft_compile` entirely.
 
+## Where the slope comes from: `slope="model"` or `slope="measured"`
+
+Every correction is a Newton step, `-slope / curvature`, taken along one direction. The curvature always comes from your model. The slope has two possible sources:
+
+| | `slope="model"` (default) | `slope="measured"` (new in 0.6.1) |
+|---|---|---|
+| slope from | your model's exact derivative | your readings, along the direction you probed |
+| converges to | the **model's** optimum | the **real system's** optimum |
+| choose it when | the model is accurate and the readings are very noisy | the model may be biased, and the readings are clean enough to show the slope |
+
+With `slope="model"`, a model whose optimum is in the wrong place pulls the answer to the wrong place. `slope="measured"` uses the model only for the shape of the landscape, so the readings decide where the optimum is. An SPSA probe already measures that slope, so the measured mode costs no extra readings:
+
+```python
+from softopt import SoftOpt, soft_compile, spsa_gradient
+
+opt = SoftOpt(n, soft_compile(my_model, n_params=n), lr=0.05, slope="measured")
+
+for step in range(num_steps):
+    grad, direction, slope = spsa_gradient(measure, theta, c=0.1)   # 2 readings
+    theta = opt.step(theta, grad, direction=direction, measured_slope=slope)
+```
+
+`measure(theta)` returns one reading of the real system. If you already compute your own SPSA estimate, pass its direction `d` and `(f(θ+cd) - f(θ-cd)) / 2c` as `measured_slope`.
+
+If your model is exact, you do not need either mode, or any readings: optimise the model directly.
+
 ## PyTorch
 
 If your known model is written in PyTorch, `SoftOptTorch` runs the same step as a `torch.optim.Optimizer`: an Adam update from the gradient, then the bounded Newton correction. The directional derivative and the curvature along the probe direction come from PyTorch's forward-mode AD (`torch.func.jvp`, nested once), which is single-axis soft-number propagation executed by PyTorch's own engine. It runs wherever your model runs: CPU, CUDA or Apple MPS.
@@ -143,6 +169,15 @@ All results below use IBM's `FakeFez` noise model via Qiskit + Aer, or realistic
 | BeH₂ | 94.7% | 5/5 |
 | HeH⁺ | 90.9% | 5/5 |
 
+**Quantum chemistry on a real molecule, and against COBYLA**
+
+| Test | Baseline | Result | Win rate |
+|---|---|---|---|
+| H₄ molecule (STO-3G, 8 qubits, 185 Pauli terms), 100 steps | Adam | 67% smaller gap to the ground state (409 vs 1227 mHa) | 10/10 |
+| H₂, same budget of 180 device readings | COBYLA | 0.11 vs 5.81 mHa above the ground state; chemical accuracy in 10/10 runs vs 3/10 | 10/10 |
+
+Both run SoftOpt with its default settings on IBM's `FakeFez` noise model: `benchmarks/vqe/h4_real_molecule.py`, `benchmarks/vqe/h2_vs_cobyla.py`.
+
 **Quantum control**
 
 | Domain | Improvement | Win rate |

{softopt-0.6.0 → softopt-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "softopt"
-version = "0.6.0"
+version = "0.6.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.6.0 → softopt-0.6.2}/softopt/__init__.py

@@ -3,7 +3,8 @@ SoftOpt — a standalone optimizer built on Klein–Maimon soft-number
 calculus, for problems with a known, differentiable computation graph
 (quantum circuits, physical models, projection models, ...).
 
-    from softopt import SoftOpt          # numpy version
+    from softopt import SoftOpt          # numpy version (slope="model" or "measured")
+    from softopt import spsa_gradient    # gradient, direction and measured slope from 2 readings
     from softopt import SoftOptTorch     # PyTorch version (torch.optim.Optimizer)
     from softopt import soft_compile     # turn a plain-Python model into g_delta
     from softopt import SoftNumber       # the algebraic primitive itself
@@ -11,7 +12,7 @@ calculus, for problems with a known, differentiable computation graph
 See README.md for the exact requirement your problem must satisfy
 (the "known computation graph" criterion) and worked examples.
 """
-from .numpy_optimizer import SoftOpt
+from .numpy_optimizer import SoftOpt, spsa_gradient
 from .compile import soft_compile
 from .soft_number import (
     SoftNumber, sadd, sneg, ssub, smul, sinv, sdiv,
@@ -28,8 +29,8 @@ def __getattr__(name):
 
 
 __all__ = [
-    "SoftOpt", "SoftOptTorch", "SoftNumber", "soft_compile",
+    "SoftOpt", "SoftOptTorch", "SoftNumber", "soft_compile", "spsa_gradient",
     "sadd", "sneg", "ssub", "smul", "sinv", "sdiv",
     "spow", "sroot", "ssqrt", "ssin", "scos", "sexp", "slog",
 ]
-__version__ = "0.6.0"
+__version__ = "0.6.2"

{softopt-0.6.0 → softopt-0.6.2}/softopt/numpy_optimizer.py

@@ -7,10 +7,25 @@ derivative of your true objective along delta, computed from your own
 known model (circuit, projection, physical law). `soft_compile` generates
 this for you from a model written in ordinary Python.
 
-The correction is a bounded Newton step. The first directional derivative is
-exact, propagated through your model by soft-number arithmetic. The second is
-a central finite difference OF that exact derivative -- an approximation, with
-the usual step-size trade-off, controlled by h_fd.
+The correction is a bounded Newton step, t* = -D1 / D2 along a direction delta.
+D2 (the curvature) always comes from your model: a central finite difference
+OF the exact soft-number derivative, with the usual step-size trade-off,
+controlled by h_fd. D1 (the slope) has two possible sources, set by `slope`:
+
+  slope="model"     (default) D1 is the model's exact directional derivative
+                    along a fresh random direction. Robust to very noisy
+                    readings, but the correction pulls towards the MODEL's
+                    optimum: if the model is biased, so is the answer.
+
+  slope="measured"  D1 is the slope you measured on the real system, along the
+                    direction you measured it in (an SPSA difference gives you
+                    both for free). The model only supplies the curvature, so
+                    the fixed point is where the MEASURED slope vanishes: the
+                    real system's optimum, even when the model is off. Needs
+                    readings clean enough that the measured slope is informative.
+
+`spsa_gradient` returns the gradient estimate, the direction and the measured
+slope in one call, ready for either mode.
 """
 import numpy as np
 
@@ -18,7 +33,10 @@ import numpy as np
 class SoftOpt:
     def __init__(self, n_params, g_delta, lr=0.02, betas=(0.9, 0.999), eps=1e-8,
                  newton_lo=-0.5, newton_hi=0.5, eta_fallback=0.3,
-                 h_fd=1e-4, seed=None, _test_frozen_constant=1.0):
+                 h_fd=1e-4, seed=None, slope="model", _test_frozen_constant=1.0):
+        if slope not in ("model", "measured"):
+            raise ValueError(f'slope must be "model" or "measured", got {slope!r}')
+        self.slope = slope
         self.g_delta = g_delta
         self.lr = lr
         self.b1, self.b2 = betas
@@ -34,13 +52,19 @@ class SoftOpt:
         self._ablation_rng = None
         self._test_frozen_constant = _test_frozen_constant
 
-    def step(self, theta, grad_estimate, _test_magnitude_source=None, _test_foreign_sampler=None, _test_rng=None):
+    def step(self, theta, grad_estimate, direction=None, measured_slope=None,
+             _test_magnitude_source=None, _test_foreign_sampler=None, _test_rng=None):
         """One complete optimizer step: Adam base update + Newton-style
         correction from the known model, in a single call.
         theta: current parameters (np.ndarray)
         grad_estimate: a gradient estimate of the loss w.r.t. theta (e.g.
             from SPSA or backprop) -- exactly what you'd normally hand
             to Adam.
+        direction, measured_slope: required when slope="measured", ignored
+            otherwise. The direction your readings probed and the slope you
+            measured along it at theta, e.g. for SPSA
+            (f(theta + c*d) - f(theta - c*d)) / (2c) along d.
+            spsa_gradient() returns both.
         Returns: theta for the next step.
 
         The _test_* arguments are TEST-ONLY hooks used exclusively by the
@@ -53,6 +77,13 @@ class SoftOpt:
         """
         theta = np.asarray(theta, dtype=float)
         grad_estimate = np.asarray(grad_estimate, dtype=float)
+        if self.slope == "measured":
+            if direction is None or measured_slope is None:
+                raise ValueError('slope="measured" needs direction= and measured_slope= on every '
+                                 'step (spsa_gradient() returns both)')
+            direction = np.asarray(direction, dtype=float)
+            if direction.shape != theta.shape:
+                raise ValueError(f"direction has shape {direction.shape}, theta has {theta.shape}")
 
         # --- Adam base update ---
         self.t += 1
@@ -70,8 +101,11 @@ class SoftOpt:
 
         # --- correction from the known, exact model ---
         n = theta.shape[0]
-        gen_rng = _test_rng if _test_rng is not None else self.rng
-        delta = gen_rng.choice([-1.0, 1.0], size=n)
+        if self.slope == "measured":
+            delta = direction
+        else:
+            gen_rng = _test_rng if _test_rng is not None else self.rng
+            delta = gen_rng.choice([-1.0, 1.0], size=n)
 
         # The ablation arms must not disturb the probe-direction stream, or
         # a corrupted arm would also change every direction that follows and
@@ -79,7 +113,10 @@ class SoftOpt:
         if self._ablation_rng is None:
             self._ablation_rng = np.random.default_rng(
                 self.rng.integers(0, 2**63 - 1))
-        D1 = self.g_delta(theta_after_adam, delta)
+        if self.slope == "measured":
+            D1 = float(measured_slope)       # from the real system
+        else:
+            D1 = self.g_delta(theta_after_adam, delta)
         gp = self.g_delta(theta_after_adam + self.h_fd * delta, delta)
         gm = self.g_delta(theta_after_adam - self.h_fd * delta, delta)
         D2_real = (gp - gm) / (2 * self.h_fd)
@@ -104,3 +141,18 @@ class SoftOpt:
             t_star = float(np.clip(-self.eta_fallback * D1, self.newton_lo, self.newton_hi))
 
         return theta_after_adam + t_star * delta
+
+
+def spsa_gradient(measure, theta, c=0.1, rng=None):
+    """One SPSA probe of a noisy objective.
+
+    measure: callable theta -> one (noisy) reading of the real system.
+    Returns (grad_estimate, direction, measured_slope), where measured_slope
+    is (measure(theta + c*d) - measure(theta - c*d)) / (2c) along the random
+    +-1 direction d, and grad_estimate = measured_slope * d. Costs 2 readings.
+    """
+    theta = np.asarray(theta, dtype=float)
+    rng = np.random.default_rng() if rng is None else rng
+    d = rng.choice([-1.0, 1.0], size=theta.shape)
+    slope = (measure(theta + c * d) - measure(theta - c * d)) / (2 * c)
+    return slope * d, d, float(slope)

{softopt-0.6.0 → softopt-0.6.2/softopt.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: softopt
-Version: 0.6.0
+Version: 0.6.2
 Summary: A standalone optimizer for problems with a known computation graph, built on Klein–Maimon soft-number calculus
 Author: Ido Angel
 License: MIT
@@ -85,7 +85,7 @@ is the mechanism.
 But at 10 qubits both arms covered only a few percent of the way to the ground
 state. 1.5× of very little is still very little. **If the plateau is your
 problem, this is not the fix.** The scan and its replication are in
-`benchmarks/barren_plateau/`.
+`benchmarks_barren_plateau/`.
 
 ## Installation
 
@@ -122,6 +122,32 @@ The one thing to avoid is converting a traced value back to a plain number mid-m
 
 If you'd rather write the derivative function yourself — because your model lives in a simulator SoftOpt can't trace, or because you want the speed of a hand-tuned implementation — pass any `g_delta(theta, delta)` that returns the exact directional derivative, and skip `soft_compile` entirely.
 
+## Where the slope comes from: `slope="model"` or `slope="measured"`
+
+Every correction is a Newton step, `-slope / curvature`, taken along one direction. The curvature always comes from your model. The slope has two possible sources:
+
+| | `slope="model"` (default) | `slope="measured"` (new in 0.6.1) |
+|---|---|---|
+| slope from | your model's exact derivative | your readings, along the direction you probed |
+| converges to | the **model's** optimum | the **real system's** optimum |
+| choose it when | the model is accurate and the readings are very noisy | the model may be biased, and the readings are clean enough to show the slope |
+
+With `slope="model"`, a model whose optimum is in the wrong place pulls the answer to the wrong place. `slope="measured"` uses the model only for the shape of the landscape, so the readings decide where the optimum is. An SPSA probe already measures that slope, so the measured mode costs no extra readings:
+
+```python
+from softopt import SoftOpt, soft_compile, spsa_gradient
+
+opt = SoftOpt(n, soft_compile(my_model, n_params=n), lr=0.05, slope="measured")
+
+for step in range(num_steps):
+    grad, direction, slope = spsa_gradient(measure, theta, c=0.1)   # 2 readings
+    theta = opt.step(theta, grad, direction=direction, measured_slope=slope)
+```
+
+`measure(theta)` returns one reading of the real system. If you already compute your own SPSA estimate, pass its direction `d` and `(f(θ+cd) - f(θ-cd)) / 2c` as `measured_slope`.
+
+If your model is exact, you do not need either mode, or any readings: optimise the model directly.
+
 ## PyTorch
 
 If your known model is written in PyTorch, `SoftOptTorch` runs the same step as a `torch.optim.Optimizer`: an Adam update from the gradient, then the bounded Newton correction. The directional derivative and the curvature along the probe direction come from PyTorch's forward-mode AD (`torch.func.jvp`, nested once), which is single-axis soft-number propagation executed by PyTorch's own engine. It runs wherever your model runs: CPU, CUDA or Apple MPS.
@@ -169,6 +195,15 @@ All results below use IBM's `FakeFez` noise model via Qiskit + Aer, or realistic
 | BeH₂ | 94.7% | 5/5 |
 | HeH⁺ | 90.9% | 5/5 |
 
+**Quantum chemistry on a real molecule, and against COBYLA**
+
+| Test | Baseline | Result | Win rate |
+|---|---|---|---|
+| H₄ molecule (STO-3G, 8 qubits, 185 Pauli terms), 100 steps | Adam | 67% smaller gap to the ground state (409 vs 1227 mHa) | 10/10 |
+| H₂, same budget of 180 device readings | COBYLA | 0.11 vs 5.81 mHa above the ground state; chemical accuracy in 10/10 runs vs 3/10 | 10/10 |
+
+Both run SoftOpt with its default settings on IBM's `FakeFez` noise model: `benchmarks/vqe/h4_real_molecule.py`, `benchmarks/vqe/h2_vs_cobyla.py`.
+
 **Quantum control**
 
 | Domain | Improvement | Win rate |

{softopt-0.6.0 → softopt-0.6.2}/softopt.egg-info/SOURCES.txt

@@ -14,5 +14,6 @@ softopt.egg-info/top_level.txt
 tests/test_basic.py
 tests/test_causal.py
 tests/test_compile.py
+tests/test_measured_slope.py
 tests/test_soft_number.py
 tests/test_torch.py

softopt-0.6.2/tests/test_measured_slope.py

@@ -0,0 +1,77 @@
+"""slope="measured": slope from the real system, curvature from the model."""
+import numpy as np
+import pytest
+from softopt import SoftOpt, soft_compile, spsa_gradient
+
+N = 6
+SHIFT = np.array([0.8, -0.6, 0.5, -0.4, 0.7, -0.5])   # the model's optimum is off by this
+
+
+def truth(x):
+    return float(np.sum(np.asarray(x) ** 2))
+
+
+def biased_model(th):
+    return sum((t - s) ** 2 for t, s in zip(th, SHIFT))
+
+
+def _run(slope, steps=400, seed=0):
+    g_delta = soft_compile(biased_model, n_params=N)
+    opt = SoftOpt(N, g_delta, lr=0.05, seed=seed, slope=slope)
+    rng = np.random.default_rng(seed)
+    x = np.full(N, 2.0)
+    for _ in range(steps):
+        g, d, s = spsa_gradient(truth, x, c=0.1, rng=rng)
+        x = opt.step(x, g, direction=d, measured_slope=s)
+    return x
+
+
+def test_measured_slope_finds_the_real_optimum_despite_a_biased_model():
+    x = _run("measured")
+    assert np.allclose(x, 0.0, atol=0.05)          # the system's optimum
+
+
+def test_model_slope_follows_the_model():
+    x = _run("model")
+    # documented behaviour: the correction pulls towards the model's optimum
+    assert np.linalg.norm(x - SHIFT) < np.linalg.norm(x - 0.0)
+
+
+def test_measured_mode_requires_direction_and_slope():
+    opt = SoftOpt(N, soft_compile(biased_model, n_params=N), slope="measured")
+    with pytest.raises(ValueError, match="direction"):
+        opt.step(np.ones(N), np.ones(N))
+    with pytest.raises(ValueError, match="shape"):
+        opt.step(np.ones(N), np.ones(N), direction=np.ones(N + 1), measured_slope=1.0)
+
+
+def test_unknown_slope_mode_rejected():
+    with pytest.raises(ValueError, match="slope"):
+        SoftOpt(N, lambda t, d: 0.0, slope="both")
+
+
+def test_model_mode_ignores_direction_arguments():
+    g_delta = soft_compile(biased_model, n_params=N)
+    a = SoftOpt(N, g_delta, lr=0.05, seed=3)
+    b = SoftOpt(N, g_delta, lr=0.05, seed=3)
+    x = np.ones(N)
+    xa = a.step(x, 2 * x)
+    xb = b.step(x, 2 * x, direction=-np.ones(N), measured_slope=123.0)
+    assert np.array_equal(xa, xb)
+
+
+def test_spsa_gradient_on_a_linear_function_is_exact():
+    w = np.arange(1.0, N + 1)
+    g, d, s = spsa_gradient(lambda x: float(w @ x), np.zeros(N), c=0.3, rng=np.random.default_rng(0))
+    assert s == pytest.approx(w @ d)
+    assert np.allclose(g, s * d)
+    assert set(np.unique(d)) <= {-1.0, 1.0}
+
+
+def test_frozen_ablation_hook_works_in_measured_mode():
+    g_delta = soft_compile(biased_model, n_params=N)
+    opt = SoftOpt(N, g_delta, lr=0.05, seed=0, slope="measured")
+    x = np.ones(N)
+    g, d, s = spsa_gradient(truth, x, rng=np.random.default_rng(1))
+    out = opt.step(x, g, direction=d, measured_slope=s, _test_magnitude_source="frozen")
+    assert out.shape == x.shape and np.all(np.isfinite(out))