SoftOpt

An optimization layer that closes the gap between your model and the real system.

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.

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.

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).

Free, open source, and runs locally.

When to use it

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.

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

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.

What calibrate=True does (new in 0.7.0)

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.

calibrate=True also works on a plain model(theta) with no bias parameters; naming the uncertain parameters is what makes it reliable across domains.

Results across domains

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/.

Measurements needed to reach the quality Adam reaches with 200

Remaining gap to the true optimum after 200 measurements (fraction of the starting gap; median)

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:

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

pip install softopt            # numpy only
pip install "softopt[torch]"   # adds SoftOptTorch

Quick start

import numpy as np
from softopt import SoftOpt, soft_compile

# Write your model once, in plain Python. No special arithmetic.
def my_model(theta):
    x, y = theta
    return (x - 2.0)**2 + np.exp(y) * x

# soft_compile turns it into the exact directional-derivative function
# SoftOpt needs, and verifies the result against your own model.
g_delta = soft_compile(my_model, n_params=2)

opt = SoftOpt(2, g_delta, lr=0.02)

for step in range(num_steps):
    grad_estimate = my_gradient_estimate(theta)   # e.g. from SPSA on real hardware
    theta = opt.step(theta, grad_estimate)

Your model needs to be built from arithmetic and the elementary functions the soft algebra defines: + - * / ** (including negative and fractional exponents, and 2.0 ** x), abs, sqrt, exp, log, log10, sin, cos, tanh, comparisons, and numpy's versions of those. Loops and if/else branching on parameter values work too — the compiled derivative is then valid on the branch your parameters are actually in.

The one thing to avoid is converting a traced value back to a plain number mid-model — float(x), or np.array(params) on the parameter list, both silently discard the derivative. soft_compile's verification catches this and says so.

Parameter scale. SoftOpt's correction moves each parameter by at most 0.5 per step, a natural size for angles and other parameters of order 1. If your parameters live on a very different scale (pixel offsets of 0.03, prices in the thousands), rescale them to roughly ±1, or set the bound to match: SoftOpt(n, g_delta, lr=..., newton_lo=-b, newton_hi=b).

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.

Exact curvature (new in 0.6.4)

The Newton correction needs two numbers along the probe direction: the slope D1 and the curvature D2. Since 0.6.4 both come from one pass of your model on nested soft numbers, with no step size. Each parameter enters as θ + δ·ε₁ + δ·ε₂, where each soft axis obeys the book's ε² = 0; the mixed ε₁ε₂ part of the result is D2 exactly (Lemma 6.1 applied twice). soft_compile sets this up for you, and SoftOpt uses it automatically.

A hand-written g_delta can opt in the same way by carrying an attribute g_delta.d1_d2 = lambda theta, delta: (D1, D2). Without it, D2 is a central finite difference of your exact g_delta (h_fd, the 0.6.3 behaviour, unchanged). exact_d2=False forces the finite difference.

On the H4 benchmark (FakeFez, 10 seeds) the exact-curvature engine (benchmarks/vqe/soft_su2_exact.py, h4_exact_d2.py) gives the same result as the published one: 400 vs 409 mHa at step 100 (p=0.56), both 10/10 against Adam with 67% of the gap closed. examples/soft_tensor_demo.py shows that the same nested construction on tensors reproduces SoftOptTorch's nested torch.func.jvp to rounding (4e-16).

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:

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:

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.

pip install "softopt[torch]"

import torch
from softopt import SoftOptTorch

class HeatModel(torch.nn.Module):          # any known, differentiable model
    def __init__(self):
        super().__init__()
        self.k = torch.nn.Parameter(torch.tensor([0.5]))
        self.T0 = torch.nn.Parameter(torch.tensor([20.0]))
    def forward(self, t):
        return self.T0 * torch.exp(-self.k * t)

def loss_fn(model, batch):                 # a fixed objective, re-evaluated exactly
    t, measured = batch
    return ((model(t) - measured) ** 2).mean()

model = HeatModel().to("cuda")             # or "cpu" / "mps"
opt = SoftOptTorch(model.parameters(), model, loss_fn, lr=1e-2)

for step in range(num_steps):
    loss = opt.step((t, measured))         # forward, backward, Adam, correction

loss_fn(model, batch) must be the same objective on every call, as in every domain above: a fixed dataset, a simulator, a physical model. Each parameter moves by at most newton_bound in the correction (default: the learning rate). BatchNorm and MaxPool layers are handled; the correction pass never updates BatchNorm running statistics.

Validated results

All results below use IBM's FakeFez noise model via Qiskit + Aer, or realistic finite-sample/measurement noise for the non-quantum domains, with torch.optim.Adam as the baseline. Improvement is the reduction in gap to the known optimum (or, for Portfolio, the reduction in loss).

Quantum chemistry (VQE)

Quantum chemistry on a real molecule, and against COBYLA

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 machine learning

benchmarks/qml/vqc.py --dataset iris|cancer

Quantum control

Condensed-matter & spin models

Computer vision

Finance

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. The ablation 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 — everything else held identical.

On GRAPE, 1000 seeds per arm:

A correction fed a non-genuine value does not merely help less — it lands about 1600× worse than applying no correction at all. Run it yourself:

cd benchmarks/grape && python3 causal_ablation.py --seeds 1000
python3 tests/test_causal.py          # the same test, smaller and faster

Two interfaces to the same algebra

SoftNumber gives you operator syntax (x * y, x.exp()) and is what soft_compile traces your model with. The tuple functions (smul, sadd, ssin, ...) are the same operations applied to whole numpy arrays at once, which is what the benchmark engines use — a quantum circuit propagates 2ⁿ amplitudes per gate, and one Python object per amplitude would not be workable.

They are the same algebra and produce identical numbers; tests/test_causal.py asserts that agreement to 1e-15 across every operation, and also asserts that soft-number operations actually fire during an optimizer step.

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):

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).

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.

calibrate=True is available in SoftOpt (numpy). SoftOptTorch runs the default correction.

License

MIT. See LICENSE.