PyPI - softopt - Versions diffs - 0.6.4__tar.gz → 0.7.0__tar.gz - Mend

softopt 0.6.4tar.gz → 0.7.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

{softopt-0.6.4/softopt.egg-info → softopt-0.7.0}/PKG-INFO RENAMED Viewed

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: softopt
-Version: 0.6.4
-Summary: A standalone optimizer for problems with a known computation graph, built on Klein–Maimon soft-number calculus
+Version: 0.7.0
+Summary: An optimization layer that closes the gap between your model and the real system, built on Klein–Maimon soft-number calculus
 Author: Ido Angel
 License: MIT
 Project-URL: Homepage, https://github.com/mobiuai/softopt
 Project-URL: Repository, https://github.com/mobiuai/softopt
 Project-URL: Issues, https://github.com/mobiuai/softopt/issues
-Keywords: optimizer,optimization,soft-logic,soft-numbers,uncertainty,sensitivity,quantum-computing,vqe
+Keywords: optimizer,optimization,soft-logic,soft-numbers,uncertainty,sensitivity,calibration,digital-twin,sim-to-real,quantum-computing,vqe
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -26,66 +26,126 @@ Dynamic: license-file
 # SoftOpt
-**A standalone optimizer that excels against leading market optimizers like Adam, in problems with a known, differentiable computation graph.**
+**An optimization layer that closes the gap between your model and the real system.**
-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.
+You have a model of your system — a simulator, a circuit, a physical law, a pharmacokinetic model — and you
+measure the real thing, where every measurement costs time or money. SoftOpt sits on top of Adam and, on every
+step, takes an exact Newton correction from your model through Klein–Maimon soft-number calculus (*Foundations
+of Soft Logic*, Klein & Maimon, Springer 2024). With `calibrate=True` the same measurements also correct the
+model's uncertain parameters while the optimization runs, so the correction keeps pointing at the real system's
+optimum instead of the model's.
-## Is SoftOpt the right tool for your problem?
+**When your model is exact** — a quantum circuit, a known physical law — SoftOpt gets closer to the true optimum
+than Adam and COBYLA. On H₂ on IBM's FakeFez noise model it reaches chemical accuracy in 10 of 10 runs against
+COBYLA's 3 of 10 (0.11 vs 5.81 mHa, same 180 readings); on the H₄ molecule (8 qubits, 185 Pauli terms) its gap to
+the ground state is 67% smaller than Adam's, 10/10; in two-qubit quantum control, 84% smaller, 20/20.
-One question decides it, and you can answer it without running anything.
+**When your model is approximately right** — the usual case on real systems — `calibrate=True` closes the gap.
+Across eleven domains — quantum chemistry, beam steering, robotics, chemical engineering, drug dosing, finance,
+building control, batteries, epidemiology, machine learning and an exact-model control — SoftOpt with
+`calibrate=True` reaches the quality Adam reaches after 200 measurements with **2.65× fewer measurements**
+(median; 1.35× to 5.4× by domain).
-**Can you get a residual vector?** That is: can you compute
-`model(theta) - data` and get back an *array*, rather than a single number?
+Free, open source, and runs locally.
-- **Yes** → use `scipy.optimize.least_squares`. It builds the full Jacobian and
-  exploits the least-squares structure, and it will beat SoftOpt on both
-  accuracy and speed. This holds regardless of how large or how noisy the
-  problem is. We measured it: on solar-cell parameter extraction, `least_squares`
-  reached 7.9 mA against SoftOpt's 37.3 mA, and did it 21x faster.
+## When to use it
-- **No** → SoftOpt is built for this case. Each evaluation returns **one number,
-  and it is noisy**: a quantum measurement, a laser-tracker sweep, a backtest, a
-  simulator that returns a score. There is no residual vector for
-  `least_squares` to work with, and finite-difference methods like L-BFGS-B end
-  up differentiating the noise rather than the model.
+**You have a model of your system and you measure the real one?** Use `calibrate=True` and name the model
+parameters you are not sure of, with a generous estimate of how far off they may be.
-SoftOpt's advantage comes from taking the derivative **from your model** instead
-of from your measurements. That only matters when the measurements are the noisy
-part. Every validated domain below is of the second kind; that is not a
-convenience of selection, it is where the mechanism applies.
+```python
+from softopt import SoftOpt, soft_compile, spsa_gradient
+def model(theta, beta):            # your simulator; beta = offsets of its uncertain parameters (0 = nominal)
+    ...
+g = soft_compile(model, n_params=n, n_bias=k)
+opt = SoftOpt(n, g, lr=0.05, calibrate=True, bias_scale=0.2)   # bias_scale: expected size of beta (generous)
+for step in range(num_steps):
+    grad, direction, slope = spsa_gradient(measure, theta, c=0.1)       # 2 measurements of the real system
+    theta = opt.step(theta, grad, direction=direction, measured_slope=slope)
+opt.calibration     # the current estimates: beta, contrast, and the discrepancy the model cannot explain
+```
-## Where it helps
+Everything else stays as it was: the same Adam update, the same measurements, no extra readings. When unsure of
+`bias_scale`, err on the wide side.
-If your problem has a **known computation graph** — a quantum circuit, a physical simulator, a projection or measurement model, anything you can write down exactly, even if the *measurements* of it are noisy — SoftOpt computes an exact directional derivative of that model on every step, plus the curvature along the same direction, and uses them to correct the optimizer's trajectory. Validated, with real hardware-noise-model data, across:
+| your situation | the tool |
+|---|---|
+| a model with uncertain parameters + measurements of the real system | **SoftOpt, `calibrate=True`** |
+| an exact model + noisy measurements | SoftOpt, default settings |
+| you can compute a residual vector `model(theta) - data` | `scipy.optimize.least_squares` |
+| only a learned black-box surrogate (a neural network) + an expensive oracle | Bayesian optimization |
-- **Quantum chemistry (VQE)** — H₂, H₄, BeH₂, HeH⁺, and larger multireference molecules
-- **Quantum control (GRAPE)** — the single cleanest result across every domain tested
-- **Computer vision** — multi-camera bundle adjustment / camera calibration
-- **Finance** — portfolio optimization (Markowitz mean-variance)
-- **Condensed-matter physics** — quasicrystal and spin-chain models (Ising, XY, Heisenberg, SSH, Kitaev)
-- Pharmacokinetics, logistic regression, and more
+## What `calibrate=True` does (new in 0.7.0)
-## Where it does *not* help
+The model is evaluated on nested soft numbers: one soft axis along the probe direction, the other along each
+uncertain parameter. The mixed part of the result is the exact sensitivity of the model's predicted slope to
+that parameter, and every measured slope updates the parameters through it (a Kalman filter). Whatever the
+parameters cannot explain is carried as an explicit discrepancy term on the soft axis. Each correction is
+SoftOpt's bounded Newton step on the calibrated model, sized by how certain the calibrated prediction is, and the
+calibrated model is evaluated at the target before the step is taken.
-Full reinforcement learning (or anything else with a continuously **moving target** — a policy, an adversary, a non-stationary distribution) is outside SoftOpt's validated scope. The mechanism needs a *fixed* objective to compute a meaningful correction against; a moving target breaks that assumption. Use plain Adam/SGD there.
+`calibrate=True` also works on a plain `model(theta)` with no bias parameters; naming the uncertain parameters is
+what makes it reliable across domains.
-**Barren plateaus.** In a deep hardware-efficient circuit at random
-initialisation, the gradient decays exponentially in the qubit count and the
-shot-noise measurement of it is larger than the thing it measures. An exact
-derivative still helps there — it comes from the circuit, so it stays exact
-however flat the landscape gets — but it does not remove the barrier.
+## Results across domains
-We measured this at 4–10 qubits on a transverse-field Ising chain: SoftOpt
-covers **1.4–1.6× as much of the distance to the ground state** as Adam, and
-that ratio held across three seed streams, five shot budgets (512 to 65536),
-five SPSA probe sizes and three different Hamiltonians — 316 wins in 320 runs
-across 16 conditions. The advantage *grows* as the measurement degrades, which
-is the mechanism.
+One small problem per domain, one protocol for all: the model is the domain's standard simulator with its
+uncertain parameters offset at random, the real system also carries an effect the model does not have
+(except in the exact-model control),
+measurements are noisy, 200 measurements, 10 seeds, the same start, Adam at its best of five learning rates and
+SoftOpt at Adam's. `benchmarks/softbench/`.
-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/`.
+**Measurements needed to reach the quality Adam reaches with 200**
+| domain | SoftOpt `calibrate=True` | runs that got there |
+|---|---|---|
+| Quantum chemistry (H₂) | **5.4× fewer** | 10/10 |
+| Epidemic control (vaccination) | **4.3× fewer** | 10/10 |
+| Drug dosing (pharmacokinetics) | **3.3× fewer** | 10/10 |
+| Portfolio optimization | **3.0× fewer** | 10/10 |
+| Exact-model control | **3.0× fewer** | 10/10 |
+| RF beam steering (phased array) | **2.7× fewer** | 9/10 |
+| Batch chemical reactor | **2.2× fewer** | 10/10 |
+| Robot arm controller tuning | **1.9× fewer** | 8/10 |
+| Classifier under data shift | **1.9× fewer** | 8/10 |
+| Building thermal control | **1.8× fewer** | 6/10 |
+| Battery fast charging | **1.35× fewer** | 7/10 |
+**Remaining gap to the true optimum after 200 measurements** (fraction of the starting gap; median)
+| domain | Adam | COBYLA | SoftOpt default | **SoftOpt `calibrate=True`** |
+|---|---|---|---|---|
+| Quantum chemistry (H₂) | 0.0010 | 0.012 | 0.0040 | **0.0001** |
+| RF beam steering | 0.0043 | 0.053 | 0.079 | **0.0026** |
+| Robot arm tuning | 0.0125 | 0.026 | 0.024 | **0.0027** |
+| Batch reactor | 0.0065 | 0.14 | 0.029 | **0.0023** |
+| Drug dosing | 0.0198 | 0.056 | 0.067 | **0.0016** |
+| Portfolio | 0.052 | 0.10 | 0.68 | **0.030** |
+| Battery charging | 0.032 | 0.17 | 1.38 | **0.023** |
+| Building thermal control | 0.0089 | 0.069 | 0.046 | 0.0148 |
+| Epidemic control | 0.0081 | 0.024 | ~0 | 0.0035 |
+| Classifier under data shift | 0.22 | 0.49 | 0.105 | 0.23 |
+| Exact-model control | 0.0026 | 0.0048 | 0.00009 | 0.00016 |
+**Quantum chemistry with gate errors, on IBM's FakeFez noise model**
+H₂ on a device whose gates carry coherent errors (over-rotations, phase offsets, residual coupling), so the
+ideal circuit no longer points at the right parameters. 180 device readings, 20 new seeds:
+| | energy above the ground state (mHa, median) |
+|---|---|
+| Adam | 4.7 |
+| COBYLA | 2.6 |
+| SoftOpt, default | 13.0 |
+| **SoftOpt, `calibrate=True`** | **0.42** (better than Adam 20/20, than COBYLA 16/20) |
+With gate errors twice as large: 0.48 mHa, against Adam 4.8 and COBYLA 2.1. On a two-qubit gate calibration
+task (18 angles, FakeFez, hidden coherent errors) the calibrated layer reaches 1.4e-4 infidelity against
+Adam's 3.7e-4 (18/20), and in sensorless adaptive optics 0.0023 against 0.0041 (17/20).
 ## Installation
@@ -298,10 +358,14 @@ The full soft-number algebra is available from the package (`from softopt import
 `SoftNumber` wraps these with operator syntax (`x + y`, `x * y`, `x ** 3`, `x.sqrt()`) and is verified, axiom by axiom, against the book's own proofs that bridge numbers form an abelian group under addition and a ring under both operations (`tests/test_soft_number.py`).
