Pricer

Bonds

class rivapy.pricing.bond_pricing.DeterministicCashflowPricer(val_date: datetime, spec: DeterministicCashflowBondSpecification, discount_curve: DiscountCurve, fwd_curve: DiscountCurve | None = None)[source]

Bases: object

Deterministic cashflow pricer utilities.

This class provides static and instance helpers for pricing deterministic cashflow instruments (fixed- and floating-rate bonds, deposits, zero-coupon instruments). It contains methods to generate expected cashflows, discount them, compute PVs, yields, z-spreads and duration measures.

Initialize the DeterministicCashflowPricer.

Parameters:

  • val_date (datetime) – The valuation date.

  • spec (DeterministicCashflowBondSpecification) – The specification of the cashflow instrument.

  • discount_curve (DiscountCurve) – The discount curve to use for pricing.

  • fwd_curve (Union[DiscountCurve, None], optional) – The forward curve to use for pricing. Defaults to None.

property cashflows: List[Tuple[datetime, float]]

Get the cashflows of the instrument.

Returns:

The cashflows of the instrument.

Return type:

Cashflow

clean_price() → float[source]

Get the clean price of the bond.

Returns:

The clean price of the bond.

Return type:

float

compute_yield(target_dirty_price: float) → float[source]

Compute the yield of the bond.

Parameters:

target_dirty_price (float) – The target dirty price.

Returns:

The computed yield.

Return type:

float

dirty_price() → float[source]

Get the dirty price of the bond.

Returns:

The dirty price of the bond.

Return type:

float

expected_cashflows() → List[Tuple[datetime, float]][source]

Get the expected cashflows of the instrument.

Returns:

The expected cashflows of the instrument.

Return type:

List[Tuple[datetime, float]]

static get_accrued_interest(specification: DeterministicCashflowBondSpecification, trade_date: date | datetime | None = None, fwd_curve: DiscountCurve | None = None) → float[source]

Get the accrued interest for a given instrument specification.

Parameters:

  • specification (DeterministicCashflowBondSpecification) – The bond specification.

  • val_date (datetime.date or datetime, optional) – The valuation date. Defaults to None.

Returns:

The accrued interest.

Return type:

float

static get_compute_yield(target_dirty_price: float, val_date: datetime, specification: DeterministicCashflowBondSpecification, cashflows: List[Tuple[datetime, float]] | None = None, fwd_curve: DiscountCurve | None = None) → float[source]
static get_dirty_price(val_date: datetime, specification: DeterministicCashflowBondSpecification, discount_curve: DiscountCurve, fwd_curve: DiscountCurve | None = None) → float[source]

Compute the dirty price (present value including accrued interest) of a bond.

Parameters:

  • val_date (date | datetime) – Valuation date.

  • specification (DeterministicCashflowBondSpecification) – Instrument specification.

  • discount_curve (DiscountCurve) – Curve used for discounting.

  • fwd_curve (DiscountCurve, optional) – Forward curve for floating-rate cashflows.

Returns:

Dirty price (PV of future cashflows after val_date).

Return type:

float

static get_expected_cashflows(spec: ~rivapy.instruments.bond_specifications.DeterministicCashflowBondSpecification, val_date: ~.datetime.date | ~datetime.datetime | None = None, fwd_curve: ~rivapy.marketdata.curves.DiscountCurve | None = None) → List[Tuple[datetime, float]][source]

Calculate the expected cashflows for a deterministic cashflow instrument.

Parameters:

  • spec (DeterministicCashflowBondSpecification) – The instrument specification containing schedule, notional, coupon type, etc.

  • val_date (datetime.date or datetime, optional) – The valuation date, required for floating rate calculation. Defaults to None.

  • curve (DiscountCurve, optional) – The forward curve used for floating rate calculation. Defaults to None.

Returns:

A sorted list of tuples, each containing the payment date and cashflow amount.

Return type:

List[Tuple[datetime, float]]

static get_float_rate(specification: ~rivapy.instruments.bond_specifications.DeterministicCashflowBondSpecification, val_date: ~.datetime.date | ~datetime.datetime | None = None, d1: ~.datetime.date | ~datetime.datetime | None = None, d2: ~.datetime.date | ~datetime.datetime | None = None, curve: ~rivapy.marketdata.curves.DiscountCurve | None = None) → float[source]

