owlplanner 2025.6.3__py3-none-any.whl → 2025.6.21__py3-none-any.whl

owlplanner/plan.py

@@ -304,8 +304,8 @@ class Plan(object):
         # Parameters from timeLists initialized to zero.
         self.omega_in = np.zeros((self.N_i, self.N_n))
         self.Lambda_in = np.zeros((self.N_i, self.N_n))
-        self.myRothX_in = np.zeros((self.N_i, self.N_n))
-        self.kappa_ijn = np.zeros((self.N_i, self.N_j, self.N_n))
+        self.myRothX_in = np.zeros((self.N_i, self.N_n + 5))
+        self.kappa_ijn = np.zeros((self.N_i, self.N_j, self.N_n + 5))
 
         # Previous 3 years for Medicare.
         self.prevMAGI = np.zeros((2))
@@ -920,14 +920,17 @@ class Plan(object):
         # Now fill in parameters which are in $.
         for i, iname in enumerate(self.inames):
             h = self.horizons[i]
-            self.omega_in[i, :h] = self.timeLists[iname]["anticipated wages"].iloc[:h]
-            self.kappa_ijn[i, 0, :h] = self.timeLists[iname]["taxable ctrb"].iloc[:h]
-            self.kappa_ijn[i, 1, :h] = self.timeLists[iname]["401k ctrb"].iloc[:h]
-            self.kappa_ijn[i, 2, :h] = self.timeLists[iname]["Roth 401k ctrb"].iloc[:h]
-            self.kappa_ijn[i, 1, :h] += self.timeLists[iname]["IRA ctrb"].iloc[:h]
-            self.kappa_ijn[i, 2, :h] += self.timeLists[iname]["Roth IRA ctrb"].iloc[:h]
-            self.myRothX_in[i, :h] = self.timeLists[iname]["Roth conv"].iloc[:h]
-            self.Lambda_in[i, :h] = self.timeLists[iname]["big-ticket items"].iloc[:h]
+            self.omega_in[i, :h] = self.timeLists[iname]["anticipated wages"].iloc[5:5+h]
+            self.Lambda_in[i, :h] = self.timeLists[iname]["big-ticket items"].iloc[5:5+h]
+
+            # Values for last 5 years of Roth conversion and contributions stored at the end
+            # of array and accessed with negative index.
+            self.kappa_ijn[i, 0, :h+5] = np.roll(self.timeLists[iname]["taxable ctrb"], -5)
+            self.kappa_ijn[i, 1, :h+5] = np.roll(self.timeLists[iname]["401k ctrb"], -5)
+            self.kappa_ijn[i, 1, :h+5] += np.roll(self.timeLists[iname]["IRA ctrb"], -5)
+            self.kappa_ijn[i, 2, :h+5] = np.roll(self.timeLists[iname]["Roth 401k ctrb"], -5)
+            self.kappa_ijn[i, 2, :h+5] += np.roll(self.timeLists[iname]["Roth IRA ctrb"], -5)
+            self.myRothX_in[i, :h+5] = np.roll(self.timeLists[iname]["Roth conv"], -5)
 
         self.caseStatus = "modified"
 
@@ -984,8 +987,9 @@ class Plan(object):
         ]
         for i, iname in enumerate(self.inames):
             h = self.horizons[i]
-            df = pd.DataFrame(0, index=np.arange(h), columns=cols)
-            df["year"] = self.year_n[:h]
+            df = pd.DataFrame(0, index=np.arange(0, h+5), columns=cols)
+            # df["year"] = self.year_n[:h]
+            df["year"] = np.arange(self.year_n[0] - 5, self.year_n[h-1]+1)
             self.timeLists[iname] = df
 
         self.caseStatus = "modified"
@@ -1086,6 +1090,7 @@ class Plan(object):
         self._add_standard_exemption_bounds()
         self._add_defunct_constraints()
         self._add_roth_conversion_constraints(options)
+        self._add_roth_maturation_constraints()
         self._add_withdrawal_limits()
         self._add_conversion_limits()
         self._add_objective_constraints(objective, options)
@@ -1127,6 +1132,45 @@ class Plan(object):
                 for j in range(self.N_j):
                     self.B.setRange(_q3(self.C["w"], self.i_d, j, n, self.N_i, self.N_j, self.N_n), 0, 0)
 
