Skip to content

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" when H₀ = ½, 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. param.H is used as the expansion anchor H₀.

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" selects "exact_heston" when param.H == 0.5, otherwise "direct_riccati" with the implicit-π solver, the most stable and accurate choice; "root_pade" is faster. The approximate bases warn at param.H == 0.5, where "exact_heston" is exact.

"auto"
pade_order (22, 33, 44)

Padé order; only used when base_solution="pade".

"22"
root_pade_series_order int or None

Number of short-time series coefficients for the root-Padé solve; None defaults to 2 * root_pade_degree + 1.

None
root_pade_degree int

Numerator degree m of the [m/(m+1)] root-Padé approximant (default 9; Hager & Kreher 2026 use 7).

9
root_pade_tail_match bool

If True (the default), replace the highest short-time Padé equation with the exact leading 1/x tail constraint. This is much more accurate for H < 0 and for steep skews.

True
direct_riccati_solver (auto, adams, implicit_pi)

Fractional ODE solver when base_solution="direct_riccati". "auto" selects "implicit_pi". "adams" is opt-in and requires a uniform time grid.

"auto"
log_cf_integrand (auto, solution, rhs)

What the log characteristic function integrates over [0, T]. "solution" integrates the Riccati solution h: θ·I¹h(T) + V0·I^(1-α)h(T) (El Euch & Rosenbaum 2019). "rhs" integrates the Riccati right-hand side F(h): ∫ F(h(s)) (V0 + θ (T-s)^α / Γ(1+α)) ds, the formula of Hager & Kreher (2026), Eq. (1.1), which the paper's numbers use (see "Reproducing the paper" in the README for the other settings). Both are exact for the exact h. "rhs" equals "solution" after one fixed-point step with the target kernel: that restores the target's short-time behaviour t^α, which the H-expansion carries only through powers of ΔH·log t, but amplifies the error of an approximate h by about ν|u|. "auto" (the default) uses "rhs" for expansions from the anchor H₀ = ½, where it is the more accurate of the two in tests, and "solution" otherwise.

"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 returns call prices, False put prices. With payoff_selection="otm" the out-of-the-money option is priced at each strike and converted by put–call parity; implied vols do not depend on call.

True
digital bool

Price digital (cash-or-nothing) payoffs instead of vanilla.

False
implied_vol bool

If True, return Black–Scholes implied volatilities instead of option prices. Vanillas only.

False
payoff_selection (otm, as_requested)

"otm" prices calls for K ≥ F and puts for K < F, then applies put–call parity. "as_requested" uses call for all strikes.

"otm"
R float

Fourier contour height. The default R = 0.5 prices every strike as a call and converts to puts by parity; for vanillas this is the Lewis contour. It needs only E[S_T^0.5], which is always finite. Other values use damped contours at +|R| for calls and -|R| for puts, which need E[S_T^|R|] and E[S_T^-|R|] to be finite. Below |R| = 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), and R = 0 runs through the pole at 0, which adds half of its residue. Near a pole the integrand has a peak of width |R - pole| at u = 0, which the panels resolve at 1e-2 from the pole (prices off by 4e-9) but not at 1e-3 (up to 2e-3 S_0); on the pole they are accurate.

0.5
L float or None

Upper truncation of the Fourier integral. None picks the point where |phi| has decayed to about 1e-10, from the model parameters, the maturity and every H priced (up to 256000).

None
panels array - like or None

Explicit Chebyshev panel breakpoints. Overrides L when given.

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 falls back to time_steps. With the exact-Heston base, phi0 at H = ½ is in closed form and does not use the grid.

None
expansion_order int

Taylor expansion order N in H around self.param.H.

0
time_steps int

Time-grid nodes for the expansion solve.

400
H float, array-like, or None

Target Hurst exponent(s). None or a scalar uses self.param.H or the given value and returns shape (N_K,). An array reuses the expensive Volterra fields across all H values and returns shape (N_K, N_H).

None
integration (panel, adaptive_panel)

"panel" uses fixed panels. "adaptive_panel" iteratively widens L until prices or implied vols stabilise.

"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".

"price"
adaptive_tol float

Tolerance of the "iv" criterion, in implied vol.

0.0001
adaptive_abs_tol float

Absolute and relative tolerances of the "price" criterion.

1e-08
adaptive_rel_tol float

Absolute and relative tolerances of the "price" criterion.