-## What SoftOpt is *not*
+## Choosing between the modes
+- `calibrate=True` — your model has parameters you are not sure of. The recommended starting point whenever you
+  measure a real system.
+- default (`slope="model"`) — your model is exact; the measurements are only noisy.
+- `slope="measured"` — the model is approximate and you do not want to name its uncertain parameters.
-- Not a claim to beat specialized full-Jacobian second-order solvers (Levenberg–Marquardt, L-BFGS) where those are already practical — SoftOpt's validated niche is genuine improvement over first-order optimizers (Adam, SGD) already in use, particularly where switching to a full second-order method isn't practical (embedded in a larger pipeline, high dimensionality, or measurement noise).
-- Not a general-purpose black-box optimizer — it requires a known computation graph, as described above.
+`calibrate=True` is available in `SoftOpt` (numpy). `SoftOptTorch` runs the default correction.
 ## License

{softopt-0.6.4 → softopt-0.7.0}/README.md RENAMED Viewed

@@ -1,65 +1,125 @@
 # SoftOpt
-**A standalone optimizer that excels against leading market optimizers like Adam, in problems with a known, differentiable computation graph.**
+**An optimization layer that closes the gap between your model and the real system.**
-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.
+You have a model of your system — a simulator, a circuit, a physical law, a pharmacokinetic model — and you
+measure the real thing, where every measurement costs time or money. SoftOpt sits on top of Adam and, on every
+step, takes an exact Newton correction from your model through Klein–Maimon soft-number calculus (*Foundations
+of Soft Logic*, Klein & Maimon, Springer 2024). With `calibrate=True` the same measurements also correct the
+model's uncertain parameters while the optimization runs, so the correction keeps pointing at the real system's
+optimum instead of the model's.
-## Is SoftOpt the right tool for your problem?
+**When your model is exact** — a quantum circuit, a known physical law — SoftOpt gets closer to the true optimum
+than Adam and COBYLA. On H₂ on IBM's FakeFez noise model it reaches chemical accuracy in 10 of 10 runs against
+COBYLA's 3 of 10 (0.11 vs 5.81 mHa, same 180 readings); on the H₄ molecule (8 qubits, 185 Pauli terms) its gap to
+the ground state is 67% smaller than Adam's, 10/10; in two-qubit quantum control, 84% smaller, 20/20.
-One question decides it, and you can answer it without running anything.
+**When your model is approximately right** — the usual case on real systems — `calibrate=True` closes the gap.
+Across eleven domains — quantum chemistry, beam steering, robotics, chemical engineering, drug dosing, finance,
+building control, batteries, epidemiology, machine learning and an exact-model control — SoftOpt with
+`calibrate=True` reaches the quality Adam reaches after 200 measurements with **2.65× fewer measurements**
+(median; 1.35× to 5.4× by domain).
-**Can you get a residual vector?** That is: can you compute
-`model(theta) - data` and get back an *array*, rather than a single number?
+Free, open source, and runs locally.
-- **Yes** → use `scipy.optimize.least_squares`. It builds the full Jacobian and
-  exploits the least-squares structure, and it will beat SoftOpt on both
-  accuracy and speed. This holds regardless of how large or how noisy the
-  problem is. We measured it: on solar-cell parameter extraction, `least_squares`
-  reached 7.9 mA against SoftOpt's 37.3 mA, and did it 21x faster.
+## When to use it
-- **No** → SoftOpt is built for this case. Each evaluation returns **one number,
-  and it is noisy**: a quantum measurement, a laser-tracker sweep, a backtest, a
-  simulator that returns a score. There is no residual vector for
-  `least_squares` to work with, and finite-difference methods like L-BFGS-B end
-  up differentiating the noise rather than the model.
+**You have a model of your system and you measure the real one?** Use `calibrate=True` and name the model
+parameters you are not sure of, with a generous estimate of how far off they may be.
-SoftOpt's advantage comes from taking the derivative **from your model** instead
-of from your measurements. That only matters when the measurements are the noisy
-part. Every validated domain below is of the second kind; that is not a
-convenience of selection, it is where the mechanism applies.
+```python
+from softopt import SoftOpt, soft_compile, spsa_gradient
+def model(theta, beta):            # your simulator; beta = offsets of its uncertain parameters (0 = nominal)
+    ...
+g = soft_compile(model, n_params=n, n_bias=k)
+opt = SoftOpt(n, g, lr=0.05, calibrate=True, bias_scale=0.2)   # bias_scale: expected size of beta (generous)
+for step in range(num_steps):
+    grad, direction, slope = spsa_gradient(measure, theta, c=0.1)       # 2 measurements of the real system
+    theta = opt.step(theta, grad, direction=direction, measured_slope=slope)
+opt.calibration     # the current estimates: beta, contrast, and the discrepancy the model cannot explain
+```
-## Where it helps
+Everything else stays as it was: the same Adam update, the same measurements, no extra readings. When unsure of
+`bias_scale`, err on the wide side.
-If your problem has a **known computation graph** — a quantum circuit, a physical simulator, a projection or measurement model, anything you can write down exactly, even if the *measurements* of it are noisy — SoftOpt computes an exact directional derivative of that model on every step, plus the curvature along the same direction, and uses them to correct the optimizer's trajectory. Validated, with real hardware-noise-model data, across:
+| your situation | the tool |
+|---|---|
+| a model with uncertain parameters + measurements of the real system | **SoftOpt, `calibrate=True`** |
+| an exact model + noisy measurements | SoftOpt, default settings |
+| you can compute a residual vector `model(theta) - data` | `scipy.optimize.least_squares` |
+| only a learned black-box surrogate (a neural network) + an expensive oracle | Bayesian optimization |
-- **Quantum chemistry (VQE)** — H₂, H₄, BeH₂, HeH⁺, and larger multireference molecules
-- **Quantum control (GRAPE)** — the single cleanest result across every domain tested
-- **Computer vision** — multi-camera bundle adjustment / camera calibration
-- **Finance** — portfolio optimization (Markowitz mean-variance)
-- **Condensed-matter physics** — quasicrystal and spin-chain models (Ising, XY, Heisenberg, SSH, Kitaev)
-- Pharmacokinetics, logistic regression, and more
+## What `calibrate=True` does (new in 0.7.0)
-## Where it does *not* help
+The model is evaluated on nested soft numbers: one soft axis along the probe direction, the other along each
+uncertain parameter. The mixed part of the result is the exact sensitivity of the model's predicted slope to
+that parameter, and every measured slope updates the parameters through it (a Kalman filter). Whatever the
+parameters cannot explain is carried as an explicit discrepancy term on the soft axis. Each correction is
+SoftOpt's bounded Newton step on the calibrated model, sized by how certain the calibrated prediction is, and the
+calibrated model is evaluated at the target before the step is taken.
-Full reinforcement learning (or anything else with a continuously **moving target** — a policy, an adversary, a non-stationary distribution) is outside SoftOpt's validated scope. The mechanism needs a *fixed* objective to compute a meaningful correction against; a moving target breaks that assumption. Use plain Adam/SGD there.
+`calibrate=True` also works on a plain `model(theta)` with no bias parameters; naming the uncertain parameters is
+what makes it reliable across domains.
-**Barren plateaus.** In a deep hardware-efficient circuit at random
-initialisation, the gradient decays exponentially in the qubit count and the
-shot-noise measurement of it is larger than the thing it measures. An exact
-derivative still helps there — it comes from the circuit, so it stays exact
-however flat the landscape gets — but it does not remove the barrier.
+## Results across domains
-We measured this at 4–10 qubits on a transverse-field Ising chain: SoftOpt
-covers **1.4–1.6× as much of the distance to the ground state** as Adam, and
-that ratio held across three seed streams, five shot budgets (512 to 65536),
-five SPSA probe sizes and three different Hamiltonians — 316 wins in 320 runs
-across 16 conditions. The advantage *grows* as the measurement degrades, which
-is the mechanism.
+One small problem per domain, one protocol for all: the model is the domain's standard simulator with its
+uncertain parameters offset at random, the real system also carries an effect the model does not have
+(except in the exact-model control),
+measurements are noisy, 200 measurements, 10 seeds, the same start, Adam at its best of five learning rates and
+SoftOpt at Adam's. `benchmarks/softbench/`.
-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/`.
+**Measurements needed to reach the quality Adam reaches with 200**
+| domain | SoftOpt `calibrate=True` | runs that got there |
+|---|---|---|
+| Quantum chemistry (H₂) | **5.4× fewer** | 10/10 |
+| Epidemic control (vaccination) | **4.3× fewer** | 10/10 |
+| Drug dosing (pharmacokinetics) | **3.3× fewer** | 10/10 |
+| Portfolio optimization | **3.0× fewer** | 10/10 |
+| Exact-model control | **3.0× fewer** | 10/10 |
+| RF beam steering (phased array) | **2.7× fewer** | 9/10 |
+| Batch chemical reactor | **2.2× fewer** | 10/10 |
+| Robot arm controller tuning | **1.9× fewer** | 8/10 |
+| Classifier under data shift | **1.9× fewer** | 8/10 |
+| Building thermal control | **1.8× fewer** | 6/10 |
+| Battery fast charging | **1.35× fewer** | 7/10 |
+**Remaining gap to the true optimum after 200 measurements** (fraction of the starting gap; median)
+| domain | Adam | COBYLA | SoftOpt default | **SoftOpt `calibrate=True`** |
+|---|---|---|---|---|
+| Quantum chemistry (H₂) | 0.0010 | 0.012 | 0.0040 | **0.0001** |
+| RF beam steering | 0.0043 | 0.053 | 0.079 | **0.0026** |
+| Robot arm tuning | 0.0125 | 0.026 | 0.024 | **0.0027** |
+| Batch reactor | 0.0065 | 0.14 | 0.029 | **0.0023** |
+| Drug dosing | 0.0198 | 0.056 | 0.067 | **0.0016** |
+| Portfolio | 0.052 | 0.10 | 0.68 | **0.030** |
+| Battery charging | 0.032 | 0.17 | 1.38 | **0.023** |
+| Building thermal control | 0.0089 | 0.069 | 0.046 | 0.0148 |
+| Epidemic control | 0.0081 | 0.024 | ~0 | 0.0035 |
+| Classifier under data shift | 0.22 | 0.49 | 0.105 | 0.23 |
+| Exact-model control | 0.0026 | 0.0048 | 0.00009 | 0.00016 |
+**Quantum chemistry with gate errors, on IBM's FakeFez noise model**
+H₂ on a device whose gates carry coherent errors (over-rotations, phase offsets, residual coupling), so the
+ideal circuit no longer points at the right parameters. 180 device readings, 20 new seeds:
+| | energy above the ground state (mHa, median) |
+|---|---|
+| Adam | 4.7 |
+| COBYLA | 2.6 |
+| SoftOpt, default | 13.0 |
+| **SoftOpt, `calibrate=True`** | **0.42** (better than Adam 20/20, than COBYLA 16/20) |
+With gate errors twice as large: 0.48 mHa, against Adam 4.8 and COBYLA 2.1. On a two-qubit gate calibration
+task (18 angles, FakeFez, hidden coherent errors) the calibrated layer reaches 1.4e-4 infidelity against
+Adam's 3.7e-4 (18/20), and in sensorless adaptive optics 0.0023 against 0.0041 (17/20).
 ## Installation
@@ -272,10 +332,14 @@ The full soft-number algebra is available from the package (`from softopt import
 `SoftNumber` wraps these with operator syntax (`x + y`, `x * y`, `x ** 3`, `x.sqrt()`) and is verified, axiom by axiom, against the book's own proofs that bridge numbers form an abelian group under addition and a ring under both operations (`tests/test_soft_number.py`).
