owlplanner 2025.12.5__py3-none-any.whl → 2026.1.26__py3-none-any.whl

owlplanner/socialsecurity.py

@@ -1,16 +1,23 @@
 """
+Social Security benefit calculation rules and utilities.
 
-Owl/socialsecurity
---------
+This module implements Social Security rules including full retirement age
+calculations, benefit computations, and related retirement planning functions.
 
-A retirement planner using linear programming optimization.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
-This file contains the rules related to social security.
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
 
-Copyright © 2025 - Martin-D. Lacasse
-
-Disclaimers: This code is for educational purposes only and does not constitute financial advice.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
 
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 import numpy as np
@@ -18,8 +25,23 @@ import numpy as np
 
 def getFRAs(yobs):
     """
-    Return full retirement age based on birth year.
-    Returns an array of fractional age.
+    Return full retirement age (FRA) based on birth year.
+
+    The FRA is determined by birth year according to Social Security rules:
+    - Birth year >= 1960: FRA is 67
+    - Birth year < 1960: FRA increases by 2 months for each year after 1954
+
+    Parameters
+    ----------
+    yobs : array-like
+        Array of birth years, one for each individual.
+
+    Returns
+    -------
+    numpy.ndarray
+        Array of FRA values in fractional years (1/12 increments), one for each individual.
+        Ages are returned in Social Security age format. Comparisons to FRA should be
+        done using Social Security age (which accounts for birthday-on-first adjustments).
     """
     fras = np.zeros(len(yobs))
 
@@ -35,7 +57,32 @@ def getFRAs(yobs):
 
 def getSpousalBenefits(pias):
     """
-    Compute spousal benefit. Returns an array.
+    Compute the maximum spousal benefit amount for each individual.
+
+    The spousal benefit is calculated as 50% of the spouse's Primary Insurance Amount (PIA),
+    minus the individual's own PIA. The result is the additional benefit the individual
+    would receive as a spouse, which cannot be negative.
+
+    Note: This calculation is not affected by which day of the month is the birthday.
+
+    Parameters
+    ----------
+    pias : array-like
+        Array of Primary Insurance Amounts (monthly benefit at FRA), one for each individual.
+        Must have exactly 1 or 2 entries.
+
+    Returns
+    -------
+    numpy.ndarray
+        Array of spousal benefit amounts (monthly), one for each individual.
+        For a single individual, returns [0].
+        For two individuals, returns the additional spousal benefit each would receive
+        (which is max(0, 0.5 * spouse_PIA - own_PIA)).
+
+    Raises
+    ------
+    ValueError
+        If the pias array does not have exactly 1 or 2 entries.
     """
     icount = len(pias)
     benefits = np.zeros(icount)
@@ -51,15 +98,52 @@ def getSpousalBenefits(pias):
     return benefits
 
 
-def getSelfFactor(fra, age):
+def getSelfFactor(fra, convage, bornOnFirstDays):
     """
-    Return factor to multiply PIA given the age when SS starts.
-    Year of FRA and age can be fractional.
+    Return the reduction/increase factor to multiply PIA based on claiming age.
+
+    This function calculates the adjustment factor for self benefits based on when
+    Social Security benefits start relative to Full Retirement Age (FRA):
+    - Before FRA: Benefits are reduced (minimum 70% at age 62)
+    - At FRA: Full benefit (100% of PIA)
+    - After FRA: Benefits are increased by 8% per year (up to 132% at age 70)
+
+    The function automatically adjusts for Social Security age if the birthday is on
+    the 1st or 2nd day of the month (adds 1/12 year to conventional age), consistent
+    with SSA rules that treat both days the same for age calculation purposes.
+
+    Parameters
+    ----------
+    fra : float
+        Full Retirement Age in years (can be fractional with 1/12 increments).
+    convage : float
+        Conventional age when benefits start, in years (can be fractional with 1/12 increments).
+        Must be between 62 and 70 inclusive.
+    bornOnFirstDays : bool
+        True if birthday is on the 1st or 2nd day of the month, False otherwise.
+        If True, the function adds 1/12 year to convert to Social Security age.
+
+    Returns
+    -------
+    float
+        Factor to multiply PIA. Examples:
+        - 0.75 = 75% of PIA (claiming at 62 with FRA of 66)
+        - 1.0 = 100% of PIA (claiming at FRA)
+        - 1.32 = 132% of PIA (claiming at 70 with FRA of 66)
+
+    Raises
+    ------
+    ValueError
+        If convage is less than 62 or greater than 70.
     """
-    if age < 62 or age > 70:
-        raise ValueError(f"Age {age} out of range.")
+    if convage < 62 or convage > 70:
+        raise ValueError(f"Age {convage} out of range.")
+
+    # Add a month to conventional age if born on the 1st or 2nd (SSA treats both the same).
+    offset = 0 if not bornOnFirstDays else 1/12
+    ssage = convage + offset
 
-    diff = fra - age
+    diff = fra - ssage
     if diff <= 0:
         return 1. - .08 * diff
     elif diff <= 3:
@@ -70,15 +154,51 @@ def getSelfFactor(fra, age):
         return .8 - 0.05 * (diff - 3)
 
 
-def getSpousalFactor(fra, age):
+def getSpousalFactor(fra, convage, bornOnFirstDays):
     """
