Optimize¶

Particle swarm is not included in v0.37.0 artifacts; build from this source checkout until the next coordinated release.

SciPy-style minimize over the finance-independent itofin-optimize crate. Python, Go, C and Rust expose Nelder-Mead, BFGS, L-BFGS-B, SLSQP, Differential Evolution and Particle Swarm.

This is distinct from Optimization, the QuantLib calibration port. The objective runs outside any bootstrap callback, so it may set a SimpleQuote and reprice an instrument. An exception raised by fun, jac, a constraint callback, or callback is re-raised as the same object; StopIteration from callback stops the run with Status.Cancelled.

from itofin.optimize import minimize

result = minimize(lambda x: (x[0] - 3.0) ** 2, [0.0], options={"xatol": 1e-8})
print(result.x, result.status, result.message)

Method	Supported options	Gradient	Bounds	General constraints
Nelder-Mead	`maxiter`, `maxfev`, `xatol`, `fatol`, `adaptive`	None	Rejected	Rejected
BFGS	`maxiter`, `gtol`, `eps`	`jac(x)` or finite differences	Rejected	Rejected
L-BFGS-B	`maxiter`, `maxfev`, `maxcor`, `ftol`, `gtol`, `eps`	`jac(x)` or bounded finite differences	`(lower, upper)` pairs; `None` opens a side	Rejected
SLSQP	`maxiter`, `maxfev`, `ftol`	`jac(x)` or finite differences	`(lower, upper)` pairs; `None` opens a side	`constraints` dictionaries
Particle-Swarm	`seed`, `population_size`, `initial_population`, `xatol`, `fatol`, `inertia`, `cognitive`, `social`, `velocity_clamp`, `maxiter`, `maxfev`	Rejected	Finite pairs required	Rejected
Differential-Evolution	`seed`, `population_size`, `initial_population`, `xatol`, `fatol`, `mutation`, `recombination`, `maxiter`, `maxfev`	Rejected	Finite pairs required	Rejected

eps is an absolute finite-difference step; it has no effect when jac is provided. An unknown method, invalid numeric input, or unsupported Nelder-Mead option raises ItofinError. Unsupported BFGS options, jac with Nelder-Mead, and bounds on Nelder-Mead or BFGS raise ValueError. L-BFGS-B and SLSQP reject an incorrect number of bound pairs before evaluating the objective. Only SLSQP accepts constraints; unsupported options and malformed constraint descriptors are rejected before the objective runs. Callback output dimensions are checked on every evaluation.

result = minimize(
    lambda x: (x[0] - 3.0) ** 2,
    [0.0],
    method="BFGS",
    jac=lambda x: [2.0 * (x[0] - 3.0)],
    options={"gtol": 1e-8},
)

result = minimize(
    lambda x: (x[0] - 3.0) ** 2 + (x[1] + 2.0) ** 2,
    [0.0, 0.0],
    method="L-BFGS-B",
    bounds=[(0.0, 1.0), (None, None)],
)

SLSQP interprets equality constraints as fun(x) == 0 and inequality constraints as fun(x) >= 0. Each fun returns a scalar or one-dimensional vector. Its optional jac returns a gradient for a scalar constraint or one gradient row per vector component. A missing Jacobian uses finite differences. The dimension is fixed at the initial point; Status.Infeasible (integer 8) means the constraints could not be satisfied.

result = minimize(
    lambda x: (x[0] - 3.0) ** 2 + (x[1] + 1.0) ** 2,
    [0.2, 0.3],
    method="SLSQP",
    bounds=[(0.0, 1.0), (0.0, 1.0)],
    constraints=[{
        "type": "ineq",
        "fun": lambda x: x[0] + x[1] - 2.0,
        "jac": lambda x: [1.0, 1.0],
    }],
    options={"ftol": 1e-10},
)

The integer values of Status match the C ItofinOptimizeStatus and the Go OptimizeStatus.

optimize ¶

Runtime source shim for the native itofin.optimize submodule.