-## What SoftOpt is *not*
+## Choosing between the modes
+- `calibrate=True` — your model has parameters you are not sure of. The recommended starting point whenever you
+  measure a real system.
+- default (`slope="model"`) — your model is exact; the measurements are only noisy.
+- `slope="measured"` — the model is approximate and you do not want to name its uncertain parameters.
-- Not a claim to beat specialized full-Jacobian second-order solvers (Levenberg–Marquardt, L-BFGS) where those are already practical — SoftOpt's validated niche is genuine improvement over first-order optimizers (Adam, SGD) already in use, particularly where switching to a full second-order method isn't practical (embedded in a larger pipeline, high dimensionality, or measurement noise).
-- Not a general-purpose black-box optimizer — it requires a known computation graph, as described above.
+`calibrate=True` is available in `SoftOpt` (numpy). `SoftOptTorch` runs the default correction.
 ## License

{softopt-0.6.4 → softopt-0.7.0}/pyproject.toml RENAMED Viewed

@@ -4,15 +4,15 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "softopt"
-version = "0.6.4"
-description = "A standalone optimizer for problems with a known computation graph, built on Klein–Maimon soft-number calculus"
+version = "0.7.0"
+description = "An optimization layer that closes the gap between your model and the real system, built on Klein–Maimon soft-number calculus"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.9"
 authors = [
     { name = "Ido Angel" }
 ]
