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

owlplanner/abcapi.py

@@ -25,10 +25,10 @@ Disclaimers: This code is for educational purposes only and does not constitute
 import numpy as np
 
 
-class Row(object):
+class Row:
     """
-    Solver-neutral API to accomodate Mosek/HiGHS.
-    A Row represent a row in matrix A.
+    Solver-neutral API to accommodate Mosek/HiGHS.
+    A Row represents a row in matrix A.
     """
 
     def __init__(self, nvars):
@@ -58,7 +58,7 @@ class Row(object):
         return self
 
 
-class ConstraintMatrix(object):
+class ConstraintMatrix:
     """
     Solver-neutral API for expressing constraints.
     """
@@ -143,7 +143,7 @@ class ConstraintMatrix(object):
         return Alu, lb, ub
 
 
-class Bounds(object):
+class Bounds:
     """
     Solver-neutral API for bounds on variables.
     """
@@ -214,7 +214,7 @@ class Bounds(object):
         return self.integrality
 
 
-class Objective(object):
+class Objective:
     """
     Solver-neutral objective function.
     """

owlplanner/config.py

@@ -10,7 +10,7 @@ Disclaimers: This code is for educational purposes only and does not constitute
 
 """
 
-import toml as toml
+import toml
 from io import StringIO, BytesIO
 import numpy as np
 from datetime import date
@@ -21,12 +21,13 @@ from owlplanner import mylogging as log
 from owlplanner.rates import FROM, TO
 
 
+AccountTypes = ["taxable", "tax-deferred", "tax-free"]
+
+
 def saveConfig(myplan, file, mylog):
     """
     Save case parameters and return a dictionary containing all parameters.
     """
-    # np.set_printoptions(legacy='1.21')
-    accountTypes = ["taxable", "tax-deferred", "tax-free"]
 
     diconf = {}
     diconf["Plan Name"] = myplan._name
@@ -36,8 +37,7 @@ def saveConfig(myplan, file, mylog):
     diconf["Basic Info"] = {
         "Status": ["unknown", "single", "married"][myplan.N_i],
         "Names": myplan.inames,
-        "Birth year": myplan.yobs.tolist(),
-        "Birth month": myplan.mobs.tolist(),
+        "Date of birth": myplan.dobs,
         "Life expectancy": myplan.expectancy.tolist(),
         "Start date": myplan.startDate,
     }
@@ -46,13 +46,13 @@ def saveConfig(myplan, file, mylog):
     diconf["Assets"] = {}
     for j in range(myplan.N_j):
         amounts = myplan.beta_ij[:, j] / 1000
-        diconf["Assets"][f"{accountTypes[j]} savings balances"] = amounts.tolist()
+        diconf["Assets"][f"{AccountTypes[j]} savings balances"] = amounts.tolist()
     if myplan.N_i == 2:
         diconf["Assets"]["Beneficiary fractions"] = myplan.phi_j.tolist()
         diconf["Assets"]["Spousal surplus deposit fraction"] = myplan.eta
 
-    # Wages and Contributions.
-    diconf["Wages and Contributions"] = {"Contributions file name": myplan.timeListsFileName}
+    # Household Financial Profile
+    diconf["Household Financial Profile"] = {"HFP file name": myplan.timeListsFileName}
 
     # Fixed Income.
     diconf["Fixed Income"] = {
@@ -90,7 +90,7 @@ def saveConfig(myplan, file, mylog):
         "Type": myplan.ARCoord,
     }
     if myplan.ARCoord == "account":
-        for accType in accountTypes:
+        for accType in AccountTypes:
             diconf["Asset Allocation"][accType] = myplan.boundsAR[accType]
     else:
         diconf["Asset Allocation"]["generic"] = myplan.boundsAR["generic"]
@@ -146,8 +146,6 @@ def readConfig(file, *, verbose=True, logstreams=None, readContributions=True):
     """
     mylog = log.Logger(verbose, logstreams)
 
-    accountTypes = ["taxable", "tax-deferred", "tax-free"]
-
     dirname = ""
     if isinstance(file, str):
         filename = file
