owlplanner 2025.3.14__tar.gz → 2025.3.16__tar.gz

{owlplanner-2025.3.14 → owlplanner-2025.3.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owlplanner
-Version: 2025.3.14
+Version: 2025.3.16
 Summary: Owl: Retirement planner with great wisdom
 Project-URL: HomePage, https://github.com/mdlacasse/owl
 Project-URL: Repository, https://github.com/mdlacasse/owl

{owlplanner-2025.3.14 → owlplanner-2025.3.16}/docs/owl.tex

@@ -32,6 +32,7 @@
 \begin{document}
 \title{Formulation of the optimization model in Owl}
 \author{Martin-D. Lacasse}
+\date{March 14, 2025}
 \maketitle
 \thispagestyle{fancy}
 \fancyfoot[R]{\copyright\ 2024 - Martin-D. Lacasse}
@@ -87,7 +88,7 @@ index name as a subscript, e.g., $N_i$ for index $i$.
 	More asset classes could be considered at the cost of increasing
 	the complexity of the problem while not generating much more insights.
 \item [$n$]
-	Year being modeled. Period being modeled runs from the beginning of year 0 to 
+	Index of year being modeled. Period being modeled runs from the beginning of year 0 to 
 	the end of year $N_n-1$, and therefore $N_n + 1$ years are considered.
 	Year $N_n$ is the first year following the passing of all
 	individuals in the plan. The time period for all decision variables is annual.
@@ -112,8 +113,8 @@ to take only non-negative values ($\ge 0$ inequality).
 \item [$e_{n}$]
 	Standard exemption for year $n$. This is a variable as the taxable income can
         sometimes be less that the standard exemption $\bar{\sigma}_n$, leading to a
-	negative taxable income if the inflation adjusted standard deviation is simply subtracted
-	from gross taxable income $G_n$.
+	negative taxable income if the inflation-adjusted standard exemption is simply subtracted
+	from the gross taxable income $G_n$.
 \item [$f_{t n}$]
 	Fraction of tax bracket $t$ filled, so that taxable ordinary income $G_n$ can be expressed as
 	\begin{eqnarray}
@@ -141,19 +142,13 @@ For more easily distinguishing parameters from variables, all parameters will be
 or using caligraphic fonts.
 Parameter values are either set by the user, historical data, or by the tax code.
 \begin{description}[leftmargin=4em,style=multiline]
-\item [$\beta{ij}$]
+\item [$\beta_{ij}$]
 	Initial balances in savings accounts. These amounts are used to initialize $b_{ij0}$.
 \item [$\tau_{kn}$]
 	Annual rate of return for asset class $k$ in year $n$.
 	A time series of annual return rates for each class of asset.
 	Here, inflation and the rate of return of $(k=3)$ cash are assumed to be the same.
-	In other words, investing in cash yields constant dollars (just inflation).
-\item[$\mathcal{T}_{ijn}$]
-	When the allocation ratios $\alpha_{ijkn}$ are prescribed,
-	it is more convenient to express the return rates as
-	\begin{equation}
-		\mathcal{T}_{ijn} = \sum_k \alpha_{ijkn} \tau_{kn}.
-	\end{equation}
+	In other words, investing in cash yields constant dollars (return just matches inflation).
 \item [$\gamma_n$]
 	Cumulative inflation at the beginning of year $n$ computed as the product
 	\begin{equation}
@@ -172,12 +167,12 @@ Parameter values are either set by the user, historical data, or by the tax code
 	and can be modified for additional exemptions after 65 of age, for example.
 	It is a simple time series
 	which can include any foreseeable changes in the tax code, or change in filing status due to the
-	passing of one spouse for $n\ge n_d$.  The value of $\bar{\sigma}_n$ is an upper bound for $e_n$.
+	passing of one spouse for $n\ge n_d$.  The value of $\bar{\sigma}_n$ is an upper bound for variable $e_n$.
 \item [$\xi_{n}$]
-	Spending profile. This is a time series that multiplies the desired net spending amount.
+	Spending profile. This is a time series that multiplies a basis for the desired net spending amount.
 	It is $\xi_n =1$ for
 	a flat profile, or can be a {\em smile} profile allowing for more money at the start
-	of retirement. Parameter
+	of retirement and modulating it over retirement. Parameter
 	$\xi_n$ can also contain spending adjustments typically made at the passing of one spouse.
 	The {\em smile} can be implemented using a cosine superimposed over a gentle linear increase
 	such as in
@@ -186,14 +181,14 @@ Parameter values are either set by the user, historical data, or by the tax code
 	\end{equation}
 	and then normalized by factor $N_n/(\sum_n \xi_n )$ to be sum-neutral with respect to a flat profile.
 	Values of $a_1 = 15\%$ and $a_2=12\%$ provide curves that are similar to realistic
-		spending profiles reported in the literature. See Fig.~\ref{Fig:profile} for an example.
+        spending profiles reported in the literature. See Fig.~\ref{Fig:profile} for an example.
 	At the passing of one spouse, both profiles are reduced by a factor $\chi$ for $n \ge n_d$,
 	and the normalizing factor needs to be adjusted accordingly.
-		\begin{figure}[t]
-		\includegraphics{profile.png}
-		\caption{\small Example of a spending profile with 15\% cosine factor and a 12\% linear
-		profile. \label{Fig:profile}}
-		\end{figure}
+	\begin{figure}[t]
+	    \includegraphics{profile.png}
+	    \caption{\small Example of a spending profile with 15\% cosine factor and a 12\% linear
+	    profile. \label{Fig:profile}}
+	\end{figure}
 \item [$\chi$]
 	Factor to reduce spending profile after the passing of one spouse. It is typically
 	assumed to be 0.6.
@@ -230,7 +225,8 @@ Parameter values are either set by the user, historical data, or by the tax code
 	individuals and accounts as $\alpha_{kn}$, for example.
 	When specified by the user, allocation ratios typically involve two values, one at the
 	beginning of the plan $\alpha_{ijk0}$ and the other at the end
-	$\alpha_{ijkN_{n-1}}$. Then, intermediate values are interpolated either using
+	$\alpha_{ijkN_{n-1}}$, or $\alpha_{ijkn_d}$ for a spouse passing before the other.
+        Then, intermediate values are interpolated either using
 	a linear relation,
 \begin{equation}
 	\alpha_{ijkn} = a + \frac{n}{N_n - 1} (b - a),
@@ -280,6 +276,13 @@ or an s-curve as in
 	\end{eqnarray}
 	depending on the scheme selected.
 
+\item[$\mathcal{T}_{ijn}$]
+	When the allocation ratios $\alpha_{ijkn}$ are prescribed,
+	it is more convenient to express the return rates as
+	\begin{equation}
+		\mathcal{T}_{ijn} = \sum_k \alpha_{ijkn} \tau_{kn}.
+	\end{equation}
+
 \item [$\Lambda^\pm_{in}$]
 	Big-ticket item requested by individual $i$ in year $n$.
 	These are large expenses or influx of money
@@ -287,8 +290,8 @@ or an s-curve as in
 	(e.g., sell a house, inheritance) or negative (e.g., buy a house, large gifts).
 \item [$\pi_{in}$]
 	Sum of pension benefits for individual $i$ in year $n$. These amounts are typically
-	specified along with the ages at which these benefits begin. Pensions
-	can optionally be indexed for inflation.
+	specified along with the ages at which these benefits begin.
+	Pensions can optionally be indexed for inflation.
 \item [$\zeta_{in}$]
 	Social security benefits for individual $i$ in year $n$. Starting age and the passing
 	of one individual for spouses will determine the time series. $\bar{\zeta}_{in}$ is
@@ -344,7 +347,8 @@ or an s-curve as in
 	depends on the modified adjusted gross income (MAGI) from 2 years earlier. For the
 	MAGI, we simply use $G_{n-2} + e_{n-2}$ (i.e., gross taxable income
 	plus standard deduction (exemption) from 2 years ago) and ignore the additional IRS
-	rules around tax-free interests which are insignificant in most cases.
+	rules around tax-free interests which are insignificant in most cases. If the plan
+        has individuals above 63 years old, values of MAGI for previous years are requested from the user.
 
 	There are $q=5$ levels
 	of step adjustments adjusted for inflation,
@@ -404,6 +408,7 @@ All intermediate variables are in uppercase letters.
 		[(1-\delta(k, 0))(b_{i0n} - w_{i0n} + d_{in} + .5\kappa_{i0n})\alpha_{i0kn}\tau_{kn}]
 	\end{eqnarray}
 	Social security is indexed for inflation and is assumed to be taxed at 85\%.
+	Pensions can optionally be indexed for inflation.
 	We use a discrete Kronecker $\delta$ function for selecting gains from non-equity assets in
 	taxable accounts. These gains are all taxed as ordinary income. Here, we assumed that
 	withdrawals and deposits in the taxable account are taking place at the beginning of the year, while
@@ -435,24 +440,32 @@ All intermediate variables are in uppercase letters.
 	the taxable savings account is being depleted slowly. An implementation keeping track
 	of stock purchases and sales is beyond the goal of providing a guide for retirement decisions.
 
+\item [$P_n$]
+	Amount of 10\% early withdrawal penalty in year $n$,
+	\begin{equation}
+		\label{Eq:PenTax0}
+		P_n = 0.10 \sum_{i, j\neq0} (1 - \mathcal{H}(n - n_{i,59})) w_{ijn}.
+	\end{equation}
+        Here, $H(n - n_{i, 59})$ is a Heavyside step function which is 0 or 1, depending on the sign of
+        its argument:
+	\begin{equation}
+	\mathcal{H}(x) :=
+	\begin{cases}
+         0 & x < 0 \\
+         1 & x \geq 0.
+	\end{cases}
+	\end{equation}
+        The variable $n_{i, 59}$ is the year index when individual $i$ turns 59,
+	or 0 if already 59 years old or older.
+
 \item [$T_n$]
 	Amount of income tax paid on taxable ordinary income $G_n$ in year $n$.
 	This is the taxes paid on ordinary income expressed as the sum of the amounts
 	paid in each tax bracket as
 	\begin{equation}
 		\label{Eq:IncTax0}
-		T_n = \sum_t f_{tn}\bar{\Delta}_{tn}\theta_{tn} + 0.10 \sum_i (1 - \mathcal{H}(n - n_{i,60})) w_{i1n},
+		T_n = \sum_t f_{tn}\bar{\Delta}_{tn}\theta_{tn}.
 	\end{equation}
-        where $H(n - n_{i, 60})$ is a Heavyside step function which is 0 or 1, depending on the sign of
-        its argument:
-        \[
-	\mathcal{H}(x) \def 	
-	\begin{cases}
-         0 & x < 0 \\
-         1 & x \geq 0. \\
-	\end{cases}
-         \]
-        Here, $n_{i, 60}$ is the year when individual $i$ will turn 60.
 	Notice that $G_n$ is also defined by Eq.~(\ref{Eq:Tx1}), and that optimal
 	values of $f_{tn}$ have to
 	minimize $T_n$ when either the bequest or the desired net spending are maximized.
@@ -463,8 +476,9 @@ All intermediate variables are in uppercase letters.
 	filling in the lower brackets first when optimizing. In that case
 	\begin{equation}
 		\label{Eq:IncTax1}
-		T_n = \sum_t \bar{F}_{tn} \theta_{tn}.
+		T_n = \sum_t \bar{F}_{tn} \theta_{tn}
 	\end{equation}
+
 \item [$U_n$]
 	Amount of income tax paid on long-term capital gains and qualified dividends in year $n$,
 	\begin{equation}
@@ -698,7 +712,7 @@ add the market returns to the savings balances.
 	\begin{eqnarray}
 		g_n = \sum_i [\omega_{in} + \bar{\zeta}_{in} + \pi_{in} ] 
 		+ \sum_{ij} w_{ijn} + \sum_i \Lambda^\pm_{in} - s_{n}
-		- T_n - U_n - \mathcal{M}^\ell_n.
+		- P_n - T_n - U_n - \mathcal{M}^\ell_n.
 	\end{eqnarray}
 	When both spouses are alive, surplus $s_n$ gets deposited in the taxable accounts
 	according to variable $\eta$ as described in Eq.~(\ref{Eq:eta}),
@@ -712,7 +726,7 @@ add the market returns to the savings balances.
 	Replacing intermediate variables and bringing all variables to the left-hand side, we get
 	\begin{eqnarray}
 		\label{Eq:C4}
-		g_n - \sum_{ij} w_{ijn} + s_{n}
+		g_n - \sum_{ij} w_{ijn} + 0.1 \sum_{i,j\neq0} (1-\mathcal{H}(n - n_{i, 59})) w_{ijn} + s_n
 		+ \sum_t \bar{F}_{tn} \theta_{t n} &&\nonumber \\
 		+ \psi\alpha_{i00n} \sum_{i} \left[\mu(b_{i0n} - w_{i0n} + d_{in})
 		+ w_{i0n}\max(0, \tau_{0n-1})\right] 
@@ -1020,7 +1034,7 @@ For the equality constraint on net spending expressed in Eq.~(\ref{Eq:C4}),
 we add $N_n$ more rows to $A_ey = v$ as
 \begin{eqnarray}
 	A_e[J_2(n), q_g(n)] &=& 1, \nonumber \\
-	A_e[J_2(n), q_w(i, j ,n)] &=& -1 + \delta(j, 0)\psi\alpha_{i00n}(\max(0, \tau_{0n-1}) - \mu), \nonumber \\
+	A_e[J_2(n), q_w(i, j ,n)] &=& -1 + .1(1-\delta(j, 0))(1-\mathcal{H}(n-n_{i, 59})) + \delta(j, 0)\psi\alpha_{i00n}(\max(0, \tau_{0n-1}) - \mu), \nonumber \\
 	A_e[J_2(n), q_d(i, n)] &=& 1 + \psi\mu\alpha_{i00n}, \nonumber \\
 	A_e[J_2(n), q_F(t, n)] &=& \theta_{t n}, \nonumber \\
 	A_e[J_2(n), q_b(i, 0, n)] &=& \psi\mu\alpha_{i00n}, \nonumber \\

{owlplanner-2025.3.14 → owlplanner-2025.3.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "owlplanner"
-version = "2025.03.14"
+version = "2025.03.16"
 authors = [
   { name="Martin-D. Lacasse", email="martin.d.lacasse@gmail.com" },
 ]

{owlplanner-2025.3.14 → owlplanner-2025.3.16}/src/owlplanner/plan.py

@@ -1284,19 +1284,15 @@ class Plan(object):
                 # Minus capital gains on taxable withdrawals using last year's rate if >=0.
                 # Plus taxable account withdrawals, and all other withdrawals.
                 row.addElem(_q3(Cw, i, 0, n, Ni, Nj, Nn), fac * (tau_0prev[n] - self.mu) - 1)
-                row.addElem(_q3(Cw, i, 1, n, Ni, Nj, Nn), -1)
-                row.addElem(_q3(Cw, i, 2, n, Ni, Nj, Nn), -1)
+                penalty = 0.1 if n < self.n59[i] else 0
+                row.addElem(_q3(Cw, i, 1, n, Ni, Nj, Nn), -1 + penalty)
+                row.addElem(_q3(Cw, i, 2, n, Ni, Nj, Nn), -1 + penalty)
                 row.addElem(_q2(Cd, i, n, Ni, Nn), fac * self.mu)
 
             # Minus tax on ordinary income, T_n.
             for t in range(Nt):
                 row.addElem(_q2(CF, t, n, Nt, Nn), self.theta_tn[t, n])
 
-            # Minus 10% penalty on early withdrawals.
-            if n < self.n59[i]:
-                row.addElem(_q3(Cw, i, 1, n, Ni, Nj, Nn), 0.1)
-                row.addElem(_q3(Cw, i, 2, n, Ni, Nj, Nn), 0.1)
-
             A.addRow(row, rhs, rhs)
 
         # Impose income profile.
@@ -1978,12 +1974,12 @@ class Plan(object):
         self.G_n = np.sum(self.F_tn, axis=0)
         self.T_tn = self.F_tn * self.theta_tn
         self.T_n = np.sum(self.T_tn, axis=0)
-        self.penalty_n = np.zeros(Nn)
-        # Add early withdrawal penalties if any.
+        self.P_n = np.zeros(Nn)
+        # Add early withdrawal penalty if any.
         for i in range(Ni):
-            self.penalty_n[0:self.n59[i]] += 0.1*(self.w_ijn[i, 1, 0:self.n59[i]] + self.w_ijn[i, 2, 0:self.n59[i]])
+            self.P_n[0:self.n59[i]] += 0.1*(self.w_ijn[i, 1, 0:self.n59[i]] + self.w_ijn[i, 2, 0:self.n59[i]])
 
-        self.T_n += self.penalty_n
+        self.T_n += self.P_n
 
         tau_0 = np.array(self.tau_kn[0, :])
         tau_0[tau_0 < 0] = 0
@@ -2126,8 +2122,8 @@ class Plan(object):
             dic[f"-- Subtotal in tax bracket {tname}"] = f"{u.d(taxPaidNow)}"
             dic[f"-- [Subtotal in tax bracket {tname}]"] = f"{u.d(taxPaid)}"
 
-        penaltyPaid = np.sum(self.penalty_n, axis=0)
-        penaltyPaidNow = np.sum(self.penalty_n / self.gamma_n[:-1], axis=0)
+        penaltyPaid = np.sum(self.P_n, axis=0)
+        penaltyPaidNow = np.sum(self.P_n / self.gamma_n[:-1], axis=0)
         dic["-- Subtotal in early withdrawal penalty"] = f"{u.d(penaltyPaidNow)}"
         dic["-- [Subtotal in early withdrawal penalty]"] = f"{u.d(penaltyPaid)}"
 

{owlplanner-2025.3.14 → owlplanner-2025.3.16}/src/owlplanner/rates.py

@@ -110,6 +110,9 @@ def getRatesDistributions(frm, to, mylog=None):
     # Build correlation matrix by dividing by the stdev for each column and row.
     corr = covar / stdev[:, None]
     corr = corr.T / stdev[:, None]
+    # Fold round-off errors in proper bounds.
+    corr[corr > 1] = 1
+    corr[corr < -1] = -1
     mylog.print("correlation matrix: \n\t\t%s" % str(corr).replace("\n", "\n\t\t"))
 
     return means, stdev, corr, covar

owlplanner-2025.3.16/src/owlplanner/version.py

@@ -0,0 +1 @@
+__version__ = "2025.03.16"

{owlplanner-2025.3.14 → owlplanner-2025.3.16}/ui/requirements.txt

@@ -7,4 +7,4 @@ scipy
 streamlit
 toml
 # --extra-index-url https://test.pypi.org/simple
-owlplanner >= 2025.03.14
+owlplanner >= 2025.03.16

owlplanner-2025.3.14/src/owlplanner/version.py

@@ -1 +0,0 @@
-__version__ = "2025.03.14"