-keywords = ["optimizer", "optimization", "soft-logic", "soft-numbers", "uncertainty", "sensitivity", "quantum-computing", "vqe"]
+keywords = ["optimizer", "optimization", "soft-logic", "soft-numbers", "uncertainty", "sensitivity", "calibration", "digital-twin", "sim-to-real", "quantum-computing", "vqe"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Science/Research",

{softopt-0.6.4 → softopt-0.7.0}/softopt/__init__.py RENAMED Viewed

@@ -1,16 +1,16 @@
 """
-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, ...).
+SoftOpt — an optimization layer built on Klein–Maimon soft-number calculus that closes the gap between your
+model (a simulator, a circuit, a physical law) and the real system you measure.
-    from softopt import SoftOpt          # numpy version (slope="model" or "measured")
+    from softopt import SoftOpt          # numpy version (slope="model" or "measured"; calibrate=True)
     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
-See README.md for the exact requirement your problem must satisfy
-(the "known computation graph" criterion) and worked examples.
+calibrate=True (new in 0.7.0): soft_compile(model, n_params, n_bias=k) for model(theta, beta), then
+SoftOpt(..., calibrate=True, bias_scale=s) -- the measurements also calibrate the model's uncertain parameters.
+See README.md.
 """
 from .numpy_optimizer import SoftOpt, spsa_gradient
 from .compile import soft_compile
@@ -33,4 +33,4 @@ __all__ = [
     "sadd", "sneg", "ssub", "smul", "sinv", "sdiv",
     "spow", "sroot", "ssqrt", "ssin", "scos", "sexp", "slog",
 ]
-__version__ = "0.6.4"
+__version__ = "0.7.0"

softopt-0.7.0/softopt/calibrate.py ADDED Viewed

@@ -0,0 +1,159 @@
+"""
+Online calibration of the model against the real system (calibrate=True).
+The model you give SoftOpt is rarely exactly the system you are optimising: a simulator with approximate
+parameters, an ideal circuit on a device with gate errors, a nominal plant. With calibrate=True every SPSA
+pair you already measure is also used to correct the model while the optimisation runs -- no extra readings.
+What the soft algebra does here
+  The model is evaluated on nested soft numbers: one axis (eps1) along the probe direction d, the other
+  (eps2) along a bias parameter beta_j. The mixed eps1*eps2 part of the result is d D1 / d beta_j exactly --
+  how the model's predicted slope responds to each uncertain parameter. That is the measurement Jacobian of a
+  Kalman filter on beta: each measured slope s along d is explained as
+        s  ~  kappa * ( D1_model(x, d; beta) + dg . d )
+  kappa is the contrast the device loses (noise), and dg is the part of the slope the model cannot explain at
+  all (its eps-part is d itself, so it costs nothing). Two filters run on the same readings -- dg local
+  (forgotten at 0.95) and dg settled (not forgotten) -- and the one that has predicted the readings better so
+  far (log-likelihood) supplies the correction.
+The correction is SoftOpt's bounded Newton step on the CALIBRATED model, scaled by the filter's own
+confidence D1^2 / (D1^2 + var D1), and checked before it is taken: the calibrated model is evaluated at the
+target, and if it predicts no improvement the step is shortened to the minimum of the parabola through
+f(0), D1 and f(step).
+Two ways to use it
+  * calibrate=True with a plain model(theta): no bias parameters; only kappa and dg are learned.
+  * soft_compile(model(theta, beta), n_params, n_bias=k) and SoftOpt(..., calibrate=True, bias_scale=s):
+    beta are the model's uncertain parameters (offsets from their nominal values, 0 = nominal); bias_scale is
+    their expected size (a number or one per parameter), on the PHYSICAL scale -- a prior far too wide lets the
+    filter fit noise.
+Validated (development + held-out seeds) where the bias structure is right: gate calibration, adaptive optics,
+H2 with coherent gate errors, robot sim-to-real. When the model lacks a major error type the median is still at
+or below Adam but single runs can be worse; when the model is already exact, calibrate=False is better.
+"""
+import numpy as np
+from .soft_number import SoftNumber
+def _sn(e, a, c, v):
+    """v + c*eps_in + a*eps_out + e*eps_in*eps_out as a nested SoftNumber."""
+    return SoftNumber(SoftNumber(e, a), SoftNumber(c, v))
+def _parts(r):
+    if isinstance(r, SoftNumber):
+        outer_a, outer_b = r.a, r.b
+        e, a = (outer_a.a, outer_a.b) if isinstance(outer_a, SoftNumber) else (0.0, outer_a)
+        c, v = (outer_b.a, outer_b.b) if isinstance(outer_b, SoftNumber) else (0.0, outer_b)
+        return float(v), float(c), float(a), float(e)
+    return float(r), 0.0, 0.0, 0.0
+class CompiledModel:
+    """model_fn(theta) or model_fn(theta, beta) on nested soft numbers: D1/D2 along d, d D1 / d beta, value."""
+    def __init__(self, model_fn, n_bias=0):
+        self.f, self.nb = model_fn, int(n_bias)
+    def _call(self, th, bs):
+        return self.f(th, bs) if self.nb else self.f(th)
+    def d1_d2(self, x, d, beta):
+        th = [_sn(0.0, float(di), float(di), float(xi)) for xi, di in zip(x, d)]
+        bs = [_sn(0.0, 0.0, 0.0, float(b)) for b in beta]
+        _, D1, _, D2 = _parts(self._call(th, bs))
+        return D1, D2
+    def d1_and_jac(self, x, d, beta):
+        th = [_sn(0.0, 0.0, float(di), float(xi)) for xi, di in zip(x, d)]          # eps_in along d
+        jac, D1 = np.zeros(self.nb), None
+        for j in range(self.nb):
+            bs = [_sn(0.0, 1.0 if i == j else 0.0, 0.0, float(b)) for i, b in enumerate(beta)]  # eps_out along beta_j
+            _, D1, _, jac[j] = _parts(self._call(th, bs))
+        if D1 is None:
+            _, D1, _, _ = _parts(self._call(th, []))
+        return D1, jac
+    def value(self, x, beta):
+        th = [_sn(0.0, 0.0, 0.0, float(xi)) for xi in x]
+        bs = [_sn(0.0, 0.0, 0.0, float(b)) for b in beta]
+        return _parts(self._call(th, bs))[0]
+class Calibrator:
+    FORGETS = (0.95, 1.0)
+    def __init__(self, n, model, bias_scale=None):
+        self.n, self.M = n, model
+        nb = model.nb
+        if nb and bias_scale is None:
+            raise ValueError('calibrate=True with bias parameters needs bias_scale= (their expected size, '
+                             'on the physical scale)')
+        self.ib, self.ik, self.ig = slice(0, nb), nb, slice(nb + 1, nb + 1 + n)
+        self.F = []
+        for fg in self.FORGETS:
+            st = np.zeros(nb + 1 + n); st[nb] = 1.0
+            P = np.zeros((nb + 1 + n,) * 2)
+            if nb:
+                P[self.ib, self.ib] = np.diag(np.broadcast_to(np.asarray(bias_scale, float) ** 2, (nb,)))
+            P[nb, nb] = 0.2 ** 2
+            self.F.append(dict(forget=fg, state=st, P=P, r2=None, ll=0.0))
+        self.t = 0
+    def update(self, x, d, slope):
+        """One measured slope along d at x: update both filters and their evidence."""
+        ib, ik, ig, n = self.ib, self.ik, self.ig, self.n
+        for f in self.F:
+            st, P = f['state'], f['P']
+            D1, jac = self.M.d1_and_jac(x, d, st[ib])
+            pred = D1 + st[ig] @ d
+            innov = slope - st[ik] * pred
+            if f['r2'] is None:
+                f['r2'] = innov ** 2
+                P[ig, ig] = np.eye(n) * (f['r2'] / n)
+            else:
+                f['r2'] = 0.95 * f['r2'] + 0.05 * innov ** 2
+            P[ig, :] /= np.sqrt(f['forget']); P[:, ig] /= np.sqrt(f['forget'])
+            H = np.r_[st[ik] * jac, pred, st[ik] * d]
+            S = H @ P @ H + f['r2']
+            if S <= 0 or not np.isfinite(S):
+                continue
+            if self.t > 0:
+                f['ll'] += -0.5 * (np.log(S) + innov ** 2 / S)
+            K = P @ H / S
+            f['state'] = st + K * innov
+            f['P'] = P - np.outer(K, H @ P)
+        self.t += 1
+    def best(self):
+        return self.F[int(np.argmax([f['ll'] for f in self.F]))]
+    def correction(self, x, e, lo, hi, eta_fallback):
+        f = self.best(); st, P = f['state'], f['P']
+        beta, dg = st[self.ib], st[self.ig]
+        D1m, D2m = self.M.d1_d2(x, e, beta)
+        _, jac_e = self.M.d1_and_jac(x, e, beta)
+        D1 = D1m + dg @ e
+        h = np.r_[jac_e, 0.0, e]
+        var = max(float(h @ P @ h), 0.0)
+        t = -D1 / D2m if D2m > 1e-8 else -eta_fallback * D1
+        w = D1 ** 2 / (D1 ** 2 + var) if (D1 ** 2 + var) > 0 else 0.0
+        step = float(np.clip(w * t, lo, hi))
+        if step != 0.0:
+            f0 = self.M.value(x, beta)
+            for _ in range(20):
+                df = self.M.value(x + step * e, beta) - f0 + step * (dg @ e)
+                if df < 0:
+                    break
+                c = (df - D1 * step) / step ** 2
+                new = -D1 / (2 * c) if c > 0 else 0.5 * step
+                step = new if 0 < new / step < 1 else 0.5 * step
+        return step
+    @property
+    def state(self):
+        f = self.best(); st = f['state']
+        return dict(beta=st[self.ib].copy(), kappa=float(st[self.ik]), discrepancy=st[self.ig].copy(),
+                    local_discrepancy=f['forget'] < 1.0)

{softopt-0.6.4 → softopt-0.7.0}/softopt/compile.py RENAMED Viewed

@@ -27,13 +27,22 @@ import numpy as np
 from .soft_number import SoftNumber
-def soft_compile(model_fn, n_params=None, verify=True, verify_tol=1e-5):
+def soft_compile(model_fn, n_params=None, verify=True, verify_tol=1e-5, n_bias=0):
     """model_fn: takes a sequence of scalars, returns a scalar.
+    n_bias: for calibrate=True with bias parameters -- model_fn(theta, beta) then takes a second sequence of
+        n_bias uncertain model parameters (offsets from nominal, 0 = nominal); SoftOpt itself sees the nominal
+        model model_fn(theta, [0]*n_bias). See softopt.calibrate.
     n_params: needed only for verification.
     verify: check the compiled derivative against finite differences at a
         random point before returning it. Catches the common mistakes --
         a model that isn't actually differentiable, uses an unsupported
         operation, or silently drops the traced parameters."""
+    from .calibrate import CompiledModel
+    calibration = CompiledModel(model_fn, n_bias)
+    if n_bias:
+        _full = model_fn
+        model_fn = lambda theta: _full(theta, [0.0] * int(n_bias))           # noqa: E731  (nominal model)
     def g_delta(theta, delta):
         soft = [SoftNumber(float(d), float(t)) for t, d in zip(theta, delta)]
         result = model_fn(soft)
@@ -88,6 +97,8 @@ def soft_compile(model_fn, n_params=None, verify=True, verify_tol=1e-5):
     except Exception:
         pass
+    g_delta.calibration = calibration
     if verify:
         if n_params is None:
             raise ValueError("pass n_params to verify the compiled model, "

{softopt-0.6.4 → softopt-0.7.0}/softopt/numpy_optimizer.py RENAMED Viewed

@@ -38,7 +38,8 @@ 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, slope="model", exact_d2="auto", _test_frozen_constant=1.0):
+                 h_fd=1e-4, seed=None, slope="model", exact_d2="auto", calibrate=False, bias_scale=None,
+                 _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
@@ -59,6 +60,14 @@ class SoftOpt:
         self.v = None
         self.t = 0
         self.rng = np.random.default_rng(seed)
+        self.calibrator = None
+        if calibrate:
+            model = getattr(g_delta, "calibration", None)
+            if model is None:
+                raise ValueError("calibrate=True needs a g_delta from soft_compile (it carries the model the "
+                                 "calibration evaluates on nested soft numbers)")
+            from .calibrate import Calibrator
+            self.calibrator = Calibrator(n_params, model, bias_scale)
         self._ablation_rng = None
         self._test_frozen_constant = _test_frozen_constant
@@ -87,6 +96,8 @@ class SoftOpt:
         """
         theta = np.asarray(theta, dtype=float)
         grad_estimate = np.asarray(grad_estimate, dtype=float)
+        if self.calibrator is not None:
+            return self._calibrated_step(theta, grad_estimate, direction, measured_slope)
         if self.slope == "measured":
             if direction is None or measured_slope is None:
                 raise ValueError('slope="measured" needs direction= and measured_slope= on every '
@@ -160,6 +171,34 @@ class SoftOpt:
         return theta_after_adam + t_star * delta
+    def _calibrated_step(self, theta, grad_estimate, direction, measured_slope):
+        """calibrate=True: the measured pair also calibrates the model (softopt.calibrate); the Adam update is
+        unchanged; the correction is the bounded Newton step of the CALIBRATED model."""
+        if direction is None or measured_slope is None:
+            raise ValueError("calibrate=True needs direction= and measured_slope= on every step "
+                             "(spsa_gradient() returns both)")
+        direction = np.asarray(direction, dtype=float)
+        self.calibrator.update(theta, direction, float(measured_slope))
+        self.t += 1
+        if self.m is None:
+            self.m = np.zeros_like(theta)
+            self.v = np.zeros_like(theta)
+        self.m = self.b1 * self.m + (1 - self.b1) * grad_estimate
+        self.v = self.b2 * self.v + (1 - self.b2) * grad_estimate ** 2
+        mh = self.m / (1 - self.b1 ** self.t)
+        vh = self.v / (1 - self.b2 ** self.t)
+        x = theta - self.lr * mh / (np.sqrt(vh) + self.eps)
+        e = self.rng.choice([-1.0, 1.0], size=theta.shape[0])
+        step = self.calibrator.correction(x, e, self.newton_lo, self.newton_hi, self.eta_fallback)
+        return x + step * e
+    @property
+    def calibration(self):
+        """calibrate=True: current estimates -- beta (bias parameters), kappa (contrast), the discrepancy
+        gradient, and which of the two discrepancy filters is in use."""
+        return None if self.calibrator is None else self.calibrator.state
 def spsa_gradient(measure, theta, c=0.1, rng=None):
     """One SPSA probe of a noisy objective.

{softopt-0.6.4 → softopt-0.7.0/softopt.egg-info}/PKG-INFO RENAMED Viewed

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: softopt
-Version: 0.6.4
-Summary: A standalone optimizer for problems with a known computation graph, built on Klein–Maimon soft-number calculus
+Version: 0.7.0
+Summary: An optimization layer that closes the gap between your model and the real system, built on Klein–Maimon soft-number calculus
 Author: Ido Angel
 License: MIT
 Project-URL: Homepage, https://github.com/mobiuai/softopt
 Project-URL: Repository, https://github.com/mobiuai/softopt
 Project-URL: Issues, https://github.com/mobiuai/softopt/issues
-Keywords: optimizer,optimization,soft-logic,soft-numbers,uncertainty,sensitivity,quantum-computing,vqe
+Keywords: optimizer,optimization,soft-logic,soft-numbers,uncertainty,sensitivity,calibration,digital-twin,sim-to-real,quantum-computing,vqe
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -26,66 +26,126 @@ Dynamic: license-file
 # SoftOpt
-**A standalone optimizer that excels against leading market optimizers like Adam, in problems with a known, differentiable computation graph.**
+**An optimization layer that closes the gap between your model and the real system.**
-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.
+You have a model of your system — a simulator, a circuit, a physical law, a pharmacokinetic model — and you
+measure the real thing, where every measurement costs time or money. SoftOpt sits on top of Adam and, on every
+step, takes an exact Newton correction from your model through Klein–Maimon soft-number calculus (*Foundations
+of Soft Logic*, Klein & Maimon, Springer 2024). With `calibrate=True` the same measurements also correct the
+model's uncertain parameters while the optimization runs, so the correction keeps pointing at the real system's
+optimum instead of the model's.
-## Is SoftOpt the right tool for your problem?
+**When your model is exact** — a quantum circuit, a known physical law — SoftOpt gets closer to the true optimum
+than Adam and COBYLA. On H₂ on IBM's FakeFez noise model it reaches chemical accuracy in 10 of 10 runs against
+COBYLA's 3 of 10 (0.11 vs 5.81 mHa, same 180 readings); on the H₄ molecule (8 qubits, 185 Pauli terms) its gap to
+the ground state is 67% smaller than Adam's, 10/10; in two-qubit quantum control, 84% smaller, 20/20.
-One question decides it, and you can answer it without running anything.
+**When your model is approximately right** — the usual case on real systems — `calibrate=True` closes the gap.
+Across eleven domains — quantum chemistry, beam steering, robotics, chemical engineering, drug dosing, finance,
+building control, batteries, epidemiology, machine learning and an exact-model control — SoftOpt with
+`calibrate=True` reaches the quality Adam reaches after 200 measurements with **2.65× fewer measurements**
+(median; 1.35× to 5.4× by domain).
-**Can you get a residual vector?** That is: can you compute
-`model(theta) - data` and get back an *array*, rather than a single number?
+Free, open source, and runs locally.
-- **Yes** → use `scipy.optimize.least_squares`. It builds the full Jacobian and
-  exploits the least-squares structure, and it will beat SoftOpt on both
-  accuracy and speed. This holds regardless of how large or how noisy the
-  problem is. We measured it: on solar-cell parameter extraction, `least_squares`
-  reached 7.9 mA against SoftOpt's 37.3 mA, and did it 21x faster.
+## When to use it
-- **No** → SoftOpt is built for this case. Each evaluation returns **one number,
-  and it is noisy**: a quantum measurement, a laser-tracker sweep, a backtest, a
-  simulator that returns a score. There is no residual vector for
-  `least_squares` to work with, and finite-difference methods like L-BFGS-B end
-  up differentiating the noise rather than the model.
+**You have a model of your system and you measure the real one?** Use `calibrate=True` and name the model
+parameters you are not sure of, with a generous estimate of how far off they may be.
-SoftOpt's advantage comes from taking the derivative **from your model** instead
-of from your measurements. That only matters when the measurements are the noisy
-part. Every validated domain below is of the second kind; that is not a
-convenience of selection, it is where the mechanism applies.
+```python
+from softopt import SoftOpt, soft_compile, spsa_gradient
+def model(theta, beta):            # your simulator; beta = offsets of its uncertain parameters (0 = nominal)
+    ...
+g = soft_compile(model, n_params=n, n_bias=k)
+opt = SoftOpt(n, g, lr=0.05, calibrate=True, bias_scale=0.2)   # bias_scale: expected size of beta (generous)
+for step in range(num_steps):
+    grad, direction, slope = spsa_gradient(measure, theta, c=0.1)       # 2 measurements of the real system
+    theta = opt.step(theta, grad, direction=direction, measured_slope=slope)
+opt.calibration     # the current estimates: beta, contrast, and the discrepancy the model cannot explain
+```
-## Where it helps
+Everything else stays as it was: the same Adam update, the same measurements, no extra readings. When unsure of
+`bias_scale`, err on the wide side.
-If your problem has a **known computation graph** — a quantum circuit, a physical simulator, a projection or measurement model, anything you can write down exactly, even if the *measurements* of it are noisy — SoftOpt computes an exact directional derivative of that model on every step, plus the curvature along the same direction, and uses them to correct the optimizer's trajectory. Validated, with real hardware-noise-model data, across:
+| your situation | the tool |
+|---|---|
+| a model with uncertain parameters + measurements of the real system | **SoftOpt, `calibrate=True`** |
+| an exact model + noisy measurements | SoftOpt, default settings |
+| you can compute a residual vector `model(theta) - data` | `scipy.optimize.least_squares` |
+| only a learned black-box surrogate (a neural network) + an expensive oracle | Bayesian optimization |
-- **Quantum chemistry (VQE)** — H₂, H₄, BeH₂, HeH⁺, and larger multireference molecules
-- **Quantum control (GRAPE)** — the single cleanest result across every domain tested
-- **Computer vision** — multi-camera bundle adjustment / camera calibration
-- **Finance** — portfolio optimization (Markowitz mean-variance)
-- **Condensed-matter physics** — quasicrystal and spin-chain models (Ising, XY, Heisenberg, SSH, Kitaev)
-- Pharmacokinetics, logistic regression, and more
+## What `calibrate=True` does (new in 0.7.0)
-## Where it does *not* help
+The model is evaluated on nested soft numbers: one soft axis along the probe direction, the other along each
+uncertain parameter. The mixed part of the result is the exact sensitivity of the model's predicted slope to
+that parameter, and every measured slope updates the parameters through it (a Kalman filter). Whatever the
+parameters cannot explain is carried as an explicit discrepancy term on the soft axis. Each correction is
+SoftOpt's bounded Newton step on the calibrated model, sized by how certain the calibrated prediction is, and the
+calibrated model is evaluated at the target before the step is taken.
-Full reinforcement learning (or anything else with a continuously **moving target** — a policy, an adversary, a non-stationary distribution) is outside SoftOpt's validated scope. The mechanism needs a *fixed* objective to compute a meaningful correction against; a moving target breaks that assumption. Use plain Adam/SGD there.
+`calibrate=True` also works on a plain `model(theta)` with no bias parameters; naming the uncertain parameters is
+what makes it reliable across domains.
-**Barren plateaus.** In a deep hardware-efficient circuit at random
-initialisation, the gradient decays exponentially in the qubit count and the
-shot-noise measurement of it is larger than the thing it measures. An exact
-derivative still helps there — it comes from the circuit, so it stays exact
-however flat the landscape gets — but it does not remove the barrier.
+## Results across domains
-We measured this at 4–10 qubits on a transverse-field Ising chain: SoftOpt
-covers **1.4–1.6× as much of the distance to the ground state** as Adam, and
-that ratio held across three seed streams, five shot budgets (512 to 65536),
-five SPSA probe sizes and three different Hamiltonians — 316 wins in 320 runs
-across 16 conditions. The advantage *grows* as the measurement degrades, which
-is the mechanism.
+One small problem per domain, one protocol for all: the model is the domain's standard simulator with its
+uncertain parameters offset at random, the real system also carries an effect the model does not have
+(except in the exact-model control),
+measurements are noisy, 200 measurements, 10 seeds, the same start, Adam at its best of five learning rates and
+SoftOpt at Adam's. `benchmarks/softbench/`.
-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/`.
+**Measurements needed to reach the quality Adam reaches with 200**
+| domain | SoftOpt `calibrate=True` | runs that got there |
+|---|---|---|
+| Quantum chemistry (H₂) | **5.4× fewer** | 10/10 |
+| Epidemic control (vaccination) | **4.3× fewer** | 10/10 |
+| Drug dosing (pharmacokinetics) | **3.3× fewer** | 10/10 |
+| Portfolio optimization | **3.0× fewer** | 10/10 |
+| Exact-model control | **3.0× fewer** | 10/10 |
+| RF beam steering (phased array) | **2.7× fewer** | 9/10 |
+| Batch chemical reactor | **2.2× fewer** | 10/10 |
+| Robot arm controller tuning | **1.9× fewer** | 8/10 |
+| Classifier under data shift | **1.9× fewer** | 8/10 |
+| Building thermal control | **1.8× fewer** | 6/10 |
+| Battery fast charging | **1.35× fewer** | 7/10 |
+**Remaining gap to the true optimum after 200 measurements** (fraction of the starting gap; median)
+| domain | Adam | COBYLA | SoftOpt default | **SoftOpt `calibrate=True`** |
+|---|---|---|---|---|
+| Quantum chemistry (H₂) | 0.0010 | 0.012 | 0.0040 | **0.0001** |
+| RF beam steering | 0.0043 | 0.053 | 0.079 | **0.0026** |
+| Robot arm tuning | 0.0125 | 0.026 | 0.024 | **0.0027** |
+| Batch reactor | 0.0065 | 0.14 | 0.029 | **0.0023** |
+| Drug dosing | 0.0198 | 0.056 | 0.067 | **0.0016** |
+| Portfolio | 0.052 | 0.10 | 0.68 | **0.030** |
+| Battery charging | 0.032 | 0.17 | 1.38 | **0.023** |
+| Building thermal control | 0.0089 | 0.069 | 0.046 | 0.0148 |
+| Epidemic control | 0.0081 | 0.024 | ~0 | 0.0035 |
+| Classifier under data shift | 0.22 | 0.49 | 0.105 | 0.23 |
+| Exact-model control | 0.0026 | 0.0048 | 0.00009 | 0.00016 |
+**Quantum chemistry with gate errors, on IBM's FakeFez noise model**
+H₂ on a device whose gates carry coherent errors (over-rotations, phase offsets, residual coupling), so the
+ideal circuit no longer points at the right parameters. 180 device readings, 20 new seeds:
+| | energy above the ground state (mHa, median) |
+|---|---|
+| Adam | 4.7 |
+| COBYLA | 2.6 |
+| SoftOpt, default | 13.0 |
+| **SoftOpt, `calibrate=True`** | **0.42** (better than Adam 20/20, than COBYLA 16/20) |
+With gate errors twice as large: 0.48 mHa, against Adam 4.8 and COBYLA 2.1. On a two-qubit gate calibration
+task (18 angles, FakeFez, hidden coherent errors) the calibrated layer reaches 1.4e-4 infidelity against
+Adam's 3.7e-4 (18/20), and in sensorless adaptive optics 0.0023 against 0.0041 (17/20).
 ## Installation
@@ -298,10 +358,14 @@ The full soft-number algebra is available from the package (`from softopt import
 `SoftNumber` wraps these with operator syntax (`x + y`, `x * y`, `x ** 3`, `x.sqrt()`) and is verified, axiom by axiom, against the book's own proofs that bridge numbers form an abelian group under addition and a ring under both operations (`tests/test_soft_number.py`).
-## What SoftOpt is *not*
+## Choosing between the modes
+- `calibrate=True` — your model has parameters you are not sure of. The recommended starting point whenever you
+  measure a real system.
+- default (`slope="model"`) — your model is exact; the measurements are only noisy.
+- `slope="measured"` — the model is approximate and you do not want to name its uncertain parameters.
-- Not a claim to beat specialized full-Jacobian second-order solvers (Levenberg–Marquardt, L-BFGS) where those are already practical — SoftOpt's validated niche is genuine improvement over first-order optimizers (Adam, SGD) already in use, particularly where switching to a full second-order method isn't practical (embedded in a larger pipeline, high dimensionality, or measurement noise).
-- Not a general-purpose black-box optimizer — it requires a known computation graph, as described above.
+`calibrate=True` is available in `SoftOpt` (numpy). `SoftOptTorch` runs the default correction.
 ## License

{softopt-0.6.4 → softopt-0.7.0}/softopt.egg-info/SOURCES.txt RENAMED Viewed

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 softopt/__init__.py
+softopt/calibrate.py
 softopt/compile.py
 softopt/numpy_optimizer.py
 softopt/soft_number.py
@@ -12,6 +13,7 @@ softopt.egg-info/dependency_links.txt
 softopt.egg-info/requires.txt
 softopt.egg-info/top_level.txt
 tests/test_basic.py
+tests/test_calibrate.py
 tests/test_causal.py
 tests/test_compile.py
 tests/test_exact_d2.py

softopt-0.7.0/tests/test_calibrate.py ADDED Viewed

@@ -0,0 +1,86 @@
+"""calibrate=True: the soft Jacobian is exact, the default path is unchanged, and calibration helps on a
+biased model."""
+import importlib.util
+import os
+import numpy as np
+import pytest
+from softopt import SoftOpt, soft_compile
+N = 4
+A = np.array([1.0, 2.0, 0.5, 1.5]); CC = np.array([0.3, -0.2, 0.5, 0.1])
+def model(th, be):
+    return sum(A[i] * (th[i] - CC[i] - be[i]) ** 2 + 0.3 * np.cos(th[i] + be[i]) for i in range(N))
+def test_soft_jacobian_matches_finite_differences():
+    cm = soft_compile(model, n_params=N, n_bias=N).calibration
+    rng = np.random.default_rng(0)
+    x, d, b = rng.normal(size=N), rng.choice([-1.0, 1.0], N), rng.normal(0, 0.2, N)
+    D1, jac = cm.d1_and_jac(x, d, b); h = 1e-6
+    for j in range(N):
+        e = np.zeros(N); e[j] = h
+        fd = (cm.d1_d2(x, d, b + e)[0] - cm.d1_d2(x, d, b - e)[0]) / (2 * h)
+        assert abs(jac[j] - fd) < 1e-6 * max(1, abs(fd))
+    fd1 = (cm.value(x + h * d, b) - cm.value(x - h * d, b)) / (2 * h)
+    assert abs(D1 - fd1) < 1e-6 * max(1, abs(fd1))
+    D1b, D2 = cm.d1_d2(x, d, b)
+    fd2 = (cm.d1_d2(x + h * d, d, b)[0] - cm.d1_d2(x - h * d, d, b)[0]) / (2 * h)
+    assert abs(D2 - fd2) < 1e-5 * max(1, abs(fd2))
+def test_nominal_model_is_beta_zero():
+    g = soft_compile(model, n_params=N, n_bias=N)
+    x, d = np.full(N, 0.2), np.ones(N)
+    assert abs(g(x, d) - g.calibration.d1_d2(x, d, np.zeros(N))[0]) < 1e-12
+def test_default_path_unchanged():
+    """calibrate=False must be bit-identical to the same SoftOpt without the calibrate code."""
+    g = soft_compile(lambda th: model(th, [0.0] * N), n_params=N)
+    a = SoftOpt(N, g, lr=0.05, seed=3); b = SoftOpt(N, g, lr=0.05, seed=3, calibrate=False)
+    x1 = x2 = np.zeros(N); rng = np.random.default_rng(4)
+    for _ in range(30):
+        gr = rng.normal(size=N)
+        x1, x2 = a.step(x1, gr), b.step(x2, gr)
+    assert np.array_equal(x1, x2)
+def _run(s, mode, budget=200):
+    rng_b = np.random.default_rng(500 + s); btrue = rng_b.normal(0, 0.3, N); noise = np.random.default_rng(900 + s)
+    meas = lambda x: model(x, btrue) + 0.05 * noise.normal()                               # noqa: E731
+    g = soft_compile(model, n_params=N, n_bias=N)
+    kw = dict(calibrate=True, bias_scale=0.3) if mode == 'cal' else dict(slope='measured')
+    opt = SoftOpt(N, g, lr=0.05, seed=s * 7 + 2, **kw)
+    x = np.zeros(N); rng = np.random.default_rng(s * 7 + 1)
+    for _ in range(budget // 2):
+        d = rng.choice([-1.0, 1.0], N); sl = (meas(x + 0.1 * d) - meas(x - 0.1 * d)) / 0.2
+        x = opt.step(x, sl * d, direction=d, measured_slope=sl)
+    from scipy.optimize import minimize
+    return model(x, btrue) - minimize(lambda z: model(z, btrue), CC + btrue).fun
+def test_calibration_helps_on_a_biased_model():
+    pytest.importorskip('scipy')
+    cal = np.array([_run(s, 'cal') for s in range(8)]); mea = np.array([_run(s, 'measured') for s in range(8)])
+    assert np.median(cal) < np.median(mea) and (cal < mea).sum() >= 6
+def test_beta_free_calibration_runs():
+    g = soft_compile(lambda th: model(th, [0.0] * N), n_params=N)
+    opt = SoftOpt(N, g, lr=0.05, seed=0, calibrate=True)
+    x = np.zeros(N); rng = np.random.default_rng(1)
+    for _ in range(20):
+        d = rng.choice([-1.0, 1.0], N); sl = float(rng.normal())
+        x = opt.step(x, sl * d, direction=d, measured_slope=sl)
+    assert np.all(np.isfinite(x)) and opt.calibration['beta'].size == 0
+def test_calibrate_requires_direction_and_scale():
+    g = soft_compile(model, n_params=N, n_bias=N)
+    with pytest.raises(ValueError):
+        SoftOpt(N, g, calibrate=True)                         # bias parameters need bias_scale
+    opt = SoftOpt(N, g, calibrate=True, bias_scale=0.1)
+    with pytest.raises(ValueError):
+        opt.step(np.zeros(N), np.zeros(N))