API reference¶
Overview¶
RoughHestonParam¶
| Field | Type | Description |
|---|---|---|
lam |
float |
Mean-reversion speed \(\lambda\) |
theta |
float |
Drift constant \(\theta\); the long-run variance is \(\theta/\lambda\) |
nu |
float |
Vol-of-vol \(\nu\) |
rho |
float |
Spot–vol correlation \(\rho \in (-1, 1)\) |
V0 |
float |
Initial variance \(V_0\) |
H |
float |
Hurst exponent \(H \in (-\tfrac{1}{2}, \tfrac{1}{2}]\); \(H = \tfrac{1}{2}\) is classical Heston |
RoughHeston(param, riskfree, base_solution="auto", ...)¶
| Argument | Description |
|---|---|
param |
RoughHestonParam instance |
riskfree |
Continuously compounded risk-free rate \(r\) |
base_solution |
Riccati solver: "auto", "root_pade", "exact_heston", "pade", "direct_riccati" |
pade_order |
"22", "33", or "44" (only for "pade") |
root_pade_degree |
Padé numerator degree \(m\) (default 9; Hager & Kreher 2026 use 7) |
root_pade_tail_match |
Replace the highest short-time Padé equation with the exact large-\(x\) tail constraint (default True) |
log_cf_integrand |
What the log characteristic function integrates: "solution" integrates the Riccati solution \(h\), \(\theta\, I^1 h(T) + V_0\, I^{1-\alpha} h(T)\) (El Euch & Rosenbaum 2019); "rhs" integrates the right-hand side, \(\int_0^T F(h(s))\,(V_0 + \theta (T-s)^\alpha/\Gamma(1+\alpha))\, ds\), as in Hager & Kreher (2026), Eq. (1.1). Both are exact for the exact \(h\). "solution" does not amplify the error of an approximate \(h\); "rhs" restores the target's short-time behaviour, which helps expansions from \(H_0 = \tfrac12\). "auto" (default) uses "rhs" for expansions from \(H_0 = \tfrac12\) and "solution" otherwise. For the paper's settings see Reproducing the paper |
model.eur_call_put(K, maturity, ...)¶
| Argument | Default | Description |
|---|---|---|
K |
— | Strike(s), scalar or array |
maturity |
— | Option maturity \(T > 0\) |
S_0 |
1.0 |
Initial spot \(S_0\) |
call |
True |
True returns calls, False puts |
digital |
False |
Cash-or-nothing digitals instead of vanillas |
implied_vol |
False |
Return Black–Scholes implied vols \(\sigma_\text{BS}\) (vanillas only) |
payoff_selection |
"otm" |
"otm" prices the out-of-the-money option at each strike (calls for \(K \ge F\), puts otherwise) and converts to call by put–call parity; "as_requested" prices the requested option directly |
expansion_order |
0 |
Taylor order \(N\) in \(H\) |
H |
None |
Target \(H\) (scalar or array; None uses param.H) |
L |
None |
Fourier truncation \(L\). None picks where \(\lvert\varphi\rvert\) has decayed to about \(10^{-10}\), from the model parameters and maturity |
integration |
"panel" |
"panel" (fixed \(L\)) or "adaptive_panel" (auto-select \(L\); warns when no two successive \(L\) agree) |
time_steps |
400 |
Time-grid nodes for the expansion Volterra solve |
time_grid |
"graded" |
"graded" clusters nodes near \(t = 0\), where the solution is rough; "uniform" or "symmetric_graded". Adams needs "uniform" |
R |
0.5 |
Fourier contour height. \(R = 0.5\) prices every strike as a call and gets puts by parity (the Lewis contour for vanillas); it needs only \(E[S_T^{1/2}]\), which is always finite. Other values use damped contours at \(\pm \lvert R\rvert\), which need \(E[S_T^{\pm \lvert R\rvert}] < \infty\). Below \(\lvert R\rvert = 1\) vanilla calls get the residue \(S_0\) of the payoff's pole at 1 added, as in the Lewis formula (half of it at 1); \(R = 0\) runs through the pole at 0 and adds half of its residue. Near a pole the integrand has a peak of width \(\lvert R - \text{pole}\rvert\) at \(u = 0\): \(10^{-2}\) from a pole prices are off by \(4 \cdot 10^{-9}\), \(10^{-3}\) from it by up to \(2 \cdot 10^{-3} S_0\) |
m_cheb |
16 |
Chebyshev nodes per Fourier panel |
adaptive_tol |
1e-4 |
Max implied-vol change threshold for adaptive convergence (digitals compare prices instead) |
accuracy_check |
True |
Estimate the error of the H-expansion and of the Padé bases and warn when it exceeds accuracy_tol; see Accuracy |
accuracy_tol |
1e-4 |
Warning threshold of the check, in implied vol (1 bp) |
Model¶
RoughHestonParam
dataclass
¶
RoughHestonParam(
lam: float = 0.3,
theta: float = 0.3 * 0.02,
nu: float = 0.3,
rho: float = -0.7,
V0: float = 0.02,
H: float = 0.4,
)
Parameters for the rough Heston stochastic volatility model.
The variance process satisfies
dS_t = sqrt(V_t) S_t dW_t
V_t = V0 + (1/Γ(H+½)) ∫₀ᵗ (t-s)^(H-½) [(theta - lam*V_s) ds
+ nu*sqrt(V_s) dB_s]
corr(dW_t, dB_t) = rho
where H ∈ (-½, ½] is the Hurst exponent; H = ½ recovers classical Heston. All parameters are the raw (un-normalised) Riccati coefficients, so the drift constant is theta itself and not lamtheta: in the usual Heston parameterisation dV = kappa(vbar - V)dt, set lam = kappa and theta = kappavbar.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
lam
|
float
|
Mean-reversion speed of the variance process. |
0.3
|
theta
|
float
|
Raw drift constant. The long-run variance is theta/lam, which the defaults below make equal to V0. |
0.3 * 0.02
|
nu
|
float
|
Vol-of-vol (raw, un-normalised). |
0.3
|
rho
|
float
|
Correlation between price and variance Brownian motions; typically < 0. |
-0.7
|
V0
|
float
|
Initial instantaneous variance. |
0.02
|
H
|
float
|
Hurst exponent; must lie in (-½, ½]. H = ½ → classical Heston. |
0.4
|
RoughHeston ¶
RoughHeston(
param: RoughHestonParam,
riskfree: float,
base_solution: str = "auto",
pade_order: str = "22",
root_pade_series_order: int | None = None,
root_pade_degree: int = 9,
root_pade_tail_match: bool = True,
direct_riccati_solver: Literal[
"auto", "adams", "implicit_pi"
] = "auto",
log_cf_integrand: Literal[
"auto", "solution", "rhs"
] = "auto",
)
Bases: object
Rough Heston model pricer based on a fractional-Riccati Taylor expansion.
The log-price characteristic function is approximated by expanding the
fractional Riccati solution around an anchor Hurst exponent H₀ = param.H
to arbitrary order in ΔH = H_target - H₀. At order 0 the expansion
collapses to the exact model characteristic function at the anchor.
The anchor Riccati solution h(u, t; H₀) is computed by the method
selected via base_solution:
"root_pade"— root-transformed Padé approximant."exact_heston"— closed-form classical Heston (only valid at H₀ = ½)."pade"— Gatheral Padé [m/m] approximant."direct_riccati"— numerical fractional ODE solver (Adams or implicit-π)."auto"—"exact_heston"whenH₀ = ½, else"direct_riccati"with implicit-π.
European option prices are computed via Fourier inversion on the Lewis
contour (R = 0.5) or a damped-payoff contour (any other R).
Initialise the rough Heston pricer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
param
|
RoughHestonParam
|
Model parameters. |
required |
riskfree
|
float
|
Continuously compounded risk-free rate. |
required |
base_solution
|
(auto, root_pade, exact_heston, pade, direct_riccati)
|
Method used to solve the base Riccati equation at the anchor.
|
"auto"
|
pade_order
|
(22, 33, 44)
|
Padé order; only used when |
"22"
|
root_pade_series_order
|
int or None
|
Number of short-time series coefficients for the root-Padé solve;
|
None
|
root_pade_degree
|
int
|
Numerator degree |
9
|
root_pade_tail_match
|
bool
|
If |
True
|
direct_riccati_solver
|
(auto, adams, implicit_pi)
|
Fractional ODE solver when |
"auto"
|
log_cf_integrand
|
(auto, solution, rhs)
|
What the log characteristic function integrates over |
"auto"
|
eur_call_put ¶
eur_call_put(
K,
maturity: float,
S_0: float = 1.0,
call: bool = True,
digital: bool = False,
implied_vol: bool = False,
payoff_selection: str = "otm",
R: float = 0.5,
integration: Literal[
"panel", "adaptive_panel"
] = "panel",
L: float | None = None,
panels=None,
m_cheb: int = 16,
q_weight: int = 128,
time_steps_phi0: int | None = None,
expansion_order: int = 0,
time_steps: int = 400,
H=None,
adaptive_metric: Literal["price", "iv"] = "iv",
adaptive_tol: float = 0.0001,
adaptive_abs_tol: float = 1e-08,
adaptive_rel_tol: float = 1e-06,
adaptive_L_candidates: list | None = None,
adaptive_max_iter: int = 8,
adaptive_verbose: bool = False,
time_grid: Literal[
"uniform", "graded", "symmetric_graded"
] = "graded",
grid_power: float | None = None,
accuracy_check: bool = True,
accuracy_tol: float = 0.0001,
) -> np.ndarray
Price European calls or puts via Fourier quadrature on the Heston measure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
K
|
array - like
|
Strike prices. |
required |
maturity
|
float
|
Option maturity T > 0. |
required |
S_0
|
float
|
Initial spot price. |
1.0
|
call
|
bool
|
|
True
|
digital
|
bool
|
Price digital (cash-or-nothing) payoffs instead of vanilla. |
False
|
implied_vol
|
bool
|
If |
False
|
payoff_selection
|
(otm, as_requested)
|
|
"otm"
|
R
|
float
|
Fourier contour height. The default |
0.5
|
L
|
float or None
|
Upper truncation of the Fourier integral. |
None
|
panels
|
array - like or None
|
Explicit Chebyshev panel breakpoints. Overrides |
None
|
m_cheb
|
int
|
Chebyshev nodes per panel. |
16
|
q_weight
|
int
|
Number of nodes for the quadrature weight pre-computation. |
128
|
time_steps_phi0
|
int or None
|
Time-grid nodes for the order-0 (phi0) solve. |
None
|
expansion_order
|
int
|
Taylor expansion order N in H around |
0
|
time_steps
|
int
|
Time-grid nodes for the expansion solve. |
400
|
H
|
float, array-like, or None
|
Target Hurst exponent(s). |
None
|
integration
|
(panel, adaptive_panel)
|
|
"panel"
|
adaptive_metric
|
(price, iv)
|
Convergence criterion for adaptive integration: the change of the
out-of-the-money prices or of their implied vols. Digitals always
use |
"price"
|
adaptive_tol
|
float
|
Tolerance of the |
0.0001
|
adaptive_abs_tol
|
float
|
Absolute and relative tolerances of the |
1e-08
|
adaptive_rel_tol
|
float
|
Absolute and relative tolerances of the |
1e-08
|
adaptive_L_candidates
|
list or None
|
Explicit sequence of |
None
|
adaptive_max_iter
|
int
|
Maximum number of adaptive refinement iterations. When no two
successive |
8
|
adaptive_verbose
|
bool
|
Print convergence information at each adaptive step. |
False
|
time_grid
|
(uniform, graded, symmetric_graded)
|
Time-node distribution; see :meth: |
"uniform"
|
grid_power
|
float or None
|
Grading exponent; |
None
|
accuracy_check
|
bool
|
If |
True
|
accuracy_tol
|
float
|
Warning threshold of the check, in implied volatility (1e-4 = 1 bp). |
0.0001
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Option prices (or implied vols) of shape |
charfun ¶
charfun(
arg: ndarray,
maturity: float = 1.0,
order: int = 0,
time_steps: int = 400,
H=None,
time_grid: Literal[
"uniform", "graded", "symmetric_graded"
] = "graded",
grid_power: float | None = None,
) -> np.ndarray
Characteristic function. See log_charfun for the H parameter.
log_charfun ¶
log_charfun(
arg: ndarray,
maturity: float = 1.0,
order: int = 0,
time_steps: int = 400,
H=None,
time_grid: Literal[
"uniform", "graded", "symmetric_graded"
] = "graded",
grid_power: float | None = None,
) -> np.ndarray
Log characteristic function E[exp(i u log(S_T/S_0))].
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
arg
|
ndarray
|
Complex Fourier argument, shape |
required |
maturity
|
float
|
Option maturity T. |
1.0
|
order
|
int
|
Taylor expansion order in H around the anchor |
0
|
time_steps
|
int
|
Number of time-grid nodes. With the exact-Heston base the log CF at H = ½ is in closed form and does not use the grid. |
400
|
H
|
float, array-like, or None
|
Target Hurst exponent(s). |
None
|
time_grid
|
(uniform, graded, symmetric_graded)
|
Time discretisation; see :meth: |
"uniform"
|
grid_power
|
float or None
|
Grading exponent; |
None
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Shape |
expansion_state ¶
expansion_state(
arg: ndarray,
maturity: float = 1.0,
order: int = 0,
time_steps: int = 400,
H: float | None = None,
return_lists: bool = False,
anchor: float | None = None,
base: Literal[
"auto",
"exact_heston",
"pade",
"root_pade",
"direct_riccati",
]
| None = None,
pade_order: str | None = None,
root_pade_degree: int | None = None,
root_pade_series_order: int | None = None,
root_pade_tail_match: bool | None = None,
time_grid: Literal[
"uniform", "graded", "symmetric_graded"
] = "graded",
grid_power: float | None = None,
direct_riccati_solver: Literal[
"auto", "adams", "implicit_pi"
]
| None = None,
) -> HestonExpansionState
Compute the fractional-Riccati expansion state at a given Fourier argument.
Solves the base Riccati equation at the anchor H₀ and accumulates
the H-derivative fields f_0, f_1, …, f_order on the time grid.
The result can be passed directly to :meth:log_charfun_from_field or
inspected for diagnostics.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
arg
|
ndarray
|
Complex Fourier argument, shape |
required |
maturity
|
float
|
Option maturity T > 0. |
1.0
|
order
|
int
|
Taylor expansion order N. Order 0 gives the exact anchor solution. |
0
|
time_steps
|
int
|
Number of time-grid nodes on |
400
|
H
|
float or None
|
Target Hurst exponent for the expansion evaluation.
|
None
|
return_lists
|
bool
|
If |
False
|
anchor
|
float or None
|
Override the expansion anchor for this call only.
|
None
|
base
|
str or None
|
Override |
None
|
pade_order
|
str | None
|
Per-call overrides for the corresponding constructor settings. |
None
|
root_pade_degree
|
str | None
|
Per-call overrides for the corresponding constructor settings. |
None
|
root_pade_series_order
|
str | None
|
Per-call overrides for the corresponding constructor settings. |
None
|
root_pade_tail_match
|
str | None
|
Per-call overrides for the corresponding constructor settings. |
None
|
time_grid
|
(uniform, graded, symmetric_graded)
|
Time-node distribution. |
"uniform"
|
grid_power
|
float or None
|
Grading exponent; |
None
|
direct_riccati_solver
|
(auto, adams, implicit_pi)
|
Per-call override for the fractional ODE solver. |
"auto"
|
Returns:
| Type | Description |
|---|---|
HestonExpansionState
|
|
HestonExpansionState
dataclass
¶
HestonExpansionState(
grid: TimeGrid,
u: ndarray,
alpha: float,
f0: object,
expansion: object,
F_ricc: Callable,
kappa_path: object,
kappa_path_reflected: object,
f_list: list | None = None,
F_list: list | None = None,
target_H: float | None = None,
anchor_H: float | None = None,
)
Intermediate state returned by :meth:RoughHeston.expansion_state.
Attributes:
| Name | Type | Description |
|---|---|---|
grid |
TimeGrid
|
Time discretisation used for the Volterra solve. |
u |
ndarray
|
Complex Fourier argument array, shape |
alpha |
float
|
|
f0 |
Field
|
Base Riccati solution |
expansion |
Field
|
Taylor-summed approximation |
F_ricc |
Callable
|
Unscaled Riccati right-hand side |
kappa_path |
Field
|
Conditional-mean path |
kappa_path_reflected |
Field
|
Same path evaluated at |
f_list |
list[Field] or None
|
Expansion coefficients |
F_list |
list[Field] or None
|
Corresponding Riccati RHS evaluations; populated alongside |
target_H |
float or None
|
Hurst exponent at which |
anchor_H |
float or None
|
Expansion anchor H₀. |
Riccati solutions in closed form¶
rough_heston_root_pade_f0 ¶
rough_heston_root_pade_f0(
u: ndarray,
t: ndarray,
param,
*,
degree: int = 9,
H: float = 0.0,
tail_match: bool = True,
) -> np.ndarray
Root-transformed Padé approximation of the rough Heston Riccati base solution.
Matches exact short-time Riccati coefficients in the large-u-aware variable x = nu * aa * t^alpha (alpha = H_anchor + 0.5), builds a [degree / (degree+1)] Padé approximant for the root-relaxation variable E (denominator one degree higher so E→0 as x→∞), and reconstructs:
h = A0 * (1 - E) / (r_plus - r_minus * E)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
u
|
ndarray
|
|
required |
t
|
ndarray
|
|
required |
param
|
|
required | |
degree
|
int
|
|
9
|
H
|
float
|
|
0.0
|
tail_match
|
bool
|
|
True
|
Returns:
| Type | Description |
|---|---|
(N_u, N_t) complex array
|
|
rough_heston_pade_f0 ¶
rough_heston_pade_f0(
u: ndarray,
t: ndarray,
param,
*,
pade_order: str = "22",
H_anchor: float = 0.0,
) -> np.ndarray
Base Riccati path at the anchor using a Padé approximation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
u
|
ndarray
|
|
required |
t
|
ndarray
|
|
required |
param
|
|
required | |
pade_order
|
str
|
|
'22'
|
H_anchor
|
float
|
|
0.0
|
Returns:
| Type | Description |
|---|---|
(N_u, N_t) complex array — f0(u, t), time on last axis
|
|
h_pade22 ¶
h_pade22(
a: ndarray,
tau: ndarray,
*,
H: float,
rho: float,
nu: float,
lam: float,
) -> np.ndarray
Gatheral Padé 2/2 approximation of the rough Heston Riccati solution.
Parameters
Parameters
a : (N_a,) complex — CF argument (a = u in expansion_state convention)
tau : (N_tau,) float — time values (non-negative)
H : float — Hurst exponent at the anchor (0.0 for H=0 anchor)
rho : float — correlation
nu : float — vol-of-vol (raw, not normalized)
lam : float — mean-reversion speed (raw, not normalized)
Returns:
| Type | Description |
|---|---|
(N_a, N_tau) complex array — h(a, tau), time on last axis.
|
h(a, 0) = 0 for all a. |
h_pade33 ¶
h_pade33(
a: ndarray,
tau: ndarray,
*,
H: float,
rho: float,
nu: float,
lam: float,
) -> np.ndarray
Gatheral Padé 3/3 approximation of the rough Heston Riccati solution.
Parameters
Parameters
a : (N_a,) complex — CF argument (a = u in expansion_state convention)
tau : (N_tau,) float — time values (non-negative)
H : float — Hurst exponent at the anchor (0.0 for H=0 anchor)
rho : float — correlation
nu : float — vol-of-vol (raw, not normalized)
lam : float — mean-reversion speed (raw, not normalized)
Returns:
| Type | Description |
|---|---|
(N_a, N_tau) complex array — h(a, tau), time on last axis.
|
h(a, 0) = 0 for all a. |
h_pade44 ¶
h_pade44(
a: ndarray,
tau: ndarray,
*,
H: float,
rho: float,
nu: float,
lam: float,
) -> np.ndarray
Gatheral Padé 4/4 approximation of the rough Heston Riccati solution.
At H = 0 the long-time coefficient g3 has a pole; there the limit H -> 0 is
returned.
Parameters
Parameters
a : (N_a,) complex — CF argument (a = u in expansion_state convention)
tau : (N_tau,) float — time values (non-negative)
H : float — Hurst exponent at the anchor (0.0 for H=0 anchor)
rho : float — correlation
nu : float — vol-of-vol (raw, not normalized)
lam : float — mean-reversion speed (raw, not normalized)
Returns:
| Type | Description |
|---|---|
(N_a, N_tau) complex array — h(a, tau), time on last axis.
|
h(a, 0) = 0 for all a. |
Time grids and Volterra operators¶
TimeGrid
dataclass
¶
TimeGrid(t: ndarray)
Explicit time grid on [0, T]. Time is the LAST axis in all fields.
uniform
staticmethod
¶
uniform(T: float, J: int) -> 'TimeGrid'
Uniform grid from 0 to T inclusive with J panels (J+1 nodes).
graded
staticmethod
¶
graded(T: float, J: int, power: float = 2.0) -> 'TimeGrid'
Grid clustered near t=0 via t_j = T * (j/J)^power.
symmetric_graded
staticmethod
¶
symmetric_graded(
T: float, J: int, power: float = 2.0
) -> "TimeGrid"
Symmetric power grid clustered near both t=0 and t=T.
Satisfies t[J-j] = T - t[j], making it suitable for pricing where ψ(t) is singular near t=0 and κ(T-t) is singular near t=T.
index_of_time ¶
index_of_time(
tau: Union[str, float, int], mode: str = "nearest"
) -> int
Map a time designator to a grid index. - "T": last node - int: treated as an index (validated) - float: mapped to nearest (default) or left neighbor
Field ¶
Field(values, grid: TimeGrid)
A function sampled on a TimeGrid. Shape convention: values.shape == (..., J+1), where the last axis is time. Leading axes are arbitrary batch dims (e.g., z-grid).
values is stored as a JAX array; use jnp operations throughout. Wrap in jax.jit at the call site to compile the full pipeline.
from_callable
staticmethod
¶
from_callable(
func, grid: TimeGrid, *, dtype=np.complex128
) -> "Field"
Evaluate func(t) on the given grid and wrap as a Field.
Integrate ¶
Integrate(
grid: TimeGrid,
kernel: KernelType = "regular",
*,
order: Union[float, int] = 0,
frac_power: float = 0.0,
start: Union[float, int, str] = 0,
stop: Optional[Union[float, int, str]] = None,
mode: str = "nearest",
from_: Optional[Union[float, int, str]] = None,
to: Optional[Union[float, int, str]] = None,
)
Grid-aware integration operator with product-integration weights.
Volterra (cumulative on grid) → returns Field (..., J+1) Definite [start, stop] → returns ndarray (...,)
Weight matrices are built once via Numba then stored as JAX arrays. The matmul path (K @ f) dispatches to jnp.matmul and runs on GPU/TPU when JAX is configured with an accelerator backend.
weights_matrix
property
¶
weights_matrix: ndarray
Dense lower-triangular product-integration matrix Ω (numpy).
Available for kernel='log', 'fraclog', and 'frac' without stop.
Raises ValueError for kernel='regular' and for a definite 'frac' integral,
which store only the weights they apply.
__matmul__ ¶
__matmul__(
obj: Union[Field, ArrayLike, callable],
) -> Union[Field, jnp.ndarray]
Apply to Field / callable / ndarray (broadcast to Field). Volterra mode → Field (..., J+1) Definite mode → jnp.ndarray (...,)
LinearVolterraSolver ¶
LinearVolterraSolver(
grid: TimeGrid, K: "Integrate", *, scale: complex = 1.0
)
Solve x(t) = rhs(t) + scale * ∫_0^t K(t,s) coeff(s) x(s) ds
by forward substitution in blocks of time steps (see _blocked_forward_solve), jitted at module level, so it compiles once per input shape.
Supports batched complex arrays with time as the last axis.
solve ¶
solve(rhs, coeff) -> 'Field'
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rhs
|
|
required | |
coeff
|
array-like, callable, or Field (..., J+1)
|
|
required |
Returns:
| Type | Description |
|---|---|
Field with time as last axis, dtype complex128.
|
|
ProductIntegrationRiccatiSolver ¶
ProductIntegrationRiccatiSolver(
grid: TimeGrid,
alpha: float,
c,
beta,
gam: float,
*,
blowup_threshold: float | None = 1e70,
)
Implicit product-integration solver for the Volterra Riccati equation
psi(t) = ∫_0^t (t-s)^(alpha-1) F(psi(s)) ds,
where F(x) = c - betax + 0.5gam*x**2 is the Riccati right-hand side.
The Adams PECE solver is useful as a cheap uniform-grid method, but it can become unstable for hyper-rough cases H < 0 on large Fourier contours. This solver treats the quadratic Riccati term implicitly at each node by solving the arising scalar quadratic exactly, and supports uniform, graded, and symmetric_graded grids. With product-integration weights Omega, step j reads
psi_j = hist_j + Omega[j, j] F(psi_j), hist_j = Σ_{k<j} Omega[j, k] F(psi_k),
a quadratic in psi_j, of which the root closest to the linearised value is taken. The time steps run in blocks (see _blocked_forward_solve).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
grid
|
TimeGrid
|
Time grid (uniform, graded, or symmetric_graded). |
required |
alpha
|
float
|
Fractional order, 0 < alpha <= 1. |
required |
c
|
(array - like, shape(n_u), complex)
|
Constant term in F. |
required |
beta
|
(array - like, shape(n_u), complex)
|
Linear coefficient in F. |
required |
gam
|
float
|
Quadratic coefficient in F (real scalar). |
required |
blowup_threshold
|
float or None
|
Values with |psi| > threshold are replaced by NaN after solving. |
1e+70
|
AdamsFractionalRiccatiSolver ¶
AdamsFractionalRiccatiSolver(
grid: TimeGrid,
alpha: float,
F,
*,
F_args: tuple = (),
normalized: bool = False,
corrector_iterations: int = 1,
blowup_threshold: float | None = 1e70,
)
Adams predictor-corrector solver for the raw Volterra equation
h(t) = scale * ∫_0^t (t-s)^(alpha-1) F(h(s)) ds,
where scale=1 (normalized=False) or scale=1/Gamma(alpha) (normalized=True).
F must accept (j, x, *F_args) where j is a JAX integer (time
index, ignored for time-independent fields) and x has the batch shape.
Returns an array of the same batch shape.
Time is the last axis; the batch dimensions are leading. Supports
batched complex arrays, e.g. shape (N_u, J+1).
The scan is jitted at module level with F as a static argument: a
module-level F with its coefficients in F_args compiles once per
shape, a closure built per call compiles on every solve.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
grid
|
TimeGrid
|
Must be a uniform grid. |
required |
alpha
|
float
|
Fractional order, 0 < alpha <= 1. |
required |
F
|
callable
|
Vector field |
required |
F_args
|
tuple
|
Arrays passed to |
()
|
normalized
|
bool
|
If True, include the 1/Gamma(alpha) factor in the kernel. |
False
|
corrector_iterations
|
int
|
Number of PECE corrector sweeps (>= 1). |
1
|
blowup_threshold
|
float or None
|
Values with |h| > threshold are replaced by NaN after solving. |
1e+70
|
solve ¶
solve(initial=None) -> 'Field'
Solve and return a Field with time as the last axis.
The batch shape is inferred by calling F(0, 0) once.
suggested_time_grid_power ¶
suggested_time_grid_power(anchor_H: float) -> float
Grading exponent matched to the short-time singularity at the given anchor.
anchor=0.0 → ~2.6, anchor=0.5 → 1.0 (uniform).
Fourier pricing¶
Generic Fourier quadrature pricing utilities.
Works with plain numpy/JAX arrays — no model objects.
General methodology
Pricing is split into a model-independent quadrature stage and a model-dependent evaluation stage. The characteristic function is factored as
phi(u, T) = phi_0(u, T) * hN(u, T)
where phi_0 is the base characteristic function (the order-0 Riccati solution, cheap to reuse across strikes and maturities) and hN is the expansion correction (phi_N / phi_0, capturing the Taylor correction in H). At expansion order 0 one has hN = 1 identically.
The separation is useful because the Chebyshev interpolation weights W
depend only on phi_0 and the payoff, while hN is evaluated on the coarse
node grid and multiplied in cheaply. For a rough-Heston model the
caller produces phi_0 and hN via model.expansion_state together with
model.log_charfun_from_field; the high-level entry point
RoughHeston.eur_call_put_measure_quad handles this automatically.
Two contour paths are provided:
Damped-measure path (any real R): Contour: u + iR, dampening factor exp(-R * log K) absorbed into the payoff transform. Needs E[S_T^R] to be finite. The integral is the price for R > 1 (vanilla calls), R > 0 (digital calls) or R < 0 (puts); on other contours step 4 adds the payoff poles in between. RoughHeston prices digitals on R = 0.5 by default, which needs only E[S_T^0.5].
1. build_panel_quadrature — build Chebyshev–GL panel nodes once
2. measure_weights_from_phi — W[k,j] = ∫ payoff_hat(K_k, u+iR) S^-i(u+iR) phi_0(u+iR) ℓ_j(u) du
3. eur_call_put_from_weights — price[k] = (disc/π) Re(W[k,:] @ hN)
4. damped_contour_residues — + the residues of the poles at R = 0 and R = 1
Lewis contour path (R = 0.5, calls only): Contour: u - i/2. No dampening factor; numerically recommended.
1. build_panel_quadrature — same quadrature setup
2. lewis_weights_from_phi — W[k,j] = ∫ exp(iu log(S/K_k))/(u²+¼) phi_0(u) ℓ_j(u) du
3. eur_call_from_lewis_weights — C_k = S - (disc/π) sqrt(S·K_k) Re(W[k,:] @ hN)
PanelQuadrature
dataclass
¶
PanelQuadrature(
u_nodes: ndarray,
u_quad: ndarray,
w_quad: ndarray,
Lmat: ndarray,
panels: ndarray,
panel_data: list = list(),
)
Pre-built panel quadrature for the Fourier u-axis integration.
u_nodes — Chebyshev interpolation nodes across all panels; shape (N_u,). hN (the correction multiplier) is evaluated here. u_quad — Gauss-Legendre quadrature points across all panels; shape (N_q,). phi0 (the base char function) is evaluated here. w_quad — GL weights (panel-scaled); shape (N_q,). Lmat — block-diagonal barycentric interpolation matrix (N_q, N_u).
build_panel_quadrature ¶
build_panel_quadrature(
panels: ndarray, m_cheb: int, q_weight: int
) -> PanelQuadrature
Build Chebyshev–Gauss-Legendre panel quadrature for the Fourier integral.
fourier_payoff_call_put ¶
fourier_payoff_call_put(
K, u, call=True, digital=False, logarithmic=True
)
Fourier transform of call/put payoff evaluated at complex argument u.
Args: K: strikes, real array (N_K,) u: complex frequency array (N_u,); includes the dampening shift call / digital / logarithmic: payoff variant flags
Returns: complex JAX array (N_K, N_u)
measure_weights_from_phi ¶
measure_weights_from_phi(
phi0: ndarray,
quad: PanelQuadrature,
K: ndarray,
R: float,
call: bool = True,
digital: bool = False,
S_0: float = 1.0,
) -> jnp.ndarray
Compute interpolation weights W[k, j] = ∫ payoff_hat(K_k, u) S_0^(-iu) phi0(u) ell_j(u) du.
Args: phi0: complex JAX array (N_q,) — base char function of log(S_T/S_0) at quad.u_quad quad: PanelQuadrature from build_panel_quadrature K: strike array (N_K,) R: dampening shift (real) call / digital: payoff variant S_0: spot price
Returns: complex JAX array (N_K, N_u)
eur_call_put_from_weights ¶
eur_call_put_from_weights(
weights: ndarray, hN: ndarray, discount: float
) -> jnp.ndarray
Price European options from interpolation weights and correction multiplier.
price[k] = discount / pi * Re( weights[k, :] @ hN )
Args: weights: complex JAX array (N_K, N_u) hN: complex JAX array (N_u,) — correction multiplier at u_nodes discount: exp(-r * T)
Returns: real JAX array (N_K,)
damped_contour_residues ¶
damped_contour_residues(
K: ndarray,
R: float,
S_0: float,
discount: float,
call: bool = True,
digital: bool = False,
) -> np.ndarray
Pole terms that turn eur_call_put_from_weights into the price on any contour.
The integral is the price itself when R lies in the payoff's strip: R > 1 for vanilla calls, R > 0 for digital calls, R < 0 for puts. Each pole of the payoff transform between R and that strip adds its residue, half of it when the contour runs through the pole: S_0 at R = 1 (vanillas), and K * discount (vanillas) or discount (digitals) at R = 0. For calls on R = 0.5 this is the Lewis formula, C = S_0 + integral.
Args: K: strike array (N_K,) R: contour height, as passed to measure_weights_from_phi S_0: spot price discount: exp(-r * T) call / digital: payoff variant
Returns: real numpy array (N_K,)
lewis_weights_from_phi ¶
lewis_weights_from_phi(
phi0: ndarray,
quad: PanelQuadrature,
K: ndarray,
S_0: float,
) -> jnp.ndarray
Compute Lewis weights W[k, j] for the contour u - i/2.
W[k, j] = int_0^L exp(iu*log(S_0/K_k)) / (u^2+1/4) * phi0(u) * ell_j(u) du
Args: phi0: complex JAX array (N_q,) — char function at quad.u_quad (real nodes) quad: PanelQuadrature from build_panel_quadrature K: strike array (N_K,) S_0: spot price
Returns: complex JAX array (N_K, N_u)
eur_call_from_lewis_weights ¶
eur_call_from_lewis_weights(
weights: ndarray,
hN: ndarray,
S_0: float,
K: ndarray,
discount: float,
) -> jnp.ndarray
Call price from Lewis weights and correction multiplier.
C_k = S_0 - discount * sqrt(S_0 * K_k) / pi * Re( weights[k, :] @ hN )
Args: weights: complex JAX array (N_K, N_u) hN: complex JAX array (N_u,) — correction multiplier at u_nodes S_0: spot price K: strike array (N_K,) discount: exp(-r * T)
Returns: real JAX array (N_K,)
otm_prices_to_ivs ¶
otm_prices_to_ivs(
raw_otm_prices: ndarray,
K: ndarray,
maturity: float,
S_0: float,
call_mask: ndarray,
put_mask: ndarray,
r: float = 0.0,
) -> np.ndarray
Invert a vector of OTM option prices to Black-Scholes implied vols.
Strikes in call_mask are treated as calls, those in put_mask as puts.
The two masks must partition K (no overlap, no gap).
adaptive_check_values ¶
adaptive_check_values(
result: ndarray,
raw_otm_prices: ndarray,
call_mask: ndarray,
put_mask: ndarray,
implied_vol: bool,
adaptive_metric: str,
K: ndarray,
maturity: float,
S_0: float,
r: float = 0.0,
scalar_H: bool = True,
) -> np.ndarray
Extract a flat array of convergence-check values from a fixed-panel result.
Used to compare successive adaptive-panel iterations. Returns raw OTM prices
when adaptive_metric='price', and implied vols when adaptive_metric='iv'
(inverting prices if the result is not already in IV space).
scalar_H=False signals that raw_otm_prices has shape (N_K, N_H)
and each H-slice is inverted independently.
adaptive_converged ¶
adaptive_converged(
prev_check: ndarray,
check: ndarray,
metric: str,
tol: float,
abs_tol: float,
rel_tol: float,
) -> bool
Return True when successive adaptive-panel check values are within tolerance.
For metric='iv' a single absolute tolerance tol is applied.
For metric='price' a combined absolute + relative criterion is used.