The real itofin.optimize is a compiled submodule registered into sys.modules by the extension; it wins at import time, so nothing here runs. This file exists only so static type checkers resolve from itofin.optimize import ... from optimize/__init__.pyi without a reportMissingModuleSource warning.

Auto-generated by scripts/gen_submodule_shims.py from optimize/__init__.pyi; do not edit or delete by hand.

OptimizeResult ¶

The outcome of a minimize run: the best point found and why it stopped.

x `property` ¶

x: NDArray[float64]

The best point found, as a new float64 array.

Status ¶

Why a minimize run stopped.

The integer values are fixed and append-only, matching the C ItofinOptimizeStatus and the Go OptimizeStatus.

minimize ¶

minimize(fun: Callable[[NDArray[float64]], float], x0: Sequence[float], method: str = 'Nelder-Mead', options: Optional[dict] = None, callback: Optional[Callable[[NDArray[float64]], object]] = None, jac: Optional[Callable[[NDArray[float64]], Sequence[float]]] = None, bounds: Optional[Sequence[tuple[Optional[float], Optional[float]]]] = None, constraints: Optional[Sequence[dict[str, object]]] = None) -> OptimizeResult

Minimize a scalar function of one or more variables.

Parameters:

Name	Type	Description	Default
`fun`	`Callable`	Called as fun(x) with a float64 array; returns a float.	required
`x0`	`Sequence[float]`	The starting point.	required
`method`	`str`	"Nelder-Mead", "BFGS", "L-BFGS-B", "SLSQP", or "Differential-Evolution", "Particle-Swarm", "Hybrid-Simulated-Annealing" or "Firefly" (any case).	`'Nelder-Mead'`
`options`	`dict \| None`	Nelder-Mead accepts maxiter, maxfev, xatol, fatol and adaptive. BFGS accepts maxiter, gtol and eps. L-BFGS-B accepts maxiter, maxfev, maxcor, ftol, gtol and eps. SLSQP accepts maxiter, maxfev and ftol. Differential-Evolution accepts maxiter, maxfev, seed, population_size, initial_population, xatol, fatol, mutation and recombination. Seed zero is deterministic; population rows are used unchanged, without inserting x0. Global convergence tolerances are normalized coordinate spread and absolute fun spread. Particle-Swarm accepts the same shared controls plus inertia, cognitive, social and velocity_clamp, instead of mutation and recombination. Its convergence additionally requires small normalized velocity. Hybrid-Simulated-Annealing accepts maxiter, maxfev, seed, xatol, fatol, initial_temperature, cooling_rate, step_size, local_search_interval, local_search_steps and reanneal_interval. It uses a reflected uniform proposal, Metropolis acceptance and bounded coordinate local searches. It does not accept population controls. Firefly accepts the shared population controls plus alpha, beta0, gamma and alpha_decay. Distances and random displacements are normalized by the finite box; attraction uses a frozen generation.	`None`
`callback`	`Callable \| None`	Called as callback(xk) after every iteration. Raising StopIteration stops the run with Status.Cancelled.	`None`
`jac`	`Callable \| None`	Analytic objective gradient for BFGS, L-BFGS-B or SLSQP, called as jac(x).	`None`
`bounds`	`Optional[Sequence[tuple[Optional[float], Optional[float]]]]`	L-BFGS-B or SLSQP pairs of (lower, upper), with None for an open side. Global methods require finite bounds and x0 inside them; equal lower and upper bounds fix a coordinate. Other methods reject bounds.	`None`
`constraints`	`Sequence[dict] \| None`	SLSQP constraints with type "eq" (fun(x) == 0) or "ineq" (fun(x) >= 0), fun(x) returning a scalar or vector, and optional jac(x) returning a gradient or 2-D rows.	`None`

Returns:

Name	Type	Description
`OptimizeResult`	`OptimizeResult`	The best point found and why the run stopped.

Raises:

Type	Description
`ItofinError`	On an unknown method or option, or a rejected input.
`Exception`	Whatever fun, jac, a constraint or callback raised, re-raised unchanged.