owlplanner 2025.12.20__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
@@ -91,7 +98,7 @@ def getSpousalBenefits(pias):
     return benefits
 
 
-def getSelfFactor(fra, convage, bornOnFirst):
+def getSelfFactor(fra, convage, bornOnFirstDays):
     """
     Return the reduction/increase factor to multiply PIA based on claiming age.
 
@@ -102,7 +109,8 @@ def getSelfFactor(fra, convage, bornOnFirst):
     - 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 first day of the month (adds 1/12 year to conventional age).
+    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
     ----------
@@ -111,8 +119,8 @@ def getSelfFactor(fra, convage, bornOnFirst):
     convage : float
         Conventional age when benefits start, in years (can be fractional with 1/12 increments).
         Must be between 62 and 70 inclusive.
-    bornOnFirst : bool
-        True if birthday is on the first day of the month, False otherwise.
+    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
@@ -131,8 +139,8 @@ def getSelfFactor(fra, convage, bornOnFirst):
     if convage < 62 or convage > 70:
         raise ValueError(f"Age {convage} out of range.")
 
-    # Add a month to conventional age if born on the first.
-    offset = 0 if not bornOnFirst else 1/12
+    # 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 - ssage
@@ -146,7 +154,7 @@ def getSelfFactor(fra, convage, bornOnFirst):
         return .8 - 0.05 * (diff - 3)
 
 
-def getSpousalFactor(fra, convage, bornOnFirst):
+def getSpousalFactor(fra, convage, bornOnFirstDays):
     """
     Return the reduction factor to multiply spousal benefits based on claiming age.
 
@@ -156,7 +164,8 @@ def getSpousalFactor(fra, convage, bornOnFirst):
     - 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 first day of the month (adds 1/12 year to conventional age).
+    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
     ----------
@@ -165,8 +174,8 @@ def getSpousalFactor(fra, convage, bornOnFirst):
     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).
-    bornOnFirst : bool
-        True if birthday is on the first day of the month, False otherwise.
+    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
@@ -185,8 +194,8 @@ def getSpousalFactor(fra, convage, bornOnFirst):
     if convage < 62:
         raise ValueError(f"Age {convage} out of range.")
 
-    # Add a month to conventional age if born on the first.
-    offset = 0 if not bornOnFirst else 1/12
+    # 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 - ssage

owlplanner/tax2026.py

@@ -1,19 +1,23 @@
 """
+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
@@ -116,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]:
@@ -146,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
+
+        # 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 cgRate_n
+    return cgTax_n
 
 
 def mediCosts(yobs, horizons, magi, prevmagi, gamma_n, Nn):
@@ -271,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
 
@@ -307,7 +367,7 @@ def computeNIIT(N_i, MAGI_n, I_n, Q_n, n_d, N_n):
     return J_n
 
 
-def rho_in(yobs, N_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
@@ -350,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

owlplanner/timelists.py

@@ -1,24 +1,30 @@
 """
+Time horizon data validation and processing utilities.
 
-Owl/timelists
----
+This module provides utility functions to read and validate timelist data
+from Excel files, including wage, contribution, and other time-based parameters.
 
-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.
 
-Utility functions to read and check timelists.
-
-Copyright © 2024 - 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/>.
 """
 
 from datetime import date
 import pandas as pd
 
+from . import utils as u
+
 
 # Expected headers in each excel sheet, one per individual.
 _timeHorizonItems = [
@@ -35,6 +41,7 @@ _timeHorizonItems = [
 
 
 _debtItems = [
+    "active",
     "name",
     "type",
     "year",
@@ -51,8 +58,10 @@ _debtTypes = [
 
 
 _fixedAssetItems = [
+    "active",
     "name",
     "type",
+    "year",
     "basis",
     "value",
     "rate",
@@ -71,7 +80,7 @@ _fixedAssetTypes = [
 ]
 
 
-def read(finput, inames, horizons, mylog):
+def read(finput, inames, horizons, mylog, filename=None):
     """
     Read listed parameters from an excel spreadsheet or through
     a dictionary of dataframes through Pandas.
@@ -80,6 +89,20 @@ def read(finput, inames, horizons, mylog):
     IRA ctrb, Roth IRA ctrb, Roth conv, and big-ticket items.
     Supports xls, xlsx, xlsm, xlsb, odf, ods, and odt file extensions.
     Return a dictionary of dataframes by individual's names.
