convex-yield-conventions
Bond yield convention implementation for the Convex pricing library. Use this skill when:(1) Implementing yield calculation methods (compounded, simple, discount, add-on)(2) Adding money market yield calculations with sequential roll-forward(3) Implementing Bond Equivalent Yield (BEY) with 182-day threshold(4) Creating market presets for bond creation and validation(5) Implementing compounding frequency conversions(6) Extending bond pricing to support global market conventions
When & Why to Use This Skill
The Convex Yield Conventions skill is a specialized financial engineering tool designed for developers building fixed-income pricing engines. It provides a comprehensive framework for implementing diverse bond yield calculation methods—including compounded, simple, discount, and add-on yields—while strictly adhering to global market conventions. By separating concerns between bond data and yield logic, it enables the creation of robust, scalable financial libraries that support international standards like US Treasury, UK Gilt, and Japanese JGB presets.
Use Cases
- Case 1: Implementing standardized yield-to-price calculation methods (Compounded, Simple, Discount, Add-on) within a Rust-based financial library.
- Case 2: Automating the application of global market day-count conventions and settlement rules for bond validation and pricing.
- Case 3: Configuring money market instruments with specific thresholds (e.g., 182-day BEY) and sequential roll-forward yield logic.
- Case 4: Developing market-specific presets for various sovereign and corporate bonds to ensure consistency across financial modeling platforms.
- Case 5: Executing precise compounding frequency conversions to compare rates across different financial instruments and jurisdictions.
| name | convex-yield-conventions |
|---|---|
| description | | |
Convex Yield Conventions Skill
Extends the Convex bond pricing library with generic yield conventions.
Core Principle: Separation of Concerns
Bond → Owns: day_count, frequency, settlement rules
YieldMethod → Controls: how to calculate yield from price
MarketPreset → Provides: defaults for bond creation, validation
The bond is the source of truth for its conventions. YieldConvention does NOT override the bond's day count or frequency.
Architecture
convex-core/src/
├── types/
│ └── yield_method.rs # YieldMethod enum only
└── compounding/
├── frequency.rs # CompoundingFrequency enum
└── converter.rs # Rate conversion utilities
convex-bonds/src/
├── traits.rs # Bond trait (owns day_count, frequency)
├── instruments/
│ └── fixed.rs # FixedRateBond with conventions
└── pricing/
└── yield_calculator.rs # Uses bond's conventions
convex-yas/src/
└── presets.rs # MarketPreset for validation/defaults
Core Types
YieldMethod (calculation approach only)
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum YieldMethod {
/// Newton-Raphson: Price = Σ CF/(1+y/f)^(f×t)
Compounded,
/// y = (Coupon + (Redemption-Price)/Years) / Price
Simple,
/// y = (Face-Price)/Face × (Basis/Days) - T-Bills
Discount,
/// y = (Face-Price)/Price × (Basis/Days) - Money market
AddOn,
}
YieldCalculatorConfig (minimal)
pub struct YieldCalculatorConfig {
/// Primary calculation method
pub method: YieldMethod,
/// Days threshold for money market switch (typically 182)
pub money_market_threshold: Option<u32>,
/// Solver tolerance (default: 1e-10)
pub tolerance: f64,
}
Bond Trait (owns conventions)
pub trait Bond {
fn day_count(&self) -> &dyn DayCount;
fn coupon_frequency(&self) -> Frequency;
fn coupon_rate(&self) -> Decimal;
fn maturity(&self) -> Date;
fn face_value(&self) -> Decimal;
fn cash_flows_from(&self, settlement: Date) -> Vec<CashFlow>;
fn accrued_interest(&self, settlement: Date) -> Decimal;
}
MarketPreset (for creation & validation)
pub struct MarketPreset {
pub name: &'static str,
pub day_count: DayCountConvention,
pub frequency: Frequency,
pub settlement_days: u32,
pub yield_method: YieldMethod,
pub money_market_threshold: Option<u32>,
}
impl MarketPreset {
/// Validate bond matches this market's conventions
pub fn validate<B: Bond>(&self, bond: &B) -> Result<(), ConventionMismatch>;
/// Get yield calculator config for this market
pub fn yield_config(&self) -> YieldCalculatorConfig;
}
Market Presets
| Preset | Day Count | Frequency | Settle | MM Threshold |
|---|---|---|---|---|
US_TREASURY |
ACT/ACT ICMA | Semi | T+1 | 182 |
US_CORPORATE |
30/360 US | Semi | T+2 | 182 |
US_TBILL |
ACT/360 | - | T+1 | - |
UK_GILT |
ACT/ACT ICMA | Semi | T+1 | - |
GERMAN_BUND |
ACT/ACT ICMA | Annual | T+2 | - |
JAPANESE_JGB |
ACT/365F | Semi | T+2 | - |
Yield Calculator Flow
impl YieldCalculator {
pub fn yield_from_price<B: Bond>(
&self,
bond: &B,
settlement: Date,
price: CleanPrice,
) -> Result<Yield, YieldError> {
// 1. Get conventions FROM THE BOND
let day_count = bond.day_count();
let frequency = bond.coupon_frequency();
// 2. Determine method (config only controls this)
let days_to_mat = (bond.maturity() - settlement).num_days() as u32;
let method = self.effective_method(days_to_mat);
// 3. Calculate using bond's conventions
match method {
YieldMethod::Compounded => {
self.solve_compounded(bond, settlement, price, day_count, frequency)
}
YieldMethod::Simple => {
self.calc_simple(bond, settlement, price, day_count)
}
YieldMethod::AddOn => {
self.calc_money_market(bond, settlement, price, day_count)
}
// ...
}
}
}
Key Thresholds
182 days - Money market method switch for US markets 365 days - Money market threshold for Canadian markets
Sequential Roll-Forward (for short-dated coupon bonds)
C₁ = C × (1 + y × D₁/basis)
Cᵢ = (C + Cᵢ₋₁) × (1 + y × Dᵢ/basis)
Where basis comes from the bond's day count convention.
Reference Files
references/formulas.md- Mathematical formulasreferences/market-conventions.md- Market specificationsreferences/test-cases.md- Bloomberg validation tests