@@ -180,21 +178,19 @@ def readConfig(file, *, verbose=True, logstreams=None, readContributions=True):
     # Basic Info.
     name = diconf["Plan Name"]
     inames = diconf["Basic Info"]["Names"]
-    # status = diconf['Basic Info']['Status']
-    yobs = diconf["Basic Info"]["Birth year"]
-    icount = len(yobs)
-    # Default to January if no month entry found.
-    mobs = diconf["Basic Info"].get("Birth month", [1]*icount)
+    icount = len(inames)
+    # Default to January 15, 1965 if no entry is found.
+    dobs = diconf["Basic Info"].get("Date of birth", ["1965-01-15"]*icount)
     expectancy = diconf["Basic Info"]["Life expectancy"]
     s = ["", "s"][icount - 1]
     mylog.vprint(f"Plan for {icount} individual{s}: {inames}.")
-    p = plan.Plan(inames, yobs, mobs, expectancy, name, verbose=True, logstreams=logstreams)
+    p = plan.Plan(inames, dobs, expectancy, name, verbose=True, logstreams=logstreams)
     p._description = diconf.get("Description", "")
 
     # Assets.
     startDate = diconf["Basic Info"].get("Start date", "today")
     balances = {}
-    for acc in accountTypes:
+    for acc in AccountTypes:
         balances[acc] = diconf["Assets"][f"{acc} savings balances"]
     p.setAccountBalances(taxable=balances["taxable"], taxDeferred=balances["tax-deferred"],
                          taxFree=balances["tax-free"], startDate=startDate)
@@ -204,14 +200,14 @@ def readConfig(file, *, verbose=True, logstreams=None, readContributions=True):
         eta = diconf["Assets"]["Spousal surplus deposit fraction"]
         p.setSpousalDepositFraction(eta)
 
-    # Wages and Contributions.
-    timeListsFileName = diconf["Wages and Contributions"]["Contributions file name"]
+    # Household Financial Profile
+    timeListsFileName = diconf["Household Financial Profile"]["HFP file name"]
     if timeListsFileName != "None":
         if readContributions:
             if os.path.exists(timeListsFileName):
                 myfile = timeListsFileName
-            elif dirname != "" and os.path.exists(dirname + "/" + timeListsFileName):
-                myfile = dirname + "/" + timeListsFileName
+            elif dirname != "" and os.path.exists(os.path.join(dirname, timeListsFileName)):
+                myfile = os.path.join(dirname, timeListsFileName)
             else:
                 raise FileNotFoundError(f"File '{timeListsFileName}' not found.")
             p.readContributions(myfile)
@@ -243,7 +239,7 @@ def readConfig(file, *, verbose=True, logstreams=None, readContributions=True):
         frm = diconf["Rates Selection"]["From"]
         if not isinstance(frm, int):
             frm = int(frm)
-        to = int(diconf["Rates Selection"]["To"])
+        to = diconf["Rates Selection"]["To"]
         if not isinstance(to, int):
             to = int(to)
     if rateMethod in ["user", "stochastic"]:
@@ -262,7 +258,7 @@ def readConfig(file, *, verbose=True, logstreams=None, readContributions=True):
     )
     allocType = diconf["Asset Allocation"]["Type"]
     if allocType == "account":