+
+    Parameters
+    ----------
+    finput : file-like object, str, or dict
+        Input file or dictionary of DataFrames
+    inames : list
+        List of individual names
+    horizons : list
+        List of time horizons
+    mylog : logger
+        Logger instance
+    filename : str, optional
+        Explicit filename for logging purposes. If provided, this will be used
+        instead of trying to extract it from finput.
     """
 
     mylog.vprint("Reading wages, contributions, conversions, and big-ticket items over time...")
@@ -89,13 +112,19 @@ def read(finput, inames, horizons, mylog):
         finput = "dictionary of DataFrames"
         streamName = "dictionary of DataFrames"
     else:
+        if filename is not None:
+            streamName = f"file '{filename}'"
+        elif hasattr(finput, "name"):
+            streamName = f"file '{finput.name}'"
+        else:
+            streamName = finput
+
         # Read all worksheets in memory but only process those with proper names.
         try:
             # dfDict = pd.read_excel(finput, sheet_name=None, usecols=_timeHorizonItems)
             dfDict = pd.read_excel(finput, sheet_name=None)
         except Exception as e:
-            raise Exception(f"Could not read file {finput}: {e}.") from e
-        streamName = f"file '{finput}'"
+            raise Exception(f"Could not read file {streamName}: {e}.") from e
 
     timeLists = _conditionTimetables(dfDict, inames, horizons, mylog)
     mylog.vprint(f"Successfully read time horizons from {streamName}.")
@@ -111,10 +140,13 @@ def _checkColumns(df, iname, colList):
     Ensure all columns in colList are present. Remove others.
     """
     # Drop all columns not in the list.
-    df = df.loc[:, ~df.columns.str.contains("^Unnamed")]
-    for col in df.columns:
-        if col == "" or col not in colList:
-            df.drop(col, axis=1, inplace=True)
+    # Make an explicit copy to avoid SettingWithCopyWarning
+    df = df.loc[:, ~df.columns.str.contains("^Unnamed")].copy()
+
+    # Collect columns to drop
+    cols_to_drop = [col for col in df.columns if col == "" or col not in colList]
+    if cols_to_drop:
+        df = df.drop(cols_to_drop, axis=1)
 
     # Check that all columns in the list are present.
     for item in colList:
@@ -141,6 +173,9 @@ def _conditionTimetables(dfDict, inames, horizons, mylog):
 
         df = _checkColumns(df, iname, _timeHorizonItems)
 
+        # Ensure columns are in the correct order
+        df = df[_timeHorizonItems].copy()
+
         # Only consider lines in proper year range. Go back 5 years for Roth maturation.
         df = df[df["year"] >= (thisyear - 5)]
         df = df[df["year"] < endyear]
@@ -150,7 +185,10 @@ def _conditionTimetables(dfDict, inames, horizons, mylog):
             year = thisyear + n
             year_rows = df[df["year"] == year]
             if year_rows.empty:
-                df.loc[len(df)] = [year, 0, 0, 0, 0, 0, 0, 0, 0]
+                # Create a new row as a dictionary to ensure correct column mapping.
+                new_row = {col: 0 for col in _timeHorizonItems}
+                new_row["year"] = year
+                df = pd.concat([df, pd.DataFrame([new_row])], ignore_index=True)
                 missing.append(year)
             else:
                 for item in _timeHorizonItems:
@@ -220,6 +258,21 @@ def _conditionHouseTables(dfDict, mylog):
                             f"Converted {mask.sum()} commission value(s) from decimal "
                             f"to percentage in Fixed Assets table."
                         )
+                # Validate and reset "year" column (reference year) if in the past
+                if "year" in df.columns:
+                    thisyear = date.today().year
+                    mask = df["year"] < thisyear
+                    if mask.any():
+                        df.loc[mask, "year"] = thisyear
+                        mylog.vprint(
+                            f"Reset {mask.sum()} reference year value(s) to {thisyear} "
+                            f"in Fixed Assets table (years cannot be in the past)."
+                        )
+
+            # Convert "active" column to boolean if it exists.
+            # Excel may read booleans as strings ("True"/"False") or numbers (1/0).
+            if "active" in df.columns:
+                df["active"] = df["active"].apply(u.convert_to_bool).astype(bool)
 
             houseDic[page] = df
             mylog.vprint(f"Found {len(df)} valid row(s) in {page} table.")
@@ -228,3 +281,126 @@ def _conditionHouseTables(dfDict, mylog):
             mylog.vprint(f"Table for {page} not found. Assuming empty table.")
 
     return houseDic
