SoftOpt

A standalone optimizer that excels against leading market optimizers like Adam, in problems with a known, differentiable computation graph.

SoftOpt is free, fully local, and requires no server, license key, or network access — the same way torch.optim.Adam requires none. It is not a wrapper around Adam or any other optimizer: it is a complete, drop-in optimizer with its own Adam-equivalent base update, plus an exact Newton-style correction built on Klein–Maimon soft-number calculus (Foundations of Soft Logic, Klein & Maimon, Springer 2024).

Where it helps

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 and curvature of that model on every step, and uses them to correct the optimizer's trajectory. Validated, with real hardware-noise-model data, across:

• 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

Where it does not help

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.

Installation

pip install softopt            # numpy version only
pip install "softopt[torch]"   # + the PyTorch optimizer (quotes needed on zsh, macOS's default shell)

Quick start

NumPy

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.

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.

PyTorch

from softopt import SoftOptTorch

opt = SoftOptTorch(model.parameters(), model, loss_fn, lr=1e-3)

for batch in data:
    loss = opt.step(batch)   # one call: backward + Adam update + soft-number correction

loss_fn(model, batch) must be an exactly re-evaluatable, differentiable function of the model's own parameters — a full-batch loss, a physics simulator, a known projection model. SoftOpt uses PyTorch's own forward-mode autodiff (torch.func.jvp) to get the same exact directional derivative and curvature the NumPy version computes by hand.

Two correction modes

SoftOpt ships with two ways of turning the computed derivative/curvature into a parameter update:

• newton (default) — a bounded Newton step t* = clip(-D1/D2, bounds). Best when the curvature (D2) is consistently one-signed along random directions — true for essentially every gradient-based physics/circuit optimization problem we tested (VQE, GRAPE, camera calibration, portfolio, ...).
• mobius — a bounded, sign-safe step derived from the book's own Möbius map (Ch. 5.3), for problems whose curvature is not reliably one-signed. Pass mode="mobius" to SoftOpt/SoftOptTorch if newton underperforms plain Adam on your problem — that pattern is itself informative about your landscape's curvature.

How do I know which one to use? Right now, empirically: run a short comparison against plain Adam with mode="newton" first; if it clearly loses, try mode="mobius". There is also an experimental mode="auto" that samples curvature sign near your starting point and picks for you — we tested it honestly and it is not yet reliable (on GRAPE, a domain we know needs newton with high confidence, it only picked correctly 40% of the time across random starting points). It's included so you can inspect opt.detected_mode and help us characterize when it works, but don't depend on it yet.

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

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

What SoftOpt is not

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

License

MIT. See LICENSE.