Skip to content

optora.core.solver_base

Shared contracts for numerical solvers and the problems they solve.

Solver

Bases: ABC, Generic[ProblemT, ResultT]

Numerical method that transforms an optimization problem into a result.

Subclasses implement a specific iterative algorithm (for example gradient descent on a differentiable objective, or primal-dual ascent-descent on a DRO minimax problem). Solver is generic in the problem and result types so each subclass can pair itself with whatever problem description its algorithm needs (an objective and an initial point, a primal-dual pair of objectives, and so on) instead of forcing every algorithm through one fixed set of arguments.

Problem and result types are keyed to the mathematical problem class, not to the algorithm: every solver of unconstrained differentiable minimization consumes MinimizationProblem and returns MinimizationResult, so callers such as optora.dro ambiguity sets can depend on Solver[MinimizationProblem, MinimizationResult] and accept any solver of that problem class.

solve(problem) abstractmethod

Run the solver on problem and return its outcome.

Parameters:

Name Type Description Default
problem ProblemT

Description of the optimization problem to solve.

 required

Returns:

Type Description
ResultT

The result of running this solver on problem.

MinimizationProblem dataclass

Unconstrained minimization of a differentiable scalar objective.

Attributes:

Name Type Description
objective Callable[[Tensor], Tensor]

Differentiable scalar-valued function of a single tensor argument. It must depend on that argument through autograd; solvers reject an objective whose value is disconnected from the point rather than treating it as stationary.
initial_point Tensor

Starting point for the iteration. Passing a previous solve's MinimizationResult.point here warm-starts the solver from that solution instead of from scratch, which is useful for the repeated inner-loop solves a DRO ambiguity set or minimax solver runs as its outer state changes slightly between calls.

MinimizationResult dataclass

Bases: ConvergenceDiagnostics

Outcome of solving a MinimizationProblem.

Attributes:

Name Type Description
point Tensor

Final iterate.
value Tensor

Objective value at point.
status ConvergenceStatus

Convergence diagnostics of the solve, exposed on the host as converged and num_iterations by ConvergenceDiagnostics and read back from the device only when one of those is accessed.

converged property

Whether the convergence criterion was met before the iteration budget.

num_iterations property

Number of iterations actually performed.

require_gradient(gradient, variable)

Return a gradient produced with allow_unused=True, rejecting None.

torch.autograd.grad(..., allow_unused=True) returns None when the objective's value is disconnected from the differentiated variable. Substituting a zero gradient there would make a solver report immediate convergence at a point it never optimized, so Optora treats a missing gradient as a violated problem contract instead of a stationary point.

Parameters:

Name Type Description Default
gradient Tensor | None

Gradient returned by torch.autograd.grad for variable.

 required
variable str

Human-readable name of the differentiated variable, used in the error message.

 required

Returns:

Type Description
Tensor

gradient, guaranteed not to be None.

Raises:

Type Description
ValueError

If gradient is None.