Get the floating rate for a given period.

Parameters:

  • specification (DeterministicCashflowBondSpecification) – The bond or instrument specification containing index, margin, calendar, and conventions.

  • val_date (datetime.date or datetime, optional) – The valuation date as of which forward rates are calculated. Defaults to None.

  • d1 (datetime.date or datetime, optional) – The start date of the interest period. Defaults to None.

  • d2 (datetime.date or datetime, optional) – The end date of the interest period. Defaults to None.

  • curve (DiscountCurve, optional) – The forward curve used for forward rate calculation. Defaults to None.

Returns:

The floating rate for the given period, including margin.

Return type:

float

static get_pv_cashflows(val_date: datetime, specification: DeterministicCashflowBondSpecification, discount_curve: DiscountCurve, fwd_curve: DiscountCurve | None = None, cashflows: List[Tuple[datetime, float]] | None = None) → float[source]

Discount and sum cashflows to obtain present value.

Parameters:

  • val_date (date | datetime) – Valuation date used for discounting.

  • specification (DeterministicCashflowBondSpecification) – Instrument specification.

  • discount_curve (DiscountCurve) – Curve used to obtain discount factors.

  • fwd_curve (DiscountCurve, optional) – Forward curve used for floating-rate cashflows.

  • cashflows (List[(date, amount)], optional) – Precomputed cashflows; if not provided they will be generated from the specification.

Returns:

Present value obtained by discounting future cashflows occurring after val_date.

Return type:

float

static get_z_spread(target_dirty_price: float, val_date: datetime, specification: DeterministicCashflowBondSpecification, discount_curve: DiscountCurve, cashflows: List[Tuple[datetime, float]] | None = None, fwd_curve: DiscountCurve | None = None) → float[source]
macaulay_duration() → float[source]

Compute the Macaulay duration for the instrument.

Macaulay duration is the weighted average time until cashflows are received, weighted by the present value of the cashflows.

Returns:

Macaulay duration expressed in the same time units used by day count.

Return type:

float

modified_duration(target_dirty_price: float = 100.0) → float[source]

Compute the modified duration for the instrument.

Modified duration approximates the percentage price change for a unit change in yield and is computed from the Macaulay duration and yield.

Parameters:

target_dirty_price (float, optional) – Dirty price used for yield inversion. Defaults to 100.0.

Returns:

Modified duration.

Return type:

float

pv_cashflows() → float[source]

Get the present value of the cashflows.

Returns:

The present value of the cashflows.

Return type:

float

z_spread(target_dirty_price: float) → float[source]

Compute the z-spread of the bond.

Parameters:

target_dirty_price (float) – The target dirty price.

Returns:

The computed z-spread.

Return type:

float

Forward Rate Agreement

class rivapy.pricing.fra_pricing.ForwardRateAgreementPricer(val_date: date | datetime, fra_spec: ForwardRateAgreementSpecification, discount_curve: DiscountCurve, forward_curve: DiscountCurve = None)[source]

Bases: object

Initializes the FRA pricer with valuation date, FRA specification, discount curve and forward curve.

Parameters:

  • val_date (_Union[date, datetime]) – specific date for which the value of the financial instrument is calculated.

  • fra_spec (ForwardRateAgreementSpecification) – Specification object with FRA specific parameters.

  • discount_curve (DiscountCurve) – Discount curve used for discounting.

  • forward_curve() – from underlying index…

static compute_fair_rate(val_date: datetime | date, specification: ForwardRateAgreementSpecification, discount_curve: DiscountCurve)[source]

Computes the fair rate such that the when used in the specification of the FRA gives a net value of zero. A discount curve is given, from which the Forward Rate is determined between the two dates. Assuming simple compounding Forward rate = (DF_1/DF_2 -1 )/ time_interval

= (1 /FWD_DF -1 )/ time_interval

