Interest Rate Swaps - Fundamentals › Building a Swap Cash Flow Calculator

from datetime import date

import pandas as pd
from dateutil.relativedelta import relativedelta


def generate_swap_schedule(
    notional: float,
    fixed_rate: float,
    start_date: date,
    maturity_years: int,
    floating_rates: list,
    fixed_frequency: str = "semi-annual",
    floating_frequency: str = "quarterly",
) -> pd.DataFrame:
    """
    Generate cash flow schedule for a pay-fixed, receive-floating swap.

    Parameters:
    -----------
    notional : float
        Notional principal amount
    fixed_rate : float
        Annual fixed rate (e.g., 0.04 for 4%)
    start_date : date
        Effective date of the swap
    maturity_years : int
        Number of years until maturity
    floating_rates : list
        Observed floating rates for each floating payment period
    fixed_frequency : str
        'semi-annual' or 'annual' for fixed leg
    floating_frequency : str
        'quarterly' or 'semi-annual' for floating leg

    Returns:
    --------
    pd.DataFrame with detailed cash flow schedule
    """
    # Determine number of periods
    if floating_frequency == "quarterly":
        float_periods = maturity_years * 4
        float_months = 3
    else:  # semi-annual
        float_periods = maturity_years * 2
        float_months = 6

    if fixed_frequency == "semi-annual":
        fixed_periods_per_year = 2
        fixed_months = 6
    else:  # annual
        fixed_periods_per_year = 1
        fixed_months = 12

    # Calculate day count fractions
    # Fixed: 30/360
    fixed_dcf = (30 * fixed_months) / 360
    fixed_payment = notional * fixed_rate * fixed_dcf

    # Build schedule
    schedule = []
    current_date = start_date

    for i in range(float_periods):
        period_end = current_date + relativedelta(months=float_months)
        actual_days = (period_end - current_date).days

        # Floating payment (Actual/360)
        float_dcf = actual_days / 360
        float_payment = notional * floating_rates[i] * float_dcf

        # Fixed payment (only on fixed payment dates)
        if (
            floating_frequency == "quarterly"
            and fixed_frequency == "semi-annual"
        ):
            # Fixed pays every 2 floating periods
            is_fixed_payment = (i + 1) % 2 == 0
        else:
            is_fixed_payment = True

        fixed_pay = fixed_payment if is_fixed_payment else 0
        net_cf = float_payment - fixed_pay

        schedule.append(
            {
                "Period": i + 1,
                "Start Date": current_date,
                "End Date": period_end,
                "Days": actual_days,
                "Floating Rate": floating_rates[i],
                "Floating DCF": float_dcf,
                "Floating Payment": float_payment,
                "Fixed Payment": fixed_pay,
                "Net Cash Flow": net_cf,
            }
        )

        current_date = period_end

    return pd.DataFrame(schedule)

# Example swap parameters
swap_notional = 100_000_000
swap_fixed = 0.0425
swap_start = date(2024, 3, 15)
swap_maturity = 3  # years

# Generate realistic floating rate path
np.random.seed(123)
initial_sofr = 0.0420
n_quarters = swap_maturity * 4

# Simple rate path with mean reversion
rates = [initial_sofr]
for _ in range(n_quarters - 1):
    # Mean-reverting process
    drift = 0.1 * (0.04 - rates[-1])  # Revert toward 4%
    shock = np.random.normal(0, 0.004)
    new_rate = max(0, rates[-1] + drift + shock)
    rates.append(new_rate)

# Generate the schedule
swap_schedule = generate_swap_schedule(
    notional=swap_notional,
    fixed_rate=swap_fixed,
    start_date=swap_start,
    maturity_years=swap_maturity,
    floating_rates=rates,
    fixed_frequency="semi-annual",
    floating_frequency="quarterly",
)