Curves-first API¶
Explicit market structure
The curves-first interface makes discounting and forwards explicit. All pricers in this style accept a PricingContext plus tau (time to expiry).
Use this layer when the market container should stay explicit instead of being flattened into convenience inputs.
Context and curves¶
These are the core market-context objects behind the curves-first pricing path.
PricingContext
dataclass
¶
Container for market term structures used by pricers.
Attributes:
| Name | Type | Description |
|---|---|---|
spot |
float
|
Spot price at valuation. |
discount |
DiscountCurve
|
Discount curve providing df(tau). |
forward |
ForwardCurve
|
Forward curve providing fwd(tau). |
Notes
- Internal convention: pricers operate on tau (time-to-expiry).
- This context is curves-first. Engines that require scalars (e.g. CRR trees, constant-coefficient BS PDE) can use r_avg/q_avg/b_avg methods.
df ¶
df(tau: float) -> float
Discount factor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tau
|
float
|
Time to expiry. |
required |
Returns:
| Type | Description |
|---|---|
float
|
Discount factor P(tau) from the discount curve. |
fwd ¶
fwd(tau: float) -> float
Forward price.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tau
|
float
|
Time to expiry. |
required |
Returns:
| Type | Description |
|---|---|
float
|
Forward price F(tau) from the forward curve. |
prepaid_forward ¶
prepaid_forward(tau: float) -> float
Prepaid forward: Fp(tau) = df(tau) * fwd(tau).
q_avg ¶
q_avg(tau: float) -> float
Average dividend yield / foreign rate / carry yield over [0, tau].
df_q ¶
df_q(tau: float) -> float
Implied 'dividend discount factor' over [0, tau].
Under deterministic carry, prepaid forward satisfies: Fp(tau) = S0 * exp(-∫ q dt) so: df_q(tau) = exp(-q_avg(tau)*tau) = Fp(tau)/S0
DiscountCurve ¶
Bases: Protocol
Discount curve protocol (curves-first).
Internal convention is time-to-expiry (tau).
Implementations must return the discount factor for a cashflow paid at tau:
df(tau) = P(0, tau).
ForwardCurve ¶
Bases: Protocol
Forward curve protocol (curves-first).
Implementations must return the forward price for delivery at maturity tau:
fwd(tau) = F(0, tau).
Notes
- For equity with continuous dividend yield q and flat r: F(0, tau) = S0 * exp((r-q) * tau)
- Some legacy code uses a forward(T, t=0) signature. That alias is modeled separately (see LegacyForwardCurve) to avoid forcing every implementation to carry legacy API.
FlatDiscountCurve
dataclass
¶
Flat (continuously-compounded) discount curve: df(tau)=exp(-r*tau).
df ¶
df(tau: float) -> float
Discount factor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tau
|
float
|
Time to expiry. |
required |
Returns:
| Type | Description |
|---|---|
float
|
Discount factor P(tau) = exp(-r*tau). |
Raises:
| Type | Description |
|---|---|
ValueError
|
If tau < 0. |
FlatCarryForwardCurve
dataclass
¶
Forward curve with constant (continuous) carry.
Uses the cost-of-carry relationship:
F(0,tau) = S0 * exp((r - q) * tau)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
spot
|
float
|
Spot price at valuation. |
required |
r
|
float
|
Continuously-compounded risk-free rate. |
required |
q
|
float
|
Continuously-compounded dividend yield / foreign rate / carry yield. |
0.0
|
fwd ¶
fwd(tau: float) -> float
Forward price.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tau
|
float
|
Time to expiry. |
required |
Returns:
| Type | Description |
|---|---|
float
|
Forward price F(tau) = S0 * exp((r - q) * tau). |
Raises:
| Type | Description |
|---|---|
ValueError
|
If tau < 0 or spot <= 0. |
forward ¶
forward(T: float, t: float = 0.0) -> float
Forward price (legacy alias).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
T
|
float
|
Maturity time. |
required |
t
|
float
|
Valuation time (default: 0.0). |
0.0
|
Returns:
| Type | Description |
|---|---|
float
|
Forward price for delivery at T. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If T < t. |
Notes¶
PricingContext.df(tau)returns the discount factor to maturitytau.PricingContext.fwd(tau)returns the forward price for maturitytau.MarketData.to_context()is the bridge from the flat convenience API into this one.