1e-08
adaptive_L_candidates list or None

Explicit sequence of L values to try. None starts at the default L and widens through the panel-template endpoints.

None
adaptive_max_iter int

Maximum number of adaptive refinement iterations. When no two successive L agree, the prices at the last are returned with a warning.

8
adaptive_verbose bool

Print convergence information at each adaptive step.

False
time_grid (uniform, graded, symmetric_graded)

Time-node distribution; see :meth:expansion_state.

"uniform"
grid_power float or None

Grading exponent; None auto-selects.

None
accuracy_check bool

If True (the default), estimate the approximation error and emit a UserWarning when it exceeds accuracy_tol at some strike. For expansion_order = N >= 1 the estimate is the change of the implied vols from order N to N+1 (the next term, computed along with the main pass) at the lowest and the highest target H. For the Padé bases away from H₀ = ½ it is the difference between the two log_cf_integrand formulas at the anchor, which is about the error of "rhs"; for root-Padé with "solution", which is several times more accurate, a third of it. The returned values do not change. Vanillas only; strikes whose out-of-the-money price is below 1e-6 S_0 are skipped. The check adds about 10–35 % run time; pass False in loops that do not need it.

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 (N_K,) for scalar H, or (N_K, N_H) when H is an array.

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 (N_u,).

required
maturity float

Option maturity T.

1.0
order int

Taylor expansion order in H around the anchor self.param.H.

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 → self.param.H. Passing an array evaluates all H values in a single Volterra solve.

None
time_grid (uniform, graded, symmetric_graded)

Time discretisation; see :meth:expansion_state.

"uniform"
grid_power float or None

Grading exponent; None auto-selects.

None

Returns:

Type Description
ndarray

Shape (N_u, N_H), one column per target H; N_H = 1 for a scalar or None H.

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 (N_u,). Typically -1j*(R - 1j*u) for a contour at height R.

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 [0, T].

400
H float or None

Target Hurst exponent for the expansion evaluation. None uses self.param.H (i.e. evaluates at the anchor itself).

None
return_lists bool

If True, populate HestonExpansionState.f_list and F_list with the individual coefficient fields f_n.

False
anchor float or None

Override the expansion anchor for this call only. None (default) uses self.param.H.

None
base str or None

Override self.base_solution for this call only.

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. "graded" clusters nodes near t = 0 (recommended for small anchors); "symmetric_graded" additionally clusters near t = T.

"uniform"
grid_power float or None

Grading exponent; None auto-selects via :func:suggested_time_grid_power.

None
direct_riccati_solver (auto, adams, implicit_pi)

Per-call override for the fractional ODE solver.

"auto"

Returns:

Type Description
HestonExpansionState

log_charfun_from_field

log_charfun_from_field(
    state: HestonExpansionState, field
) -> np.ndarray

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 (N_u,).

alpha float

Γ(anchor_H + ½) — the normalisation factor for the fractional kernel.

f0 Field

Base Riccati solution h(u, ·) at the expansion anchor, shape (N_u, N_t).

expansion Field

Taylor-summed approximation Σ_{n=0}^{N} (H-H₀)ⁿ/n! fₙ, same shape as f0.

F_ricc Callable

Unscaled Riccati right-hand side F_raw(x) = c - β x + ½γ x².

kappa_path Field

Conditional-mean path V0 + (θ/Γ(H+3/2)) t^(H+½), shape (N_t,).

kappa_path_reflected Field

Same path evaluated at T - t (used for the measure change).

f_list list[Field] or None

Expansion coefficients [f_0, f_1, …, f_N]; populated only when return_lists=True is passed to :meth:~RoughHeston.expansion_state.

F_list list[Field] or None

Corresponding Riccati RHS evaluations; populated alongside f_list.

target_H float or None

Hurst exponent at which expansion is evaluated.

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
               leading 1/x tail constraint p_m = C_exact * q_n, where
               C_exact = r_plus / (r_plus - r_minus) / Gamma(1 - alpha).
               At alpha = 1 C_exact = 0: E decays exponentially there, and
               a free 1/x tail would make the log-CF integral grow like log u.
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
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
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
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

solve

solve() -> 'Field'

Solve and return a Field with shape (n_u, J+1).

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 F(j, x, *F_args) -> x-shaped array.

required
F_args tuple

Arrays passed to F after (j, x).

()
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.