Parameters:

  • val_date (_Union[datetime, date]) – specific date as of which the value of the financial instrument is calculated.

  • forward_curve (DiscountCurve) – Forward curve used for projecting rates

  • rate_start_date (_Union[datetime, date]) – start date for the forward period

  • rate_end_date (_Union[datetime, date]) – end date for the forward period

Returns:

_description_

Return type:

float

expected_cashflows()[source]

Calculate expected cashflows for the FRA specification.

Returns:

List of tuples containing payment dates and amounts.

Return type:

List[Tuple[datetime, float]]

static get_expected_cashflows(specification: ~rivapy.instruments.fra_specifications.ForwardRateAgreementSpecification, val_date: ~.datetime.date | ~datetime.datetime, fwdcurve: ~rivapy.marketdata.curves.DiscountCurve) → List[Tuple[datetime, float]][source]

Calculate expected cashflows for the FRA specification based on the valuation date and discount curve.

Parameters:

  • specification (ForwardRateAgreementSpecification) – The FRA specification.

  • val_date (_Union[datetime.date, datetime]) – The data as of which the cashflows are calculated.

  • fwdcurve (_Union[DiscountCurve, None]) – The forward curve.

Returns:

List of tuples containing payment dates and amounts.

Return type:

List[Tuple[datetime, float]]

static get_price(val_date: ~.datetime.date | ~datetime.datetime, specification: ~rivapy.instruments.fra_specifications.ForwardRateAgreementSpecification, discount_curve: ~rivapy.marketdata.curves.DiscountCurve, forward_curve: ~rivapy.marketdata.curves.DiscountCurve | None = None) → float[source]

Calculate the present value of the specified FRA given a discount curve and forward curve

Parameters:
Returns:

The present value of the FRA.

Return type:

float

price()[source]

Calculate the present value of the specified FRA given a discount curve and forward curve

Returns:

present value of a deposit based on simple compounding

Return type:

float

Deposits

class rivapy.pricing.deposit_pricing.DepositPricer(val_date: date | datetime, deposit_spec: DepositSpecification, discount_curve: DiscountCurve)[source]

Bases: DeterministicCashflowPricer

Create a pricer for a deposit instrument.

Parameters:

  • val_date (date | datetime) – Valuation date used for pricing.

  • deposit_spec (DepositSpecification) – Deposit specification containing schedule and contractual parameters.

  • discount_curve (DiscountCurve) – Discount curve used for discounting cashflows.

expected_cashflows() → List[Tuple[datetime, float]][source]

Return expected cashflows for the configured deposit and valuation date.

Returns:

List of (pay_date, amount) tuples.

Return type:

List[Tuple[datetime, float]]

static get_expected_cashflows(specification: ~rivapy.instruments.deposit_specifications.DepositSpecification, val_date: ~.datetime.date | ~datetime.datetime | None = None) → List[Tuple[datetime, float]][source]

Static helper: get expected cashflows for a deposit specification.

Parameters:

  • specification (DepositSpecification) – The deposit specification.

  • val_date (date | datetime, optional) – Valuation date to use. If None, the specification’s default behavior is used.

Returns:

List of (pay_date, amount) tuples.

Return type:

List[Tuple[datetime, float]]

static get_implied_simply_compounded_rate(val_date: datetime, specification: DepositSpecification, discount_curve: DiscountCurve) → float[source]

Compute the implied simply compounded rate that sets deposit PV to zero.

The implementation assumes simple compounding: D(t) = 1 / (1 + rate * dt).

Parameters:

  • val_date (date | datetime) – Valuation date.

  • specification (DepositSpecification) – Deposit specification with start/end dates and day count convention.

  • discount_curve (DiscountCurve) – Discount curve used to obtain forward discount factor between start and end.

Returns:

The implied simply compounded rate.

Return type:

float

Raises:

ValueError – If discount_curve is not an instance of DiscountCurve.

static get_price(val_date: datetime, specification: DepositSpecification, discount_curve: DiscountCurve) → float[source]

Calculate present value of a deposit using the provided discount curve.

Parameters:

  • val_date (date | datetime) – Valuation date.

  • specification (DepositSpecification) – Deposit contract specification.

  • discount_curve (DiscountCurve) – Discount curve used for discounting.

Returns:

Present value (PV) computed from discounted expected cashflows.