+    def _add_roth_maturation_constraints(self):
+        """
+        Withdrawals from Roth accounts are subject to the 5-year rule for conversion.
+        Conversions and gains are subject to the 5-year rule since conversion.
+        Contributions can be withdrawn at any time (without 59.5 penalty) but
+        gains on contributions are subject to the 5-year rule since the opening of the account.
+        A retainer is put on all conversions and associated gains, and gains on all recent contributions.
+        """
+        # Assume 10% per year for contributions and conversions for past 5 years.
+        # Future years will use the assumed returns.
+        oldTau1 = 1.10
+        for i in range(self.N_i):
+            h = self.horizons[i]
+            for n in range(h):
+                rhs = 0
+                # To add compounded gains to original amount.
+                cgains = 1
+                row = self.A.newRow()
+                row.addElem(_q3(self.C["b"], i, 2, n, self.N_i, self.N_j, self.N_n + 1), 1)
+                row.addElem(_q3(self.C["w"], i, 2, n, self.N_i, self.N_j, self.N_n), -1)
+                for dn in range(1, 6):
+                    nn = n - dn
+                    if nn < 0:  # Past of future is in the past:
+                        # Parameters are stored at the end of contributions and conversions arrays.
+                        cgains *= oldTau1
+                        # If only an contribution - without conversion.
+                        # rhs += (cgains - 1) * self.kappa_ijn[i, 2, nn] + cgains * self.myRothX_in[i, nn]
+                        rhs += cgains * self.kappa_ijn[i, 2, nn] + cgains * self.myRothX_in[i, nn]
+                    else:       # Past of future is in the future: use variables and parameters.
+                        ksum2 = np.sum(self.alpha_ijkn[i, 2, :, nn] * self.tau_kn[:, nn], axis=0)
+                        Tau1 = 1 + ksum2
+                        cgains *= Tau1
+                        row.addElem(_q2(self.C["x"], i, nn, self.N_i, self.N_n), -cgains)
+                        # If only a contribution - without conversion.
+                        # rhs += (cgains - 1) * self.kappa_ijn[i, 2, nn]
+                        rhs += cgains * self.kappa_ijn[i, 2, nn]
+
+                self.A.addRow(row, rhs, np.inf)
+
     def _add_roth_conversion_constraints(self, options):
         if "maxRothConversion" in options and options["maxRothConversion"] == "file":
             for i in range(self.N_i):