-    Return factor to multiply spousal benefit given the age when benefit starts.
-    Year of FRA and age can be fractional.
+    Return the reduction factor to multiply spousal benefits based on claiming age.
+
+    This function calculates the adjustment factor for spousal benefits based on when
+    benefits start relative to Full Retirement Age (FRA):
+    - Before FRA: Benefits are reduced (minimum 32.5% at age 62)
+    - At or after FRA: Full spousal benefit (50% of spouse's PIA, no increase for delay)
+
+    The function automatically adjusts for Social Security age if the birthday is on
+    the 1st or 2nd day of the month (adds 1/12 year to conventional age), consistent
+    with SSA rules that treat both days the same for age calculation purposes.
+
+    Parameters
+    ----------
+    fra : float
+        Full Retirement Age in years (can be fractional with 1/12 increments).
+    convage : float
+        Conventional age when benefits start, in years (can be fractional with 1/12 increments).
+        Must be at least 62 (no maximum, but no increase beyond FRA).
+    bornOnFirstDays : bool
+        True if birthday is on the 1st or 2nd day of the month, False otherwise.
+        If True, the function adds 1/12 year to convert to Social Security age.
+
+    Returns
+    -------
+    float
+        Factor to multiply spousal benefit. Examples:
+        - 0.325 = 32.5% reduction factor (claiming at 62 with FRA of 66)
+        - 1.0 = 100% of spousal benefit (claiming at or after FRA)
+        Note: Unlike self benefits, spousal benefits do not increase beyond FRA.
+
+    Raises
+    ------
+    ValueError
+        If convage is less than 62.
     """
-    if age < 62:
-        raise ValueError(f"Age {age} out of range.")
+    if convage < 62:
+        raise ValueError(f"Age {convage} out of range.")
+
+    # Add a month to conventional age if born on the 1st or 2nd (SSA treats both the same).
+    offset = 0 if not bornOnFirstDays else 1/12
+    ssage = convage + offset
 
-    diff = fra - age
+    diff = fra - ssage
     if diff <= 0:
         return 1.
     elif diff <= 3:

owlplanner/tax2026.py

@@ -1,39 +1,35 @@
 """
+Tax calculation module for 2026 tax year rules.
 
-Owl/tax2026
----
+This module handles all tax calculations including income tax brackets,
+capital gains tax, and other tax-related computations based on 2026 tax rules.
 
-A retirement planner using linear programming optimization.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
-See companion document for a complete explanation and description
-of all variables and parameters.
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
 
-Module to handle all tax calculations.
-
-Copyright © 2026 - Martin-D. Lacasse
-
-Disclaimers: This code is for educational purposes only and does not constitute financial advice.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
 
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 import numpy as np
 from datetime import date
 
 
-##############################################################################
-# Prepare the data.
-
-taxBracketNames = ["10%", "12/15%", "22/25%", "24/28%", "32/33%", "35%", "37/40%"]
-
-rates_OBBBA = np.array([0.10, 0.12, 0.22, 0.24, 0.32, 0.35, 0.370])
-rates_preTCJA = np.array([0.10, 0.15, 0.25, 0.28, 0.33, 0.35, 0.396])
-
 ###############################################################################
 # Start of section where rates need to be actualized every year.
 ###############################################################################
 # Single [0] and married filing jointly [1].
 
-# These are 2025 current.
+# These are current for 2026, i.e., applying to tax year 2025.
 taxBrackets_OBBBA = np.array(
     [
         [12400, 50400, 105700, 201775, 256225, 640600, 9999999],
@@ -41,17 +37,20 @@ taxBrackets_OBBBA = np.array(
     ]
 )
 
+# These are current for 2026 (2025TY).
 irmaaBrackets = np.array(
     [
-        [0, 106000, 133000, 167000, 200000, 500000],
-        [0, 212000, 266000, 334000, 400000, 750000],
+        [0, 109000, 137000, 171000, 205000, 500000],
+        [0, 218000, 274000, 342000, 410000, 750000],
     ]
 )
 
-# Index [0] stores the standard Medicare part B premium.
+# These are current for 2026 (2025TY).
+# Index [0] stores the standard Medicare part B basic premium.
 # Following values are incremental IRMAA part B monthly fees.
-irmaaFees = 12 * np.array([185.00, 74.00, 111.00, 110.90, 111.00, 37.00])
+irmaaFees = 12 * np.array([202.90, 81.20, 121.70, 121.70, 121.70, 40.70])
 
+#########################################################################
 # Make projection for pre-TCJA using 2017 to current year.
 # taxBrackets_2017 = np.array(
 #    [ [9325, 37950, 91900, 191650, 416700, 418400, 9999999],
@@ -60,41 +59,60 @@ irmaaFees = 12 * np.array([185.00, 74.00, 111.00, 110.90, 111.00, 37.00])
 #
 # stdDeduction_2017 = [6350, 12700]
 #
-# For 2025, I used a 30.5% adjustment from 2017, rounded to closest 50.
+# COLA from 2017: [2.0, 2.8, 1.6, 1.3, 5.9, 8.7, 3.2, 2.5, 2.8]
+# For 2026, I used a 35.1% adjustment from 2017, rounded to closest 10.
 #
 # These are speculated.
 taxBrackets_preTCJA = np.array(
     [
-        [12150, 49550, 119950, 250200, 544000, 546200, 9999999],  # Single
-        [24350, 99100, 199850, 304600, 543950, 614450, 9999999],  # MFJ
+        [12600, 51270, 124160, 258920, 562960, 565260, 9999999],   # Single
+        [25200, 102540, 206840, 315260, 562960, 635920, 9999999],  # MFJ
     ]
 )
 
-# These are 2025 current.
+# These are speculated (adjusted for inflation to 2026).
+stdDeduction_preTCJA = np.array([8580, 17160])   # Single, MFJ
+#########################################################################
+
+# These are current for 2026 (2025TY).
 stdDeduction_OBBBA = np.array([16100, 32200])    # Single, MFJ
-# These are speculated (adjusted for inflation to 2026). TODO
-stdDeduction_preTCJA = np.array([8300, 16600])  # Single, MFJ
 
-# These are current (adjusted for inflation) per individual.
-extra65Deduction = np.array([2000, 1600])       # Single, MFJ
+# These are current for 2026  (2025TY) per individual.
+extra65Deduction = np.array([2000, 1600])        # Single, MFJ
 
-# Thresholds setting capital gains brackets 0%, 15%, 20% (adjusted for inflation).
+# These are current for 2026 (2025TY).
+# Thresholds setting capital gains brackets 0%, 15%, 20%.
 capGainRates = np.array(
     [
-        [48350, 533400],
-        [96700, 600050],
+        [49450, 545500],
+        [98900, 613700],
     ]
 )
 
+###############################################################################
+# End of section where rates need to be actualized every year.
+###############################################################################
+
+###############################################################################
+# Data that is unlikely to change.
+###############################################################################
+
 # Thresholds for net investment income tax (not adjusted for inflation).
 niitThreshold = np.array([200000, 250000])
 niitRate = 0.038
 
-# Thresholds for 65+ bonus for circumventing tax on social security.
+# Thresholds for 65+ bonus of $6k per individual for circumventing tax
+# on social security for low-income households. This expires in 2029.
+# These numbers are hard-coded below as the tax code will likely change
+# the rules for eligibility and will require a code review.
+# Bonus decreases linearly above threshold by 1% / $1k over threshold.
 bonusThreshold = np.array([75000, 150000])
 
-###############################################################################
-# End of section where rates need to be actualized every year.
+taxBracketNames = ["10%", "12/15%", "22/25%", "24/28%", "32/33%", "35%", "37/40%"]
+
+rates_OBBBA = np.array([0.10, 0.12, 0.22, 0.24, 0.32, 0.35, 0.370])
+rates_preTCJA = np.array([0.10, 0.15, 0.25, 0.28, 0.33, 0.35, 0.396])
+
 ###############################################################################
 
 
@@ -102,25 +120,26 @@ def mediVals(yobs, horizons, gamma_n, Nn, Nq):
     """
     Return tuple (nm, L, C) of year index when Medicare starts and vectors L, and C
     defining end points of constant piecewise linear functions representing IRMAA fees.
+    Costs C include the fact that one or two indivuals have to pay. Eligibility is built-in.
     """
     thisyear = date.today().year
     assert Nq == len(irmaaFees), f"Inconsistent value of Nq: {Nq}."
     assert Nq == len(irmaaBrackets[0]), "Inconsistent IRMAA brackets array."
     Ni = len(yobs)
-    # What index year will Medicare start? 65 - age.
-    nm = 65 - (thisyear - yobs)
-    nm = np.min(nm)
+    # What index year will Medicare start? 65 - age for each individual.
+    nm = yobs + 65 - thisyear
+    nm = np.maximum(0, nm)
+    nmstart = np.min(nm)
     # Has it already started?
-    nm = max(0, nm)
-    Nmed = Nn - nm
+    Nmed = Nn - nmstart
 
     L = np.zeros((Nmed, Nq-1))
     C = np.zeros((Nmed, Nq))
 
-    # Year starts at offset nm in the plan.
+    # Year starts at offset nmstart in the plan. L and C arrays are shorter.
     for nn in range(Nmed):
         imed = 0
-        n = nm + nn
+        n = nmstart + nn
         if thisyear + n - yobs[0] >= 65 and n < horizons[0]:
             imed += 1
         if Ni == 2 and thisyear + n - yobs[1] >= 65 and n < horizons[1]:
@@ -132,28 +151,83 @@ def mediVals(yobs, horizons, gamma_n, Nn, Nq):
         else:
             raise RuntimeError("mediVals: This should never happen.")
 
-    return nm, L, C
+    return nmstart, L, C
 
 
-def capitalGainTaxRate(Ni, magi_n, gamma_n, nd, Nn):
+def capitalGainTax(Ni, txIncome_n, ltcg_n, gamma_n, nd, Nn):
     """
-    Return an array of decimal rates for capital gains.
-    Parameter nd is the index year of first passing of a spouse, if applicable,
-    nd == Nn for single individuals.
+    Return an array of tax on capital gains.
+
+    Parameters:
+    -----------
+    Ni : int
+        Number of individuals (1 or 2)
+    txIncome_n : array
+        Array of taxable income for each year (ordinary income + capital gains)
+    ltcg_n : array
+        Array of long-term capital gains for each year
+    gamma_n : array
+        Array of inflation adjustment factors for each year
+    nd : int
+        Index year of first passing of a spouse, if applicable (nd == Nn for single individuals)
+    Nn : int
+        Total number of years in the plan
+
+    Returns:
+    --------
+    cgTax_n : array
+        Array of tax on capital gains for each year
+
+    Notes:
+    ------
+    Thresholds are determined by the taxable income which is roughly AGI - (standard/itemized) deductions.
+    Taxable income can also be thought of as taxable ordinary income + capital gains.
+
+    Long-term capital gains are taxed at 0%, 15%, or 20% based on total taxable income.
+    Capital gains "stack on top" of ordinary income, so the portion of gains that
+    pushes total income above each threshold is taxed at the corresponding rate.
     """
     status = Ni - 1
-    cgRate_n = np.zeros(Nn)
+    cgTax_n = np.zeros(Nn)
 
     for n in range(Nn):
         if status and n == nd:
             status -= 1
 
-        if magi_n[n] > gamma_n[n] * capGainRates[status][1]:
-            cgRate_n[n] = 0.20
-        elif magi_n[n] > gamma_n[n] * capGainRates[status][0]:
-            cgRate_n[n] = 0.15
+        # Calculate ordinary income (taxable income minus capital gains).
+        ordIncome = txIncome_n[n] - ltcg_n[n]
+
+        # Get inflation-adjusted thresholds for this year.
+        threshold15 = gamma_n[n] * capGainRates[status][0]  # 0% to 15% threshold
+        threshold20 = gamma_n[n] * capGainRates[status][1]  # 15% to 20% threshold
 
-    return cgRate_n
+        # Calculate how much LTCG falls in the 20% bracket.
+        # This is the portion of LTCG that pushes total income above threshold20.
+        if txIncome_n[n] > threshold20:
+            ltcg20 = min(ltcg_n[n], txIncome_n[n] - threshold20)
+        else:
+            ltcg20 = 0
+
+        # Calculate how much LTCG falls in the 15% bracket.
+        # This is the portion of LTCG in the range [threshold15, threshold20].
+        if ordIncome >= threshold20:
+            # All LTCG is already in the 20% bracket.
+            ltcg15 = 0
+        elif txIncome_n[n] > threshold15:
+            # Some LTCG falls in the 15% bracket.
+            # The 15% bracket spans from threshold15 to threshold20.
+            bracket_top = min(threshold20, txIncome_n[n])
+            bracket_bottom = max(threshold15, ordIncome)
+            ltcg15 = min(ltcg_n[n] - ltcg20, bracket_top - bracket_bottom)
+        else:
+            # Total income is below the 15% threshold.
+            ltcg15 = 0
+
+        # Remaining LTCG is in the 0% bracket (ltcg0 = ltcg_n[n] - ltcg20 - ltcg15).
+        # Calculate tax: 20% on ltcg20, 15% on ltcg15, 0% on remainder.
+        cgTax_n[n] = 0.20 * ltcg20 + 0.15 * ltcg15
+
+    return cgTax_n
 
 
 def mediCosts(yobs, horizons, magi, prevmagi, gamma_n, Nn):
@@ -257,7 +331,7 @@ def taxBrackets(N_i, n_d, N_n, yOBBBA=2099):
     # Number of years left in OBBBA from this year.
     thisyear = date.today().year
     if yOBBBA < thisyear:
-        raise ValueError(f"Expiration year {yOBBBA} cannot be in the past.")
+        raise ValueError(f"OBBBA expiration year {yOBBBA} cannot be in the past.")
 
     ytc = yOBBBA - thisyear
 
@@ -273,7 +347,27 @@ def taxBrackets(N_i, n_d, N_n, yOBBBA=2099):
     return data
 
 
-def rho_in(yobs, N_n):
+def computeNIIT(N_i, MAGI_n, I_n, Q_n, n_d, N_n):
+    """
+    Compute ACA tax on Dividends (Q) and Interests (I).
+    For accounting for rent and/or trust income, one can easily add a column
+    to the Wages and Contributions file and add yearly amount to Q_n + I_n below.
+    """
+    J_n = np.zeros(N_n)
+    status = N_i - 1
+
+    for n in range(N_n):
+        if status and n == n_d:
+            status -= 1
+
+        Gmax = niitThreshold[status]
+        if MAGI_n[n] > Gmax:
+            J_n[n] = niitRate * min(MAGI_n[n] - Gmax, I_n[n] + Q_n[n])
+
+    return J_n
+
+
+def rho_in(yobs, longevity, N_n):
     """
     Return Required Minimum Distribution fractions for each individual.
     This implementation does not support spouses with more than
@@ -316,11 +410,30 @@ def rho_in(yobs, N_n):
         5.2,
         4.9,
         4.6,
+        4.3,
+        4.1,
+        3.9,
+        3.7,
+        3.5,
+        3.4,
+        3.3,
+        3.1,
+        3.0,
+        2.9,
+        2.8,
+        2.7,
+        2.5,
+        2.3,
+        2.0
     ]
 
     N_i = len(yobs)
     if N_i == 2 and abs(yobs[0] - yobs[1]) > 10:
         raise RuntimeError("RMD: Unsupported age difference of more than 10 years.")
+    if np.any(np.array(longevity) > 120):
+        raise RuntimeError(
+            "RMD: Unsupported life expectancy over 120 years."
+        )
 
     rho = np.zeros((N_i, N_n))
     thisyear = date.today().year