feat: add macaulay duration algorithm

Author: max-klingner

financial/macaulay_duration.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+def macaulay_duration(
+    face_value: float,
+    coupon_rate: float,
+    periods: int,
+    yield_rate: float
+) -> float:
+    """
+    Calculates the Macaulay Duration of a bond.
+
+    Reference:
+    https://www.investopedia.com/terms/m/macaulayduration.asp
+
+    Args:
+        face_value: The final payout amount of the bond.
+        coupon_rate: The annual interest rate paid by the bond.
+        periods: The number of years until the bond matures.
+        yield_rate: The current market interest rate used to discount future cash flows.
+
+    Returns:
+        The Macaulay Duration of the bond in years.
+
+    >>> round(macaulay_duration(1000.0, 0.05, 8, 0.04), 2)
+    6.83
+    >>> round(macaulay_duration(987435.34, 0.07, 5, 0.038), 2)
+    4.43
+    >>> round(macaulay_duration(3564.2, 0.023, 6, 0.071), 2)
+    5.62
+    >>> macaulay_duration(-1000.0, 0.05, 8, 0.04)
+    Traceback (most recent call last):
+        ...
+    ValueError: face_value must be > 0
+    >>> macaulay_duration(1000.0, -0.05, 8, 0.04)
+    Traceback (most recent call last):
+        ...
+    ValueError: coupon_rate must be >= 0
+    >>> macaulay_duration(1000.0, 0.05, 0, 0.04)
+    Traceback (most recent call last):
+        ...
+    ValueError: periods must be > 0
+    >>> macaulay_duration(1000.0, 0.05, 8, -0.04)
+    Traceback (most recent call last):
+        ...
+    ValueError: yield_rate must be > 0
+    """
+    if face_value <= 0:
+        raise ValueError("face_value must be > 0")
+    if coupon_rate < 0:
+        raise ValueError("coupon_rate must be >= 0")
+    if periods < 1:
+        raise ValueError("periods must be > 0")
+    if yield_rate <= 0:
+        raise ValueError("yield_rate must be > 0")
+
+    total_present_value: float = 0.0
+    total_time_weighted_value: float = 0.0
+
+    for period in range(1, periods + 1):
+        cash_flow: float = (face_value * coupon_rate) + (face_value if period == periods else 0)
+
+        time_weighted_value: float = (period * cash_flow) / pow(1 + yield_rate, period)
+        total_time_weighted_value += time_weighted_value
+
+        present_value: float = cash_flow / pow(1 + yield_rate, period)
+        total_present_value += present_value
+
+    return total_time_weighted_value / total_present_value
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()