@@ -1949,7 +1993,7 @@ class Plan(object):
         self.Q_n = np.sum(
             (
                 self.mu
-                * (self.b_ijn[:, 0, :-1] - self.w_ijn[:, 0, :] + self.d_in[:, :] + 0.5 * self.kappa_ijn[:, 0, :])
+                * (self.b_ijn[:, 0, :-1] - self.w_ijn[:, 0, :] + self.d_in[:, :] + 0.5 * self.kappa_ijn[:, 0, :Nn])
                 + tau_0prev * self.w_ijn[:, 0, :]
             )
             * self.alpha_ijkn[:, 0, 0, :-1],
@@ -2370,7 +2414,7 @@ class Plan(object):
         the default behavior of setDefaultPlots().
         """
         value = self._checkValue(value)
-        title = self._name + "\nIncome Tax"
+        title = self._name + "\nFederal Income Tax"
         if tag:
             title += " - " + tag
         # All taxes: ordinary income and dividends.
@@ -2489,16 +2533,16 @@ class Plan(object):
         # Account balances except final year.
         accDic = {
             "taxable bal": self.b_ijn[:, 0, :-1],
-            "taxable ctrb": self.kappa_ijn[:, 0, :],
+            "taxable ctrb": self.kappa_ijn[:, 0, :self.N_n],
             "taxable dep": self.d_in,
             "taxable wdrwl": self.w_ijn[:, 0, :],
             "tax-deferred bal": self.b_ijn[:, 1, :-1],
-            "tax-deferred ctrb": self.kappa_ijn[:, 1, :],
+            "tax-deferred ctrb": self.kappa_ijn[:, 1, :self.N_n],
             "tax-deferred wdrwl": self.w_ijn[:, 1, :],
             "(included RMDs)": self.rmd_in[:, :],
             "Roth conv": self.x_in,
             "tax-free bal": self.b_ijn[:, 2, :-1],
-            "tax-free ctrb": self.kappa_ijn[:, 2, :],
+            "tax-free ctrb": self.kappa_ijn[:, 2, :self.N_n],
             "tax-free wdrwl": self.w_ijn[:, 2, :],
         }
         for i in range(self.N_i):
@@ -2595,12 +2639,12 @@ class Plan(object):
             planData[self.inames[i] + " txbl dep"] = self.d_in[i, :]
             planData[self.inames[i] + " txbl wrdwl"] = self.w_ijn[i, 0, :]
             planData[self.inames[i] + " tx-def bal"] = self.b_ijn[i, 1, :-1]
-            planData[self.inames[i] + " tx-def ctrb"] = self.kappa_ijn[i, 1, :]
+            planData[self.inames[i] + " tx-def ctrb"] = self.kappa_ijn[i, 1, :self.N_n]
             planData[self.inames[i] + " tx-def wdrl"] = self.w_ijn[i, 1, :]
             planData[self.inames[i] + " (RMD)"] = self.rmd_in[i, :]
             planData[self.inames[i] + " Roth conv"] = self.x_in[i, :]
             planData[self.inames[i] + " tx-free bal"] = self.b_ijn[i, 2, :-1]
-            planData[self.inames[i] + " tx-free ctrb"] = self.kappa_ijn[i, 2, :]
+            planData[self.inames[i] + " tx-free ctrb"] = self.kappa_ijn[i, 2, :self.N_n]
             planData[self.inames[i] + " tax-free wdrwl"] = self.w_ijn[i, 2, :]
             planData[self.inames[i] + " big-ticket items"] = self.Lambda_in[i, :]
 

owlplanner/timelists.py

@@ -21,7 +21,7 @@ import pandas as pd
 
 
 # Expected headers in each excel sheet, one per individual.
-timeHorizonItems = [
+_timeHorizonItems = [
     "year",
     "anticipated wages",
     "taxable ctrb",
@@ -59,14 +59,14 @@ def read(finput, inames, horizons, mylog):
             raise Exception(f"Could not read file {finput}: {e}.") from e
         streamName = f"file '{finput}'"
 
-    timeLists = condition(dfDict, inames, horizons, mylog)
+    timeLists = _condition(dfDict, inames, horizons, mylog)
 
     mylog.vprint(f"Successfully read time horizons from {streamName}.")
 
     return finput, timeLists
 
 
-def condition(dfDict, inames, horizons, mylog):
+def _condition(dfDict, inames, horizons, mylog):
     """
     Make sure that time horizons contain all years up to life expectancy,
     and that values are positive (except big-ticket items).
@@ -83,24 +83,24 @@ def condition(dfDict, inames, horizons, mylog):
 
         df = df.loc[:, ~df.columns.str.contains("^Unnamed")]
         for col in df.columns:
-            if col == "" or col not in timeHorizonItems:
+            if col == "" or col not in _timeHorizonItems:
                 df.drop(col, axis=1, inplace=True)
 
-        for item in timeHorizonItems:
+        for item in _timeHorizonItems:
             if item not in df.columns:
                 raise ValueError(f"Item {item} not found for {iname}.")
 
-        # Only consider lines in proper year range.
-        df = df[df["year"] >= thisyear]
+        # 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]
         missing = []
-        for n in range(horizons[i]):
+        for n in range(-5, horizons[i]):
             year = thisyear + n
             if not (df[df["year"] == year]).any(axis=None):
                 df.loc[len(df)] = [year, 0, 0, 0, 0, 0, 0, 0, 0]
                 missing.append(year)
             else:
-                for item in timeHorizonItems:
+                for item in _timeHorizonItems:
                     if item != "big-ticket items" and df[item].iloc[n] < 0:
                         raise ValueError(f"Item {item} for {iname} in year {df['year'].iloc[n]} is < 0.")
 

owlplanner/version.py

@@ -1 +1 @@
-__version__ = "2025.06.03"
+__version__ = "2025.06.21"

{owlplanner-2025.6.3.dist-info → owlplanner-2025.6.21.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owlplanner
-Version: 2025.6.3
+Version: 2025.6.21
 Summary: Owl: Retirement planner with great wisdom
 Project-URL: HomePage, https://github.com/mdlacasse/owl
 Project-URL: Repository, https://github.com/mdlacasse/owl
@@ -837,6 +837,8 @@ which are all tracked separately for married individuals. Asset transition to th
 is done according to beneficiary fractions for each type of savings account.
 Tax status covers married filing jointly and single, depending on the number of individuals reported.
 
+Maturation rules for Roth contributions and conversions are implemented as constraints
+limiting withdrawal amounts to cover Roth account balances for 5 years after the events.
 Medicare and IRMAA calculations are performed through a self-consistent loop on cash flow constraints.
 Future values are simple projections of current values with the assumed inflation rates.
 
@@ -885,7 +887,7 @@ assets to support, even with no estate being left.
 - Streamlit Community Cloud [Streamlit](https://streamlit.io)
 - Contributors: Josh (noimjosh@gmail.com) for Docker image code,
  Dale Seng (sengsational) for great insights and suggestions,
- Robert E. Anderson (NH-RedAnt) for bug fixes and suggestions.
+ Robert E. Anderson (NH-RedAnt) for bug fixes and suggestions, Clark Jefcoat (hubcity) for fruitful interactions.
 
 ---------------------------------------------------------------------
 
@@ -893,8 +895,8 @@ Copyright © 2024 - Martin-D. Lacasse
 
 Disclaimers: This code is for educatonal purposes only and does not constitute financial advice.
 
-Code output has been verified with analytical solutions and other approaches.
-Nevertheless, accuracy of results are not guaranteed.
+Code output has been verified with analytical solutions when applicable, and comparative approaches otherwise.
+Nevertheless, accuracy of results is not guaranteed.
 
 --------------------------------------------------------
 

{owlplanner-2025.6.3.dist-info → owlplanner-2025.6.21.dist-info}/RECORD

@@ -2,13 +2,13 @@ owlplanner/__init__.py,sha256=hJ2i4m2JpHPAKyQLjYOXpJzeEsgcTcKD-Vhm0AIjjWg,592
 owlplanner/abcapi.py,sha256=8VCXS7nH_QZYxCUU3lwO0_UPR9Q5fuYQ6DHDLvHVLPg,6878
 owlplanner/config.py,sha256=onGIMqW2WwB9_CUZauDL6LtHGvc8O1cPUKKcK7Oh70M,12617
 owlplanner/mylogging.py,sha256=RKUr-y-1XvKZzLMcfdtm4IM30LuRpJwb2qUeXmAWqME,2557
-owlplanner/plan.py,sha256=FgQB0kEV5BXsQdFzcVZwukpqJUy1qR2OYP8wS_owtfo,107055
+owlplanner/plan.py,sha256=VVHyKJiooLXXVLiRFJcauZ3oOYU62CCBe4DlpA08P38,109765
 owlplanner/progress.py,sha256=2DOjOLo6Mo7m21wY-9iZhoUksAyi4VCbb6UL2RegNCw,529
 owlplanner/rates.py,sha256=7jXcuHbkJ3AVIeBYZdwme18rdYslIzCuT-c0cLzvKUU,14819
 owlplanner/tax2025.py,sha256=HVYJq8po28jL5Z_il39ZY7qvf2riUEfxio15Zp7TGj8,7890
-owlplanner/timelists.py,sha256=HjoUJQU_ZbfdUy79DefQo5EAXpkfcuG_dOIO9qCljyM,3971
+owlplanner/timelists.py,sha256=95rKYknGMi1bonDVIc3xNmiwG0zTSejKyQy_uWCLSiA,4024
 owlplanner/utils.py,sha256=6Ky8ZKfNE9x--3znsZ8VZaT2PptDinszRxWsOCPanu8,2512
-owlplanner/version.py,sha256=s0nlL6F_JwS9jBAKvGDeVQurTia-o1wmPv43QaJETt4,28
+owlplanner/version.py,sha256=Q6lAE5sS9Y-tuy3jNnv43HcB70y7l1kmDPNzx4CR9tc,28
 owlplanner/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 owlplanner/data/rates.csv,sha256=6fxg56BVVORrj9wJlUGFdGXKvOX5r7CSca8uhUbbuIU,3734
 owlplanner/plotting/__init__.py,sha256=uhxqtUi0OI-QWNOO2LkXgQViW_9yM3rYb-204Wit974,250
@@ -16,7 +16,7 @@ owlplanner/plotting/base.py,sha256=UimGKpMTV-dVm3BX5Apr_Ltorc7dlDLCRPRQ3RF_v7c,2
 owlplanner/plotting/factory.py,sha256=EDopIAPQr9zHRgemObko18FlCeRNhNCoLNNFAOq-X6s,1030
 owlplanner/plotting/matplotlib_backend.py,sha256=AOEkapD94U5hGNoS0EdbRoe8mgdMHH4oOvkXADZS914,17957
 owlplanner/plotting/plotly_backend.py,sha256=AO33GxBHGYG5osir_H1iRRtGxdhs4AjfLV2d_xm35nY,33138
-owlplanner-2025.6.3.dist-info/METADATA,sha256=WhszwtjjNOjd2rfx3QHl6_E52ypcg1DpdJ6JJz3G1vY,53785
-owlplanner-2025.6.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-owlplanner-2025.6.3.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
-owlplanner-2025.6.3.dist-info/RECORD,,
+owlplanner-2025.6.21.dist-info/METADATA,sha256=bZI1gHxPSbxJvJP2DuSqiB6Y33x4tdiVgHlKK73wGD4,54045
+owlplanner-2025.6.21.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+owlplanner-2025.6.21.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+owlplanner-2025.6.21.dist-info/RECORD,,