Return type:

float

implied_simply_compounded_rate() → float[source]

Return the implied simply compounded rate for the configured deposit.

The implied simply compounded rate is the rate that makes the deposit’s PV equal to zero under a simple-compounding assumption.

Returns:

Implied simply compounded rate.

Return type:

float

price() → float[source]

Return the present value of the configured deposit using the provided curves.

Returns:

Present value.

Return type:

float

Interest Rate Swap

class rivapy.pricing.interest_rate_swap_pricing.InterestRateSwapPricer(val_date: date | datetime, spec: InterestRateSwapSpecification, discount_curve_pay_leg: DiscountCurve, discount_curve_receive_leg: DiscountCurve, fixing_curve_pay_leg: DiscountCurve, fixing_curve_receive_leg: DiscountCurve, fx_fwd_curve_pay_leg: DiscountCurve, fx_fwd_curve_receive_leg: DiscountCurve, pricing_request: InterestRateSwapPricingRequest, pricing_param: Dict = None, fixing_map: FixingTable = None, fx_pay_leg: float = 1.0, fx_receive_leg: float = 1.0)[source]

Bases: object

Initializes the Interest Rate Swap Pricer with all required curves, specifications, and parameters.

Parameters:

  • val_date (date | datetime) – The valuation date for pricing the swap. This is the anchor date for all time-dependent calculations.

  • spec (InterestRateSwapSpecification) – The swap’s structural details (legs, notionals, schedules, etc.).

  • discount_curve_pay_leg (DiscountCurve) – Discount curve used to present value the pay leg.

  • discount_curve_receive_leg (DiscountCurve) – Discount curve used to present value the receive leg.

  • fixing_curve_pay_leg (DiscountCurve) – Curve used to forecast forward rates for the pay leg (typically for floating legs).

  • fixing_curve_receive_leg (DiscountCurve) – Curve used to forecast forward rates for the receive leg.

  • fx_fwd_curve_pay_leg (DiscountCurve) – FX forward curve to convert the pay leg currency to the pricing currency (if applicable).

  • fx_fwd_curve_receive_leg (DiscountCurve) – FX forward curve to convert the receive leg currency to the pricing currency.

  • pricing_request (InterestRateSwapPricingRequest) – Contains the pricing type, metrics requested (e.g., PV), and other flags. Not yet used properly

  • pricing_param (Dict, optional) – Additional pricing parameters, such as day count conventions, compounding rules, etc.

  • fixing_map (FixingTable, optional) – Historical fixings for floating legs that reference past periods.

  • fx_pay_leg (float, optional) – FX rate multiplier to convert the pay leg currency to base. Default is 1.0 (i.e., same currency).

  • fx_receive_leg (float, optional) – FX rate multiplier to convert the receive leg currency to base. Default is 1.0.

static compute_basis_spread(ref_date: date | datetime, discount_curve: DiscountCurve, payLegFixingCurve: DiscountCurve, receiveLegFixingCurve: DiscountCurve, pay_leg: IrFloatLegSpecification, receive_leg: IrFloatLegSpecification, spread_leg: IrFixedLegSpecification, fixing_map: FixingTable = None, pricing_params: dict = {'fixing_grace_period': 0.0}) → float[source]
static compute_swap_rate(ref_date: date | datetime, discount_curve: DiscountCurve, fixing_curve: DiscountCurve, float_leg: IrFloatLegSpecification, fixed_leg: IrFixedLegSpecification, fixing_map: FixingTable = None, pricing_params: dict = {'fixing_grace_period': 0.0}) → float[source]
To calculate the fair swap rate, i.e. the fixed rate(r*) such that

PV_fixed(r*) = PV_float

where

PV_fixed(r*) = r* * Annuity

where

Annuity = sum(notional_i * DF_i * YF_i*)

Fast path for OIS floating leg: use analytical OIS formula so we do not simulate daily compounding each time inside the solver.