+
+
+def conditionDebtsAndFixedAssetsDF(df, tableType, mylog=None):
+    """
+    Condition a DataFrame for Debts or Fixed Assets by:
+    - Creating an empty DataFrame with proper columns if df is None or empty
+    - Resetting the index
+    - Filling NaN values with 0 while preserving boolean columns (like "active")
+
+    Parameters
+    ----------
+    df : pandas.DataFrame or None
+        The DataFrame to condition, or None/empty to create a new empty DataFrame
+    tableType : str
+        Type of table: "Debts" or "Fixed Assets"
+    mylog : logger, optional
+        Logger instance for optional UI/log output
+
+    Returns
+    -------
+    pandas.DataFrame
+        Conditioned DataFrame with proper columns and no NaN values (except boolean columns default to True)
+    """
+    # Map table type to column items
+    items = {"Debts": _debtItems, "Fixed Assets": _fixedAssetItems}
+    if tableType not in items:
+        raise ValueError(f"tableType must be 'Debts' or 'Fixed Assets', got '{tableType}'")
+
+    columnItems = items[tableType]
+
+    df = u.ensure_dataframe(df, pd.DataFrame(columns=columnItems))
+
+    df = df.copy()
+    df.reset_index(drop=True, inplace=True)
+
+    # Ensure all required columns exist
+    for col in columnItems:
+        if col not in df.columns:
+            df[col] = None
+
+    # Only keep the columns we need, in the correct order
+    df = df[columnItems].copy()
+
+    # Define which columns are integers vs floats
+    if tableType == "Debts":
+        int_cols = ["year", "term"]
+        float_cols = ["amount", "rate"]
+    else:  # Fixed Assets
+        int_cols = ["year", "yod"]
+        float_cols = ["basis", "value", "rate", "commission"]
+
+    # Handle empty DataFrame by setting dtypes directly
+    if len(df) == 0:
+        dtype_dict = {}
+        dtype_dict["active"] = bool
+        for col in ["name", "type"]:
+            dtype_dict[col] = "object"  # string columns
+        for col in int_cols:
+            dtype_dict[col] = "int64"
+        for col in float_cols:
+            dtype_dict[col] = "float64"
+        df = df.astype(dtype_dict)
+    else:
+        # Fill NaN values and ensure proper types for non-empty DataFrame
+        for col in df.columns:
+            if col == "active":
+                # Ensure "active" column is boolean, handling strings/numbers from Excel
+                df[col] = df[col].apply(u.convert_to_bool).astype(bool)
+            elif col in ["name", "type"]:
+                # String columns: ensure they are strings, not lists
+                # Streamlit data_editor can return lists for string columns in some cases
+                def convert_to_string(val):
+                    if pd.isna(val) or val is None:
+                        return ""
+                    if isinstance(val, list):
+                        # If it's a list, join the elements (handles Streamlit data_editor edge cases)
+                        # Filter out None/NaN values before joining
+                        cleaned = [str(x) for x in val if x is not None and not pd.isna(x)]
+                        return " ".join(cleaned) if cleaned else ""
+                    return str(val)
+
+                df[col] = df[col].apply(convert_to_string).astype(str)
+                # Replace "nan" string with empty string
+                df[col] = df[col].replace("nan", "").replace("None", "")
+            elif col in int_cols:
+                # Integer columns: convert to int64, fill NaN with 0
+                df[col] = pd.to_numeric(df[col], errors="coerce").fillna(0).astype("int64")
+            elif col in float_cols:
+                # Float columns: convert to float64, fill NaN with 0.0
+                df[col] = pd.to_numeric(df[col], errors="coerce").fillna(0.0).astype("float64")
+
+    # For Fixed Assets, validate and reset "year" column if in the past
+    if tableType == "Fixed Assets" and "year" in df.columns and len(df) > 0:
+        thisyear = date.today().year
+        mask = df["year"] < thisyear
+        if mask.any():
+            df.loc[mask, "year"] = thisyear
+
+    if mylog is not None:
+        mylog.vprint(f"Found {len(df)} valid row(s) in {tableType} table.")
+
+    return df
+
+
+def getTableTypes(tableType):
+    """
+    Get the list of valid types for a given table type.
+
+    Parameters
+    ----------
+    tableType : str
+        Type of table: "Debts" or "Fixed Assets"
+
+    Returns
+    -------
+    list
+        List of valid types for the specified table
+    """
+    types = {"Debts": _debtTypes, "Fixed Assets": _fixedAssetTypes}
+    if tableType not in types:
+        raise ValueError(f"tableType must be 'Debts' or 'Fixed Assets', got '{tableType}'")
+
+    return types[tableType]