-        for aType in accountTypes:
+        for aType in AccountTypes:
             boundsAR[aType] = np.array(diconf["Asset Allocation"][aType], dtype=np.float32)
 
         p.setAllocationRatios(
@@ -300,7 +296,7 @@ def readConfig(file, *, verbose=True, logstreams=None, readContributions=True):
     p.solverOptions = diconf["Solver Options"]
 
     # Address legacy case files.
-    if diconf["Solver Options"].get("withMedicare", None) is True:
+    if diconf["Solver Options"].get("withMedicare"):
         p.solverOptions["withMedicare"] = "loop"
 
     # Check consistency of noRothConversions.
@@ -311,7 +307,7 @@ def readConfig(file, *, verbose=True, logstreams=None, readContributions=True):
     # Rebase startRothConversions on year change.
     thisyear = date.today().year
     year = p.solverOptions.get("startRothConversions", thisyear)
-    diconf["Solver Options"]["startRothConversions"] = max(year, thisyear)
+    p.solverOptions["startRothConversions"] = max(year, thisyear)
 
     # Results.
     p.setDefaultPlots(diconf["Results"]["Default plots"])

owlplanner/data/awi.csv

@@ -0,0 +1,75 @@
+year,AWI,percent
+1951, 2799.16 ,—  
+1952, 2973.32 ,6.22
+1953, 3139.44 ,5.59
+1954, 3155.64 ,0.52
+1955, 3301.44 ,4.62
+1956, 3532.36 ,6.99
+1957, 3641.72 ,3.10
+1958, 3673.80 ,0.88
+1959, 3855.80 ,4.95
+1960, 4007.12 ,3.92
+1961, 4086.76 ,1.99
+1962, 4291.40 ,5.01
+1963, 4396.64 ,2.45
+1964, 4576.32 ,4.09
+1965, 4658.72 ,1.80
+1966, 4938.36 ,6.00
+1967, 5213.44 ,5.57
+1968, 5571.76 ,6.87
+1969, 5893.76 ,5.78
+1970, 6186.24 ,4.96
+1971, 6497.08 ,5.02
+1972, 7133.80 ,9.80
+1973, 7580.16 ,6.26
+1974, 8030.76 ,5.94
+1975, 8630.92 ,7.47
+1976, 9226.48 ,6.90
+1977, 9779.44 ,5.99
+1978, 10556.03 ,7.94
+1979, 11479.46 ,8.75
+1980, 12513.46 ,9.01
+1981, 13773.10 ,10.07
+1982, 14531.34 ,5.51
+1983, 15239.24 ,4.87
+1984, 16135.07 ,5.88
+1985, 16822.51 ,4.26
+1986, 17321.82 ,2.97
+1987, 18426.51 ,6.38
+1988, 19334.04 ,4.93
+1989, 20099.55 ,3.96
+1990, 21027.98 ,4.62
+1991, 21811.60 ,3.73
+1992, 22935.42 ,5.15
+1993, 23132.67 ,0.86
+1994, 23753.53 ,2.68
+1995, 24705.66 ,4.01
+1996, 25913.90 ,4.89
+1997, 27426.00 ,5.84
+1998, 28861.44 ,5.23
+1999, 30469.84 ,5.57
+2000, 32154.82 ,5.53
+2001, 32921.92 ,2.39
+2002, 33252.09 ,1.00
+2003, 34064.95 ,2.44
+2004, 35648.55 ,4.65
+2005, 36952.94 ,3.66
+2006, 38651.41 ,4.60
+2007, 40405.48 ,4.54
+2008, 41334.97 ,2.30
+2009, 40711.61 ,-1.51
+2010, 41673.83 ,2.36
+2011, 42979.61 ,3.13
+2012, 44321.67 ,3.12
+2013, 44888.16 ,1.28
+2014, 46481.52 ,3.55
+2015, 48098.63 ,3.48
+2016, 48642.15 ,1.13
+2017, 50321.89 ,3.45
+2018, 52145.80 ,3.62
+2019, 54099.99 ,3.75
+2020, 55628.60 ,2.83
+2021, 60575.07 ,8.89
+2022, 63795.13 ,5.32
+2023, 66621.80 ,4.43
+2024, 69846.57 ,4.84

owlplanner/data/bendpoints.csv

@@ -0,0 +1,49 @@
+year	first	second	
+1979	180	1085
+1980	194	1171
+1981	211	1274	
+1982	230	1388
+1983	254	1528
+1984	267	1612
+1985	280	1691
+1986	297	1790
+1987	310	1866
+1988	319	1922
+1989	339	2044
+1990	356	2145
+1991	370	2230
+1992	387	2333
+1993	401	2420
+1994	422	2545
+1995	426	2567
+1996	437	2635
+1997	455	2741
+1998	477	2875
+1999	505	3043
+2000	531	3202
+2001	561	3381
+2002	592	3567
+2003	606	3653
+2004	612	3689
+2005	627	3779
+2006	656	3955
+2007	680	4100
+2008	711	4288
+2009	744	4483
+2010	761	4586
+2011	749	4517
+2012	767	4624
+2013	791	4768
+2014	816	4917
+2015	826	4980
+2016	856	5157
+2017	885	5336
+2018	895	5397
+2019	926	5583
+2020	960	5785
+2021	996	6002
+2022	1024	6172
+2023	1115	6721
+2024	1174	7078
+2025	1226	7391
+2026	1286	7749

owlplanner/data/newawi.csv

@@ -0,0 +1,75 @@
+year,AWI,percent
+1951, 2799.16 ,—  
+1952, 2973.32 ,6.22
+1953, 3139.44 ,5.59
+1954, 3155.64 ,0.52
+1955, 3301.44 ,4.62
+1956, 3532.36 ,6.99
+1957, 3641.72 ,3.10
+1958, 3673.80 ,0.88
+1959, 3855.80 ,4.95
+1960, 4007.12 ,3.92
+1961, 4086.76 ,1.99
+1962, 4291.40 ,5.01
+1963, 4396.64 ,2.45
+1964, 4576.32 ,4.09
+1965, 4658.72 ,1.80
+1966, 4938.36 ,6.00
+1967, 5213.44 ,5.57
+1968, 5571.76 ,6.87
+1969, 5893.76 ,5.78
+1970, 6186.24 ,4.96
+1971, 6497.08 ,5.02
+1972, 7133.80 ,9.80
+1973, 7580.16 ,6.26
+1974, 8030.76 ,5.94
+1975, 8630.92 ,7.47
+1976, 9226.48 ,6.90
+1977, 9779.44 ,5.99
+1978, 10556.03 ,7.94
+1979, 11479.46 ,8.75
+1980, 12513.46 ,9.01
+1981, 13773.10 ,10.07
+1982, 14531.34 ,5.51
+1983, 15239.24 ,4.87
+1984, 16135.07 ,5.88
+1985, 16822.51 ,4.26
+1986, 17321.82 ,2.97
+1987, 18426.51 ,6.38
+1988, 19334.04 ,4.93
+1989, 20099.55 ,3.96
+1990, 21027.98 ,4.62
+1991, 21811.60 ,3.73
+1992, 22935.42 ,5.15
+1993, 23132.67 ,0.86
+1994, 23753.53 ,2.68
+1995, 24705.66 ,4.01
+1996, 25913.90 ,4.89
+1997, 27426.00 ,5.84
+1998, 28861.44 ,5.23
+1999, 30469.84 ,5.57
+2000, 32154.82 ,5.53
+2001, 32921.92 ,2.39
+2002, 33252.09 ,1.00
+2003, 34064.95 ,2.44
+2004, 35648.55 ,4.65
+2005, 36952.94 ,3.66
+2006, 38651.41 ,4.60
+2007, 40405.48 ,4.54
+2008, 41334.97 ,2.30
+2009, 40711.61 ,-1.51
+2010, 41673.83 ,2.36
+2011, 42979.61 ,3.13
+2012, 44321.67 ,3.12
+2013, 44888.16 ,1.28
+2014, 46481.52 ,3.55
+2015, 48098.63 ,3.48
+2016, 48642.15 ,1.13
+2017, 50321.89 ,3.45
+2018, 52145.80 ,3.62
+2019, 54099.99 ,3.75
+2020, 55628.60 ,2.83
+2021, 60575.07 ,8.89
+2022, 63795.13 ,5.32
+2023, 66621.80 ,4.43
+2024, 69846.57 ,4.84

owlplanner/debts.py

@@ -0,0 +1,287 @@
+"""
+
+Owl/debts:r
+
+This file contains functions for handling debts.
+
+Copyright © 2025 - Martin-D. Lacasse
+
+Disclaimers: This code is for educational purposes only and does not constitute financial advice.
+
+"""
+
+######################################################################
+import numpy as np
+import pandas as pd  # noqa: F401
+from datetime import date
+
+
+def calculate_monthly_payment(principal, annual_rate, term_years):
+    """
+    Calculate monthly payment for an amortizing loan. This is a constant payment amount for a fixed-rate loan.
+    monthly payment = principal * (monthly_rate * (1 + monthly_rate)**num_payments) /
+                      ((1 + monthly_rate)**num_payments - 1)
+    where monthly_rate = annual_rate / 100.0 / 12.0 and num_payments = term_years * 12.0.
+
+    This formula is derived from the formula for the present value of an annuity.
+
+    Parameters:
+    -----------
+    principal : float
+        Original loan amount
+    annual_rate : float
+        Annual interest rate as a percentage (e.g., 4.5 for 4.5%)
+    term_years : int
+        Loan term in years
+
+    Returns:
+    --------
+    float
+        Monthly payment amount
+    """
+    if term_years <= 0 or annual_rate < 0 or principal <= 0:
+        return 0.0
+
+    monthly_rate = annual_rate / 100.0 / 12.0
+    num_payments = term_years * 12
+    fac = (1 + monthly_rate)**num_payments
+
+    if monthly_rate == 0:
+        return principal / num_payments
+
+    payment = principal * (monthly_rate * fac) / (fac - 1)
+
+    return payment
+
+
+def calculate_annual_payment(principal, annual_rate, term_years):
+    """
+    Calculate annual payment for an amortizing loan.
+
+    Parameters:
+    -----------
+    principal : float
+        Original loan amount
+    annual_rate : float
+        Annual interest rate as a percentage
+    term_years : int
+        Loan term in years
+
+    Returns:
+    --------
+    float
+        Annual payment amount
+    """
+    return 12 * calculate_monthly_payment(principal, annual_rate, term_years)
+
+
+def calculate_remaining_balance(principal, annual_rate, term_years, years_elapsed):
+    """
+    Calculate remaining balance on a loan after a given number of years.
+
+    Parameters:
+    -----------
+    principal : float
+        Original loan amount
+    annual_rate : float
+        Annual interest rate as a percentage
+    term_years : int
+        Original loan term in years
+    years_elapsed : float
+        Number of years since loan origination
+
+    Returns:
+    --------
+    float
+        Remaining balance
+    """
+    if years_elapsed <= 0:
+        return principal
+
+    if years_elapsed >= term_years:
+        return 0.0
+
+    monthly_rate = annual_rate / 100.0 / 12.0
+    fac = 1 + monthly_rate
+    num_payments = term_years * 12
+    payments_made = int(years_elapsed * 12)
+
+    if monthly_rate == 0:
+        return principal * (1 - payments_made / num_payments)
+
+    remaining = principal * (fac**num_payments - fac**payments_made) / (fac**num_payments - 1)
+
+    return max(0.0, remaining)
+
+
+def get_debt_payments_for_year(debts_df, year):
+    """
+    Calculate total debt payments (principal + interest) for a given year.
+
+    Parameters:
+    -----------
+    debts_df : pd.DataFrame
+        DataFrame with columns: name, type, year, term, amount, rate
+    year : int
+        Year for which to calculate payments
+
+    Returns:
+    --------
+    float
+        Total annual debt payments for the year
+    """
+    if debts_df is None or debts_df.empty:
+        return 0.0
+
+    total_payments = 0.0
+
+    for _, debt in debts_df.iterrows():
+        start_year = int(debt["year"])
+        term = int(debt["term"])
+        end_year = start_year + term
+
+        # Check if loan is active in this year
+        if start_year <= year < end_year:
+            principal = float(debt["amount"])
+            rate = float(debt["rate"])
+
+            # Calculate annual payment (payment amount is constant for fixed-rate loans)
+            annual_payment = calculate_annual_payment(principal, rate, term)
+            total_payments += annual_payment
+
+    return total_payments
+
+
+def get_debt_balances_for_year(debts_df, year):
+    """
+    Calculate total remaining debt balances at the end of a given year.
+
+    Parameters:
+    -----------
+    debts_df : pd.DataFrame
+        DataFrame with columns: name, type, year, term, amount, rate
+    year : int
+        Year for which to calculate balances
+
+    Returns:
+    --------
+    float
+        Total remaining debt balances at end of year
+    """
+    if debts_df is None or debts_df.empty:
+        return 0.0
+
+    total_balance = 0.0
+
+    for _, debt in debts_df.iterrows():
+        start_year = int(debt["year"])
+        term = int(debt["term"])
+        end_year = start_year + term
+
+        # Check if loan is active at end of this year
+        if start_year <= year < end_year:
+            principal = float(debt["amount"])
+            rate = float(debt["rate"])
+
+            # Calculate remaining balance at end of year
+            years_elapsed = year - start_year + 1
+            remaining_balance = calculate_remaining_balance(principal, rate, term, years_elapsed)
+            total_balance += remaining_balance
+
+    return total_balance
+
+
+def get_debt_payments_array(debts_df, N_n, thisyear=None):
+    """
+    Process debts_df to provide a single array of length N_n containing
+    all annual payments made for each year of the plan.
+
+    Parameters:
+    -----------
+    debts_df : pd.DataFrame
+        DataFrame with columns: name, type, year, term, amount, rate
+    N_n : int
+        Number of years in the plan (length of output array)
+    thisyear : int, optional
+        Starting year of the plan (defaults to date.today().year).
+        Array index 0 corresponds to thisyear, index 1 to thisyear+1, etc.
+
+    Returns:
+    --------
+    np.ndarray
+        Array of length N_n with annual debt payments for each year.
+        payments_n[0] = payments for thisyear,
+        payments_n[1] = payments for thisyear+1, etc.
+    """
+    if thisyear is None:
+        thisyear = date.today().year
+
+    if debts_df is None or debts_df.empty:
+        return np.zeros(N_n)
+
+    payments_n = np.zeros(N_n)
+
+    for _, debt in debts_df.iterrows():
+        start_year = int(debt["year"])
+        term = int(debt["term"])
+        end_year = start_year + term
+        principal = float(debt["amount"])
+        rate = float(debt["rate"])
+
+        # Calculate annual payment (payment amount is constant for fixed-rate loans)
+        annual_payment = calculate_annual_payment(principal, rate, term)
+
+        # Add payments for each year the loan is active within the plan horizon
+        for n in range(N_n):
+            year = thisyear + n
+            if start_year <= year < end_year:
+                payments_n[n] += annual_payment
+
+    return payments_n
+
+
+def get_remaining_debt_balance(debts_df, N_n, thisyear=None):
+    """
+    Calculate total remaining debt balance at the end of the plan horizon.
+    Returns the sum of all remaining balances for loans that haven't been
+    fully paid off by the end of the plan.
+
+    Parameters:
+    -----------
+    debts_df : pd.DataFrame
+        DataFrame with columns: name, type, year, term, amount, rate
+    N_n : int
+        Number of years in the plan
+    thisyear : int, optional
+        Starting year of the plan (defaults to date.today().year)
+
+    Returns:
+    --------
+    float
+        Total remaining debt balance at the end of the plan horizon.
+        Returns 0.0 if all loans are paid off or if no loans are active.
+    """
+    if thisyear is None:
+        thisyear = date.today().year
+
+    if debts_df is None or debts_df.empty:
+        return 0.0
+
+    end_year = thisyear + N_n - 1
+    total_balance = 0.0
+
+    for _, debt in debts_df.iterrows():
+        start_year = int(debt["year"])
+        term = int(debt["term"])
+        loan_end_year = start_year + term
+        principal = float(debt["amount"])
+        rate = float(debt["rate"])
+
+        # Check if loan is still active at the end of the plan
+        if start_year <= end_year < loan_end_year:
+            # Calculate remaining balance at end of plan horizon
+            years_elapsed = end_year - start_year + 1
+            remaining_balance = calculate_remaining_balance(principal, rate, term, years_elapsed)
+            total_balance += remaining_balance
+
+    return total_balance