Parameters:

  • ref_date (_Union[date, datetime]) – reference date

  • discount_curve (DiscountCurve) – discoutn curve to determine present value

  • fixing_curve (DiscountCurve) – curve used for fwd rates for the floating leg

  • float_leg (IrFloatLegSpecification) – IR swap float leg specification

  • fixed_leg (IrFixedLegSpecification) – IR swap fix leg specification

  • fixing_map (FixingTable, optional) – historical fixing data (TODO). Defaults to None.

  • fixing_grace_period (int, optional) – . Defaults to 0.

Returns:

fair rate for the swap

Return type:

float

static compute_swap_rate_ois_analytical(ref_date: datetime, discount_curve: DiscountCurve, forward_curve: DiscountCurve, float_leg: IrOISLegSpecification, fixed_leg: IrFixedLegSpecification) → float[source]

Computes the fair (par) fixed rate for an Overnight Indexed Swap (OIS) using an analytical shortcut based on discount factors.

This method assumes that the floating leg is a compounded overnight leg and that, under standard OIS discounting, the present value of the floating leg can be derived directly from the discount curve without simulating daily compounding. Much faster than simulating daily compounding for each. [https://btrm.org/wp-content/uploads/2024/03/BTRM-WP15_SOFR-OIS-Curve-Construction_Dec-2020.pdf]

The par OIS rate is computed as:

R = (sum_i N_i * [P(T_i) - P(T_{i+1})]) / (sum_i N_i * alpha_i * P(T_{i+1}))

where:

  • P(T_i): discount factor at period start/end,

  • alpha_i: accrual year fraction on the fixed leg,

  • N_i: notional applicable for that period.

Assumptions:

  • The floating leg is fully collateralized and discounted on the same OIS curve.

  • The compounded overnight rate is implied by the discount factors.

  • No spread, lag, or convexity correction is applied.

  • Notionals and accrual conventions are consistent with the given curves.

  • Forward curve is used only for projected notionals or FX conversions, not for rate projection.

  • The fixed leg is currently not explictily used as it assumes that it has the same notional structure and payment dates as the floating leg, which usually the case.

Raises:

ValueError – If the computed annuity (denominator) is zero, indicating invalid leg setup or inconsistent inputs.

Returns:

The par fixed rate that equates PV_fixed = PV_float (analytical) (as a decimal, e.g. 0.025 for 2.5%).

Return type:

float

compute_swap_spread()[source]
price()[source]

price a full swap, with a pay leg and a receive leg in the context of pricing container and pricer having been initlialized with required inputs.

static price_leg(val_date, discount_curve: DiscountCurve, forward_curve: DiscountCurve, fxForward_curve: DiscountCurve, spec: IrFixedLegSpecification | IrFloatLegSpecification, fixing_map: FixingTable = None, fixing_grace_period: float = 0, pricing_params: dict = {'desired_rate': 1.0, 'set_rate': False})[source]

Price a leg of a IR swap making distinctions for floating and fixed legs as well as OIS legs.

Parameters:

  • val_date (_type_) – Valuation date

  • discount_curve (DiscountCurve) – discount curve for discounting cashflows

  • forward_curve (DiscountCurve) – forward curve for the forward rate calculations

  • fxForward_curve (DiscountCurve) – fx forward curve for currency conversions for applicable instruments (not yet implemented)

  • spec (_Union[IrFixedLegSpecification, IrFloatLegSpecification]) – Specification object for the leg to be priced

  • fixing_map (FixingTable, optional) – Historical fixing data (not yet implemented). Defaults to None.

  • fixing_grace_period (float, optional) – . Defaults to 0.

  • pricing_params (_type_, optional) – Additional parameters needed for swap pricing. Defaults to {“set_rate”: False, “desired_rate”: 1.0}.

Raises:

ValueError – if unknown leg type is passed

Returns:

return the aggregated Present value of the leg of the swap.

Return type:

float

static price_leg_pricing_data(val_date, pricing_data: InterestRateSwapLegPricingData_rivapy, param)[source]

Pricing a single Leg using Pricing Data architecture (not yet fully integrated, to be done once architecture clarified)

Parameters:

  • val_date (_type_) – _description_

  • pricing_data (InterestRateSwapLegPricingData) – float leg or base leg pricing data …

  • param (_type_) – extra parameters (not yet used)

Raises:

ValueError – _description_

Returns:

_description_

Return type:

_type_