Options API¶
European Options¶
european
¶
European option pricing: BS closed-form + QAE interface.
Asian Options¶
asian
¶
Asian option pricing (geometric + arithmetic) via QAE.
Constructs QAE estimation problems for Asian options where the payoff depends on the average price over a monitoring window.
For geometric Asian options, closed-form BS-like solutions exist. For arithmetic, QAE provides an alternative to Monte Carlo.
References¶
Stamatopoulos et al., Quantum 4:291 (2020), arXiv:1905.02666.
AsianOptionSpec
dataclass
¶
Asian option specification.
Parameters¶
s0 : float Spot price. k : float Strike price. r : float Risk-free rate. sigma : float Volatility. T : float Time to expiry. n_monitoring : int Number of monitoring dates (equally spaced). is_call : bool True for call, False for put. average_type : str "arithmetic" or "geometric". n_qubits_per_step : int Qubits per monitoring date for QAE discretization.
geometric_asian_closed_form(s0, k, r, sigma, T, n_monitoring, is_call=True)
¶
Closed-form price for geometric Asian option (Kemna-Vorst).
The geometric average follows a log-normal distribution, so Black-Scholes-like formulas apply.
Parameters¶
s0, k, r, sigma, T : float Standard option parameters. n_monitoring : int Number of equally spaced monitoring dates. is_call : bool Call or put.
Returns¶
float Option price.
build_asian_estimation_problem(spec)
¶
Build QAE estimation problem for Asian option pricing.
Uses a simplified single-step approximation: loads the distribution of the average price and applies payoff comparator.
For multi-step paths, the average distribution is approximated by a log-normal with adjusted parameters.
Returns¶
tuple of (EstimationProblem, rescale_factor)
Barrier Options¶
barrier
¶
Barrier option pricing via QAE.
Constructs QAE estimation problems for barrier options with knock-in / knock-out features.
References¶
Stamatopoulos et al., Quantum 4:291 (2020), arXiv:1905.02666, Fig. 8.
BarrierOptionSpec
dataclass
¶
Barrier option specification.
Parameters¶
s0 : float Spot price. k : float Strike price. r : float Risk-free rate. sigma : float Volatility. T : float Time to expiry. barrier : float Barrier level. barrier_type : str One of "up-and-out", "down-and-out", "up-and-in", "down-and-in". is_call : bool True for call, False for put. n_qubits : int Qubits for price discretization.
barrier_closed_form(s0, k, r, sigma, T, barrier, barrier_type='up-and-out', is_call=True)
¶
Closed-form barrier option price (Merton 1973, Reiner-Rubinstein 1991).
Only supports single-barrier European options. Uses in-out parity: knock-in + knock-out = vanilla.
build_barrier_estimation_problem(spec)
¶
Build QAE estimation problem for barrier option pricing.
Uses terminal price distribution with barrier condition applied as a constraint on the payoff function.
For single-step (European-style barrier checked only at expiry): payoff = max(S_T - K, 0) * I(barrier not breached at T)
Returns¶
tuple of (EstimationProblem, rescale_factor)
Bermudan Options¶
bermudan
¶
Bermudan option pricing via CRR binomial tree.
Supports early exercise only at user-specified exercise dates, interpolated to the nearest tree time-steps.
BermudanOptionSpec
dataclass
¶
Bermudan option specification.
Parameters¶
s0 : float Spot price. k : float Strike price. r : float Risk-free rate (annualised). sigma : float Volatility (annualised). T : float Time to expiry in years. exercise_dates : list[float] Times (in years) at which early exercise is permitted. Must be in (0, T]. is_call : bool True for call, False for put. n_steps : int Number of binomial tree time-steps.
Amplitude Estimation¶
Estimation Problem¶
estimation_problem
¶
Estimation problem abstraction for Quantum Amplitude Estimation.
Defines the oracle interface: a state preparation operator A and an objective qubit index such that measuring the objective qubit in |1> has probability a = sin^2(theta_a).
QAE estimates this probability a (or equivalently the angle theta_a).
References¶
Brassard et al., "Quantum Amplitude Amplification and Estimation" (2002). Stamatopoulos et al., Quantum 4:291 (2020), arXiv:1905.02666.
EstimationProblem
dataclass
¶
Amplitude estimation problem specification.
Parameters¶
state_preparation : Any Quantum circuit A that prepares the state. A|0> = sqrt(1-a)|psi_0>|0> + sqrt(a)|psi_1>|1> objective_qubits : list[int] Qubit indices that define the "good" subspace. grover_operator : Any | None Custom Grover operator Q = A S_0 A^dag S_chi. If None, constructed automatically from state_preparation. n_qubits : int Total number of qubits in the circuit. is_good_state : callable | None Function that takes a bitstring and returns True if it is in the "good" subspace. Defaults to checking objective qubits.
build_grover_operator()
¶
Build the Grover operator Q = -A S_0 A^dag S_chi.
Per Brassard et al. (2002) Eq. (4), the operator is:
Q = -A (I - 2|0><0|) A^dag (I - 2 P_good)
The minus sign ensures eigenvalues are e^{±2i*theta_a}, which is critical for QPE-based amplitude estimation to recover a = sin^2(theta_a) via the formula a = sin^2(pi * phi).
For circuit implementation, the global phase -1 is applied
via global_phase += pi, which becomes a relative phase on
the control qubit in controlled-Q operations (QPE).
Canonical QAE¶
canonical
¶
Canonical Amplitude Estimation with QPE (Brassard et al., 2002).
Uses Quantum Phase Estimation to estimate the eigenphase of the Grover operator, which encodes the amplitude a = sin^2(theta_a).
Requires m evaluation qubits; the estimate has precision O(2^{-m}).
References¶
Brassard, Hoyer, Mosca, Tapp, "Quantum Amplitude Amplification and Estimation", Contemporary Mathematics 305 (2002).
CanonicalAmplitudeEstimation
¶
Canonical QAE using Quantum Phase Estimation.
Estimates a = sin^2(theta) where theta is the eigenphase of the Grover operator Q.
Circuit structure: - m evaluation qubits initialized with H - Controlled-Q^{2^k} for k = 0, ..., m-1 - Inverse QFT on evaluation register - Measure evaluation register -> y - Estimate: a = sin^2(pi * y / 2^m)
The Grover operator Q has eigenvalues e^{±2i*theta_a}, so QPE returns y/2^m ≈ theta_a/pi or 1 - theta_a/pi. Both map to the same amplitude via a = sin^2(pi * y / 2^m).
estimate()
¶
Run canonical QAE and return the amplitude estimate.
CanonicalQAEConfig
dataclass
¶
Configuration for canonical (QPE-based) QAE.
CanonicalQAEResult
dataclass
¶
Bases: Result
Result from canonical QAE.
Iterative QAE (IQAE)¶
iqae
¶
Iterative Quantum Amplitude Estimation (Grinko-Gacon-Zoufal-Woerner, npj QI 2021).
arXiv:1912.05559. No QPE; quadratic speedup up to a double-log factor. Uses adaptive Grover iterations with confidence interval refinement.
The algorithm maintains a confidence interval [theta_low, theta_high] for the angle theta_a, and iteratively applies Q^k with carefully chosen k to narrow the interval until sin^2(theta_high) - sin^2(theta_low) <= 2*epsilon.
Key insight: after k Grover iterations, the measurement probability is p_k = sin^2((2k+1)*theta_a). Since sin^2 is periodic, a single measurement of p_k yields multiple candidate theta values. The algorithm intersects these candidates with the current interval to refine the estimate.
IterativeAmplitudeEstimation
¶
IQAE per Grinko et al. (1912.05559).
Key idea: instead of QPE, adaptively choose Grover iteration depths k_i and estimate a from the fraction of "good" measurements. Uses Clopper-Pearson or beta distribution confidence intervals.
The critical step is the multi-branch resolution: for depth k, the probability sin^2((2k+1)*theta) = p has O(k) solutions in [0, pi/2]. We enumerate all candidate theta intervals and intersect with the running interval to disambiguate.
estimate()
¶
Run IQAE main loop until CI half-width <= epsilon_target.
IQAEConfig
dataclass
¶
Configuration for IQAE.
IQAEResult
dataclass
¶
Bases: Result
Result from IQAE.
Classical Monte Carlo¶
monte_carlo
¶
Monte Carlo option pricing with variance reduction.
Supports antithetic variates and control variate (delta-based).
european_mc(s, k, r, sigma, T, n_paths=100000, option_type='call', q=0.0, antithetic=True, seed=42)
¶
Price a European option via Monte Carlo.
Parameters¶
s : float Spot price. k : float Strike. r : float Risk-free rate. sigma : float Volatility. T : float Time to expiry. n_paths : int Number of simulation paths. option_type : "call" or "put" Option type. q : float Continuous dividend yield. antithetic : bool Use antithetic variates for variance reduction. seed : int | None Random seed.
Returns¶
MCResult
asian_mc(s, k, r, sigma, T, n_steps=252, n_paths=100000, option_type='call', average_type='arithmetic', q=0.0, antithetic=True, seed=42)
¶
Price an Asian option via Monte Carlo.
Parameters¶
n_steps : int Number of monitoring points. average_type : "arithmetic" or "geometric" Type of average.
barrier_mc(s, k, r, sigma, T, barrier, barrier_type='up-and-out', n_steps=252, n_paths=100000, option_type='call', q=0.0, seed=42)
¶
Price a barrier option via Monte Carlo.
Heston Model¶
heston
¶
Heston stochastic-volatility option pricing via QAE.
Implements weak-Euler discretization of the Heston model for loading into quantum circuits, following Wang & Kan (2024).
The Heston model
dS = rSdt + sqrt(V)SdW_1 dV = kappa(theta - V)dt + xisqrt(V)dW_2 corr(dW_1, dW_2) = rho
References¶
Wang & Kan, Quantum 8:1504 (2024), arXiv:2312.15871. Heston, Review of Financial Studies 6(2):327-343 (1993).
HestonParams
dataclass
¶
Heston model parameters.
Parameters¶
s0 : float Initial stock price. v0 : float Initial variance. r : float Risk-free rate. kappa : float Mean reversion speed. theta : float Long-run variance. xi : float Vol-of-vol (volatility of variance). rho : float Correlation between stock and variance Brownian motions. T : float Time to expiry.
heston_weak_euler_terminal(params, n_steps=100, n_paths=100000, seed=42)
¶
Simulate Heston terminal prices using weak-Euler scheme.
Wang & Kan (2024) show that weak-Euler matches strong-Euler accuracy while eliminating the need for Gaussian state preparation on quantum hardware. The key insight: weak convergence only requires matching moments, not pathwise accuracy.
Uses full truncation to ensure V >= 0.
Returns¶
NDArray of shape (n_paths,) Terminal stock prices.
heston_strong_euler_terminal(params, n_steps=100, n_paths=100000, seed=42)
¶
Simulate Heston terminal prices using strong-Euler scheme.
Standard Euler-Maruyama with full truncation.
Returns¶
NDArray of shape (n_paths,) Terminal stock prices.
heston_european_price(params, k=100.0, is_call=True, n_steps=100, n_paths=200000, method='weak_euler', seed=42)
¶
heston_terminal_distribution(params, n_qubits=4, n_paths=200000, n_sigma=3.0, method='weak_euler', seed=42)
¶
Generate discretized terminal price distribution under Heston.
Simulates many paths and fits a histogram to create a DistributionSpec suitable for QAE loading.
Parameters¶
params : HestonParams Heston model parameters. n_qubits : int Qubits for discretization (2^n_qubits bins). n_paths : int Paths for Monte Carlo estimation. n_sigma : float Domain range in standard deviations from mean. method : str "weak_euler" or "strong_euler". seed : int | None Random seed.
Returns¶
DistributionSpec
resource_estimates(n_qubits_price, n_qubits_vol=0, n_steps=1)
¶
Estimate T-count and T-depth for Heston QAE circuit.
Based on Table III of Wang & Kan (2312.15871). These are approximate resource estimates for fault-tolerant implementations.
Parameters¶
n_qubits_price : int Qubits for price register. n_qubits_vol : int Qubits for volatility register (0 = BS, >0 = Heston). n_steps : int Number of time steps.
Returns¶
dict with 'total_qubits', 'T_count', 'T_depth', 'cnot_count'.
Path-Dependent QAE (Asian)¶
path_dependent_qae
¶
Path-dependent QAE for Asian option pricing.
Constructs a multi-register quantum circuit encoding discrete GBM price paths |S_1>|S_2>...|S_T>, computes the running average via quantum arithmetic, and estimates Asian option payoffs using QAE.
References¶
Stamatopoulos et al., Quantum 4:291 (2020), arXiv:1905.02666. Rebentrost et al., "Quantum computational finance: Monte Carlo pricing of financial derivatives", Phys. Rev. A 98, 022321 (2018).
PathDependentAsianSpec
dataclass
¶
Asian option specification for path-dependent QAE pricing.
Parameters¶
s0 : float
Spot price.
k : float
Strike price.
r : float
Risk-free rate.
sigma : float
Volatility.
T : float
Time to expiry (years).
n_steps : int
Number of monitoring dates (equally spaced).
is_call : bool
True for call, False for put.
average_type : str
"arithmetic" or "geometric".
n_qubits_per_step : int
Qubits per time step for price discretization.
price_asian_qae(spec, backend, qae_method='iqae', qae_config=None)
¶
Price an Asian option using path-dependent QAE.
Integrates with the existing QAE algorithms (canonical, IQAE, MLAE) to estimate the Asian option price from the path-dependent circuit.
Parameters¶
spec : PathDependentAsianSpec
Asian option specification.
backend : Backend
Quantum backend to execute circuits.
qae_method : str
QAE variant: "iqae", "canonical", or "mlae".
qae_config : Any
Configuration for the chosen QAE method. If None,
a default configuration is used.
Returns¶
PathDependentQAEResult Pricing result with price, confidence interval, and metadata.
price_asian_mc(spec, n_paths=100000, seed=42)
¶
Price an Asian option via classical Monte Carlo.
Simulates full GBM paths and computes arithmetic or geometric average payoffs as a classical benchmark.
Parameters¶
spec : PathDependentAsianSpec Asian option specification. n_paths : int Number of Monte Carlo paths. seed : int Random seed for reproducibility.
Returns¶
dict
Dictionary with keys "price", "std_error",
"ci_low", "ci_high", "n_paths".
build_path_state_preparation(spec)
¶
Build the multi-register state |S_1>|S_2>...|S_T>.
Encodes the joint distribution of a discrete GBM path using independent log-normal increments at each monitoring date. Under GBM, the increments are independent in log-space, so the joint state factorizes as a product of per-step distributions:
|psi> = |S_1> (x) |S_2> (x) ... (x) |S_T>
Each register is loaded with the marginal log-normal distribution for S_t given S_0, capturing the sequential GBM dynamics.
Parameters¶
spec : PathDependentAsianSpec Asian option specification.
Returns¶
tuple[QuantumCircuit, list[NDArray]]
The state preparation circuit and the list of per-step
price grids (each of shape (2**n_qubits_per_step,)).
American QAE (Quantum LSM)¶
american_qae
¶
American option pricing via quantum-accelerated Longstaff-Schwartz Monte Carlo.
Combines classical path simulation with quantum-enhanced regression for continuation value estimation, and optional QAE for final price aggregation.
The approach: 1. Simulate GBM paths classically (path simulation is not amenable to quantum speedup in the NISQ era). 2. At each exercise step, use a variational quantum solver (VQE-based least-squares) to fit continuation values from basis function features. 3. Apply backward induction with quantum regression to determine the early exercise boundary. 4. Optionally use QAE for the final discounted payoff estimation.
References¶
Longstaff & Schwartz (2001), "Valuing American Options by Simulation". Rebentrost et al. (2014), "Quantum Support Vector Machine", arXiv:1307.0471. Chakrabarti et al. (2021), "A threshold for quantum advantage in derivative pricing", Quantum 5:463, arXiv:2012.03819.
QuantumLSM
¶
Quantum-accelerated Longstaff-Schwartz regression.
Uses a variational quantum eigensolver (VQE) approach to solve the least-squares regression for continuation values. The basis functions are encoded into quantum feature vectors, and a parameterised ansatz learns the optimal coefficients.
On NISQ hardware this provides a proof-of-concept for quantum-enhanced regression. For production use the classical fallback is recommended until fault-tolerant hardware is available.
Parameters¶
spec : AmericanQAESpec Option and algorithm specification. backend : Any | None Quantum backend for circuit execution. If None, uses classical least-squares as fallback.
price_american_qae(s0=100.0, k=100.0, r=0.05, sigma=0.2, T=1.0, is_call=False, n_steps=50, n_paths=10000, basis_type=BasisType.POLYNOMIAL, basis_degree=3, n_qubits=4, vqe_layers=2, backend=None, seed=42)
¶
Price an American option via quantum-accelerated Longstaff-Schwartz.
This is a convenience wrapper around :class:QuantumLSM.
Parameters¶
s0 : float Spot price. k : float Strike price. r : float Risk-free rate. sigma : float Volatility. T : float Time to expiry. is_call : bool True for call, False for put. n_steps : int Number of time steps. n_paths : int Number of Monte Carlo paths. basis_type : BasisType Basis function family. basis_degree : int Degree of basis functions. n_qubits : int Number of qubits for quantum regression. vqe_layers : int Number of variational layers. backend : Any | None Quantum backend. If None, uses classical regression. seed : int | None Random seed.
Returns¶
AmericanQAEResult Pricing result.
price_american_classical(s0=100.0, k=100.0, r=0.05, sigma=0.2, T=1.0, is_call=False, n_steps=50, n_paths=50000, basis_type=BasisType.POLYNOMIAL, basis_degree=3, seed=42)
¶
Classical LSM baseline for American option pricing.
Parameters¶
s0, k, r, sigma, T : float Standard option parameters. is_call : bool True for call, False for put. n_steps : int Number of time steps. n_paths : int Number of Monte Carlo paths. basis_type : BasisType Basis function family. basis_degree : int Degree of basis functions. seed : int | None Random seed.
Returns¶
dict
price, std_err.
american_binomial(s0=100.0, k=100.0, r=0.05, sigma=0.2, T=1.0, is_call=False, n_steps=500)
¶
Price an American option using the CRR binomial tree.
Used as a reference price for validation.
Parameters¶
s0, k, r, sigma, T : float Standard option parameters. is_call : bool True for call, False for put. n_steps : int Number of binomial tree steps (higher = more accurate).
Returns¶
float Option price.
estimate_resources(n_steps=50, basis_degree=3, n_qubits_regression=4, vqe_layers=2, n_eval_qubits_qae=5)
¶
Estimate quantum resources for American option pricing.
Parameters¶
n_steps : int Number of time steps in the option. basis_degree : int Degree of basis functions for regression. n_qubits_regression : int Qubits per regression circuit. vqe_layers : int Number of variational ansatz layers. n_eval_qubits_qae : int Evaluation qubits for QAE final estimation.
Returns¶
ResourceEstimate Resource breakdown.
Implied Volatility Surface¶
implied_vol_surface
¶
Implied volatility surface modeling via quantum and classical regression.
Provides quantum kernel (QSVM) and variational quantum circuit (VQC) regression for interpolating / extrapolating the IV surface, plus classical baselines (SABR, SVI parameterisation).
References¶
- Gatheral, The Volatility Surface, Wiley, 2006.
- Havlicek et al., Nature 567, 209-212 (2019).
- Hagan et al., Wilmott Magazine, Jan 2002 (SABR).
QuantumIVSurface
¶
Implied volatility surface modelling via quantum regression.
Supports QSVM kernel regression, VQC regression, and classical baselines (SABR, SVI). All models are fit on (K/S, T) -> IV.
Parameters¶
config : QuantumIVSurfaceConfig Model configuration. backend : Backend or None Quantum backend (required for 'qsvm' and 'vqc' methods).
Examples¶
from qufin.backends.mock import MockBackend cfg = QuantumIVSurfaceConfig(n_qubits=2, method="qsvm") model = QuantumIVSurface(cfg, MockBackend(seed=0)) model.fit(data) preds = model.predict(strikes, expiries, spot)
fit(data, r=0.0)
¶
predict(strikes, expiries, spot, method=None, r=0.0)
¶
Predict implied volatilities at given strikes and expiries.
Parameters¶
strikes : array of shape (n,) expiries : array of shape (n,) spot : float method : str or None Override the configured method ('qsvm', 'vqc', 'sabr', 'svi'). If None, uses the configured method (or 'qsvm' when 'all'). r : float Risk-free rate (used by SABR).
Returns¶
NDArray of shape (n,) Predicted implied volatilities.
evaluate(test_data, method=None, r=0.0)
¶
plot_surface(spot=100.0, strike_range=(80.0, 120.0), expiry_range=(0.1, 2.0), n_grid=30, method=None, r=0.0, ax=None)
¶
Plot the fitted IV surface as a 3D surface.
Parameters¶
spot : float Spot price. strike_range : tuple (min_strike, max_strike). expiry_range : tuple (min_T, max_T). n_grid : int Grid resolution per axis. method : str or None Which model to plot. r : float Risk-free rate. ax : matplotlib Axes3D or None Existing 3D axes to plot on.
Returns¶
matplotlib Axes3D