Optimization¶
QuantLib-style methods for fitting Heston and Hull-White models. Pass any of
these methods to HestonModel.calibrate* or HullWhite.calibrate*, with an
EndCriteria to set the stopping thresholds.
| Method | Choose it when |
|---|---|
LevenbergMarquardt |
Fitting least-squares errors with the usual calibration default. |
Simplex(lambda_) |
You want a derivative-free search and can choose a positive starting scale. |
ConjugateGradient |
You want a gradient-based search using the core Armijo line search. |
SteepestDescent |
You want a basic gradient-based search using the same line search. |
ParticleSwarm |
You have a wholly feasible finite box and want synchronous seeded global-best swarm search. |
DifferentialEvolution |
You have a finite search box entirely inside the model domain and want a seeded population search. |
These methods belong to itofin.optimization. The separate itofin.optimize
API minimizes scalar objectives directly. See Global optimization
for the shared solver contract, calibration bounds and diagnostic results.
Every HestonModel.calibrate* and HullWhite.calibrate* method also accepts
keyword-only constraint=, weights=, and fix_parameters= arguments. Use
NoConstraint(), PositiveConstraint(), BoundaryConstraint(low, high), or
CompositeConstraint(a, b) for an additional constraint intersected with the
model's own parameter limits. A composite copies its children.
weights has one entry per helper. fix_parameters has one Boolean per model
parameter: Heston uses (theta, kappa, sigma, rho, v0) and Hull-White uses
(a, sigma). Omit either argument for the core default. Hull-White's existing
fix_reversion=True fixes a; it cannot be combined with a nonempty
fix_parameters mask.
Runtime source shim for the native itofin.optimization submodule.
The real itofin.optimization 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.optimization import ... from optimization/__init__.pyi without a
reportMissingModuleSource warning.
Auto-generated by scripts/gen_submodule_shims.py from optimization/__init__.pyi; do not edit or delete by hand.
An inclusive lower and upper bound for every parameter.
Build a bound with finite, ordered endpoints.
CompositeConstraint(a: NoConstraint | PositiveConstraint | BoundaryConstraint | CompositeConstraint, b: NoConstraint | PositiveConstraint | BoundaryConstraint | CompositeConstraint)
The intersection of two reusable constraints.
Copy both children, so they may be released independently.
The conjugate-gradient method for calibration.
Build a conjugate-gradient method with the core Armijo line search.
DifferentialEvolution(bounds: Sequence[tuple[float, float]], *, seed: int = 0, population_size: Optional[int] = None, initial_population: Optional[Sequence[Sequence[float]]] = None, xatol: Optional[float] = None, fatol: Optional[float] = None, mutation: float = 0.8, recombination: float = 0.9, maxiter: Optional[int] = None, maxfev: Optional[int] = None)
Bounded global calibration in projected free-parameter order. The complete search box must satisfy the model's constraint.
Construct a bounded, deterministic DE/rand/1/bin calibration method. Bounds and population coordinates use the free parameter order. Invalid candidates abort before pricing rather than receiving a penalty.
last_result() -> Optional[OptimizeResult]
Copy the exact last global result, or None before a completed run. Exhausted runs are retained without being labelled successful.
EndCriteria(max_iterations: int, max_stationary_state_iterations: Optional[int], root_epsilon: float, function_epsilon: float, gradient_norm_epsilon: Optional[float])
The optimizer stopping rule.
Carries the iteration cap and the stationarity thresholds an optimization run is tested against.
Initialize the criteria.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
max_iterations
|
int
|
The iteration count at which the run stops. |
required |
max_stationary_state_iterations
|
int | None
|
How many consecutive stationary iterations are tolerated before the run is called converged; None defaults to min(max_iterations / 2, 100). |
required |
root_epsilon
|
float
|
The variation of the independent variable below which an iteration counts as stationary. |
required |
function_epsilon
|
float
|
The variation of the function value below which an iteration counts as stationary, and, for a cost function known to be positive, the value below which the run has converged. |
required |
gradient_norm_epsilon
|
float | None
|
The gradient norm below which the run has converged; None defaults to function_epsilon. |
required |
Raises:
| Type | Description |
|---|---|
ItofinError
|
Unless 1 < max_stationary_state_iterations < max_iterations, or if any epsilon is negative or non-finite. |
Firefly(bounds: Sequence[tuple[float, float]], *, seed: int = 0, population_size: Optional[int] = None, initial_population: Optional[Sequence[Sequence[float]]] = None, xatol: Optional[float] = None, fatol: Optional[float] = None, alpha: float = 0.25, beta0: float = 1.0, gamma: float = 1.0, alpha_decay: float = 0.97, maxiter: Optional[int] = None, maxfev: Optional[int] = None)
Bounded global calibration in projected free-parameter order. The complete search box must satisfy the model's constraint.
Construct a bounded, deterministic synchronous normalized firefly calibration method. Bounds and population coordinates use the free parameter order. Invalid candidates abort before pricing rather than receiving a penalty.
last_result() -> Optional[OptimizeResult]
Copy the exact last global result, or None before a completed run. Exhausted runs are retained without being labelled successful.
HybridSimulatedAnnealing(bounds: Sequence[tuple[float, float]], *, seed: int = 0, initial_temperature: float = 1.0, cooling_rate: float = 0.95, step_size: float = 0.25, local_search_interval: int = 10, local_search_steps: int = 4, reanneal_interval: int = 100, xatol: Optional[float] = None, fatol: Optional[float] = None, maxiter: Optional[int] = None, maxfev: Optional[int] = None)
Bounded hybrid annealing calibration in projected free-parameter order. The complete search box must satisfy the model's constraint.
Construct a seeded single-chain annealing method with coordinate local searches. Bounds use the free parameter order; no population is constructed. Invalid candidates abort before pricing rather than receiving a penalty.
last_result() -> Optional[OptimizeResult]
Copy the exact last result, or None before a completed run. Exhausted runs retain their actual counters without being labelled successful.
LevenbergMarquardt(epsfcn: float = 1e-08, xtol: float = 1e-08, gtol: float = 1e-08, use_cost_functions_jacobian: bool = False)
The least-squares optimizer used to fit model parameters.
Wraps the MINPACK lmdif routine. The Jacobian comes from a built-in forward-difference scheme by default; the cost function's own jacobian method is used instead when use_cost_functions_jacobian is set.
Initialize the optimizer; the defaults are QuantLib's.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
epsfcn
|
float
|
The finite-difference step seed used when the Jacobian is computed by differences. |
1e-08
|
xtol
|
float
|
The tolerance on the independent variable. |
1e-08
|
gtol
|
float
|
The tolerance on the gradient. |
1e-08
|
use_cost_functions_jacobian
|
bool
|
Use the cost function's own jacobian method (a central difference, order 2 but costlier) instead of the built-in forward-difference scheme. |
False
|
A constraint that accepts every parameter vector.
Build an unconstrained parameter region.
ParticleSwarm(bounds: Sequence[tuple[float, float]], *, seed: int = 0, population_size: Optional[int] = None, initial_population: Optional[Sequence[Sequence[float]]] = None, xatol: Optional[float] = None, fatol: Optional[float] = None, inertia: float = 0.7, cognitive: float = 1.4, social: float = 1.4, velocity_clamp: float = 0.2, maxiter: Optional[int] = None, maxfev: Optional[int] = None)
Bounded global calibration in projected free-parameter order. The complete search box must satisfy the model's constraint.
Construct a bounded, deterministic global-best particle swarm calibration method. Bounds and population coordinates use the free parameter order. Invalid candidates abort before pricing rather than receiving a penalty.
last_result() -> Optional[OptimizeResult]
Copy the exact last global result, or None before a completed run. Exhausted runs are retained without being labelled successful.
A constraint requiring every parameter to be strictly positive.
Require each parameter to be strictly positive.
The downhill simplex method for derivative-free calibration.
Build a simplex with a finite, positive characteristic length.
Raises:
| Type | Description |
|---|---|
ValueError
|
If lambda_ is zero, negative or non-finite. |
The steepest-descent method for calibration.
Build a steepest-descent method with the core Armijo line search.