owlplanner 2025.2__tar.gz → 2025.2.2__tar.gz

{owlplanner-2025.2 → owlplanner-2025.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owlplanner
-Version: 2025.2
+Version: 2025.2.2
 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.2 → owlplanner-2025.2.2}/pyproject.toml

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

{owlplanner-2025.2 → owlplanner-2025.2.2}/src/owlplanner/plan.py

@@ -859,12 +859,12 @@ class Plan(object):
 
                 'year',
                 'anticipated wages',
-                'ctrb taxable',
-                'ctrb 401k',
-                'ctrb Roth 401k',
-                'ctrb IRA',
-                'ctrb Roth IRA',
-                'Roth X',
+                'taxable ctrb',
+                '401k ctrb',
+                'Roth 401k ctrb',
+                'IRA ctrb',
+                'Roth IRA ctrb',
+                'Roth conv',
                 'big-ticket items'
 
         in any order. A template is provided as an example.
@@ -890,12 +890,12 @@ class Plan(object):
         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]['ctrb taxable'].iloc[:h]
-            self.kappa_ijn[i, 1, :h] = self.timeLists[iname]['ctrb 401k'].iloc[:h]
-            self.kappa_ijn[i, 2, :h] = self.timeLists[iname]['ctrb Roth 401k'].iloc[:h]
-            self.kappa_ijn[i, 1, :h] += self.timeLists[iname]['ctrb IRA'].iloc[:h]
-            self.kappa_ijn[i, 2, :h] += self.timeLists[iname]['ctrb Roth IRA'].iloc[:h]
-            self.myRothX_in[i, :h] = self.timeLists[iname]['Roth X'].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]
 
         #  In 1st year, reduce wages and contribution depending on starting date.
@@ -947,8 +947,8 @@ class Plan(object):
         self.myRothX_in[:, :] = 0.
         self.kappa_ijn[:, :, :] = 0.
 
-        cols = ['year', 'anticipated wages', 'ctrb taxable', 'ctrb 401k',
-                'ctrb Roth 401k', 'ctrb IRA', 'ctrb Roth IRA', 'Roth X', 'big-ticket items']
+        cols = ['year', 'anticipated wages', 'taxable ctrb', '401k ctrb',
+                'Roth 401k ctrb', 'IRA ctrb', 'Roth IRA ctrb', 'Roth conv', 'big-ticket items']
         for i, iname in enumerate(self.inames):
             h = self.horizons[i]
             df = pd.DataFrame(0, index=np.arange(h), columns=cols)
@@ -1993,8 +1993,8 @@ class Plan(object):
             'wages',
             'ssec',
             'pension',
-            'dist',
-            'rmd',
+            '+dist',
+            'RMD',
             'RothX',
             'wdrwl taxable',
             'wdrwl tax-free',
@@ -2004,12 +2004,12 @@ class Plan(object):
         sources['wages'] = self.omega_in
         sources['ssec'] = self.zetaBar_in
         sources['pension'] = self.pi_in
-        sources['wdrwl taxable'] = self.w_ijn[:, 0, :]
-        sources['rmd'] = self.rmd_in
-        sources['dist'] = self.dist_in
+        sources['txbl acc wdrwl'] = self.w_ijn[:, 0, :]
+        sources['RMD'] = self.rmd_in
+        sources['+dist'] = self.dist_in
         sources['RothX'] = self.x_in
-        sources['wdrwl tax-free'] = self.w_ijn[:, 2, :]
-        sources['bti'] = self.Lambda_in
+        sources['tax-free wdrwl'] = self.w_ijn[:, 2, :]
+        sources['BTI'] = self.Lambda_in
 
         savings = {}
         savings['taxable'] = self.b_ijn[:, 0, :]
@@ -2719,7 +2719,7 @@ class Plan(object):
             'all wages': np.sum(self.omega_in, axis=0),
             'all pensions': np.sum(self.pi_in, axis=0),
             'all soc sec': np.sum(self.zetaBar_in, axis=0),
-            "all bti's": np.sum(self.Lambda_in, axis=0),
+            "all BTI's": np.sum(self.Lambda_in, axis=0),
             'all wdrwls': np.sum(self.w_ijn, axis=(0, 1)),
             'all deposits': -np.sum(self.d_in, axis=0),
             'ord taxes': -self.T_n,
@@ -2735,12 +2735,12 @@ class Plan(object):
             'wages': self.sources_in['wages'],
             'social sec': self.sources_in['ssec'],
             'pension': self.sources_in['pension'],
-            'txbl acc wdrwl': self.sources_in['wdrwl taxable'],
-            'RMDs': self.sources_in['rmd'],
-            '+distributions': self.sources_in['dist'],
-            'Roth conversion': self.sources_in['RothX'],
-            'tax-free wdrwl': self.sources_in['wdrwl tax-free'],
-            'big-ticket items': self.sources_in['bti'],
+            'txbl acc wdrwl': self.sources_in['txbl acc wdrwl'],
+            'RMDs': self.sources_in['RMD'],
+            '+distributions': self.sources_in['+dist'],
+            'Roth conv': self.sources_in['RothX'],
+            'tax-free wdrwl': self.sources_in['tax-free wdrwl'],
+            'big-ticket items': self.sources_in['BTI'],
         }
 
         for i in range(self.N_i):
@@ -2751,13 +2751,14 @@ class Plan(object):
         # Account balances except final year.
         accDic = {
             'taxable bal': self.b_ijn[:, 0, :-1],
+            'taxable ctrb': self.kappa_ijn[:, 0, :],
             '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 wdrwl': self.w_ijn[:, 1, :],
             '(included RMDs)': self.rmd_in[:, :],
-            'Roth conversion': self.x_in,
+            'Roth conv': self.x_in,
             'tax-free bal': self.b_ijn[:, 2, :-1],
             'tax-free ctrb': self.kappa_ijn[:, 2, :],
             'tax-free wdrwl': self.w_ijn[:, 2, :],
@@ -2856,7 +2857,7 @@ class Plan(object):
             planData[self.inames[i] + ' tx-def ctrb'] = self.kappa_ijn[i, 1, :]
             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 conversion'] = self.x_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] + ' tax-free wdrwl'] = self.w_ijn[i, 2, :]

{owlplanner-2025.2 → owlplanner-2025.2.2}/src/owlplanner/timelists.py

@@ -23,12 +23,12 @@ import pandas as pd
 timeHorizonItems = [
     'year',
     'anticipated wages',
-    'ctrb taxable',
-    'ctrb 401k',
-    'ctrb Roth 401k',
-    'ctrb IRA',
-    'ctrb Roth IRA',
-    'Roth X',
+    'taxable ctrb',
+    '401k ctrb',
+    'Roth 401k ctrb',
+    'IRA ctrb',
+    'Roth IRA ctrb',
+    'Roth conv',
     'big-ticket items',
 ]
 
@@ -38,8 +38,8 @@ def read(finput, inames, horizons, mylog):
     Read listed parameters from an excel spreadsheet or through
     a dictionary of dataframes through Pandas.
     Use one sheet for each individual with the following 9 columns:
-    year, anticipated wages, ctrb taxable, ctrb 401k, ctrb Roth 401k,
-    ctrb IRA, ctrb Roth IRA, Roth X, and big-ticket items.
+    year, anticipated wages, taxable ctrb, 401k ctrb, Roth 401k ctrb,
+    IRA ctrb, Roth IRA ctrb, Roth conv, and big-ticket items.
     Supports xls, xlsx, xlsm, xlsb, odf, ods, and odt file extensions.
     Returs a dictionary of dataframes by individual's names.
     """

owlplanner-2025.2.2/src/owlplanner/version.py

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

{owlplanner-2025.2 → owlplanner-2025.2.2}/ui/About_Owl.py

@@ -7,8 +7,7 @@ import owlbridge as owb
 st.write("## About Owl 🦉")
 kz.orangeDivider()
 
-st.write("This version of Owl was released in January 2025 (version %s). "
-         "Running on Streamlit %s." % (owb.version(), st.__version__))
+st.write("This is Owl version %s running on Streamlit %s." % (owb.version(), st.__version__))
 st.snow()
 
 st.write('''
@@ -36,7 +35,8 @@ Copyright © 2024 - Martin-D. Lacasse
 
 #### :orange[Privacy]
 - This app does not store or forward any information. All data entered is lost
-after a session is closed.
+after a session is closed. However, you can choose to download selected data to your own
+computer before closing the session.
 Source code is publicly available and can be inspected in the repository.
 
 #### :orange[Disclaimers]

{owlplanner-2025.2 → owlplanner-2025.2.2}/ui/Case_Results.py

@@ -38,7 +38,7 @@ else:
                 data=owb.saveCaseFile(),
                 file_name=fileName,
                 disabled=kz.caseHasNotCompletedRun(),
-                mime='txt/plain'
+                mime='application/toml'
             )
         with col2:
             download2 = st.download_button(

{owlplanner-2025.2 → owlplanner-2025.2.2}/ui/Documentation.py

@@ -105,7 +105,11 @@ how to split potential surplus budget moneys between the taxable accounts of the
 When the `Beneficiary fractions` are not all 1, it is recommended to deposit all
 surplus moneys in the taxable account of the first individual to pass. Otherwise,
 the optimizer will find creative solutions that can generate surpluses in order
-to maximize the final bequest.
+to maximize the final bequest. Finally, when fractions are not all equal,
+it can take longer to solve (minutes) as these cases trigger the use
+of binary variables which involve more complex algorithms.
+In some situations, transfers from tax-deferred savings accounts to taxable
+savings accounts, through surpluses and deposits, can be part of the optimal solution.
 
 Setting a surplus fraction that deposits all surpluses in the survivor's account
 can lead to slow convergence. This is especially noticeable when solving with
@@ -124,7 +128,7 @@ The wages and contributions data contains 9 columns titled as follows:
 
 # <span style="font-size: 10px;"> </span>
 st.write('''
-|year|anticipated wages|ctrb taxable|ctrb 401k|ctrb Roth 401k|ctrb IRA|ctrb Roth IRA|Roth X|big-ticket items|
+|year|anticipated wages|ctrb taxable|ctrb 401k|ctrb Roth 401k|ctrb IRA|ctrb Roth IRA|Roth conv|big-ticket items|
 |--|--|--|--|--|--|--|--|--|
 |2025 | | | | | | | | |
 |2026 | | | | | | | | |
@@ -158,7 +162,7 @@ of the anticipated wages for contributions as this can sometimes be easier. For
 purpose, additional columns (on the right) can be used for storing the anticipated total salary and
 to derive relevant numbers from there. These columns will be ignored when the file is processed.
 
-Roth conversion can be specified in the column marked *Roth X*.
+Roth conversion can be specified in the column marked *Roth conv*.
 This column is provided to override the Roth conversion optimization in Owl. When the option
 `Convert as in contribution file` is toggled in the [Optimization Parameters](#optimization-parameters) page,
 values from the contributions file will be used and no optimization over Roth conversions
@@ -303,6 +307,8 @@ Each table can be downloaded separately in csv format, or all tables can be down
 together as an Excel workbook by clicking the button at the bottom
 of the page.
 Note that all values here (worksheets and workbook) are in \\$, not in thousands.
+The first line of the *Sources* worksheets are the most important
+as these lines are the only ones that are actionable.
 
 #### Case Summary
 This page shows a summary of the scenario which was computed.
@@ -347,15 +353,16 @@ when considering Monte Carlo simulations, consider:
 --------------------------------------------------------------------------------------
 ### :orange[Resources]
 #### Logs
-Messages coming from the underlying Owl calculation engine are displayed under this page.
+Messages coming from the underlying Owl calculation engine are displayed on this page.
 
 #### Settings
-This page contains a global setting for choosing the display style used for the graphs. Some color
+This page contains global settings. At the current time, there is only a single
+option for choosing the style used for the graphs. Some color
 schemes are best suited for colorblind individuals. The *classic* offers good contrast, while
-*petroff10* has more distinguishing colors.
+*petroff10* presents other distinguishing colors.
 
 #### Documentation
-These pages.
+These very pages.
 
 #### About Owl
 Credits and disclaimers.

{owlplanner-2025.2 → owlplanner-2025.2.2}/ui/Quick_Start.py

@@ -11,36 +11,38 @@ with col1:
     kz.orangeDivider()
     st.write('### Quick Start')
     st.markdown('''
-Owl uses two files to store the specifications of a case so that it can be recalled at a later time.
+Owl does not store any information related to a case:
+all is lost after a session is closed. For that reason,
+two files can be used to store the specifications of a case so that it can be recalled at a later time.
 - A *case* parameter file
-specifies account balances, asset allocation, social security and pension, rates,
+specifying account balances, asset allocation, social security and pension, rates,
 optimization parameters and related assumptions.
 This file is in *toml* format which is editable with a simple text editor.
-- A *wages and contributions* file contains a
-time table describing anticipated wages, future contributions
+- A *wages and contributions* file containing a
+time table with anticipated wages, future contributions
 to savings accounts, and anticipated big-ticket items, which can be either expenses or income.
 This file is in Excel or LibreOffice format, and has one tab per individual in the plan.
 
-With these two files, a scenario can be solved in only a few steps. We will use the case
+With these two files, a scenario can be created and solved in only a few steps. We will use the case
 of Jack and Jill provided here as an example:
-1) Download these two files from the repository:
+1) Download these two files from the GitHub repository:
     - Case parameter file named
     [case_jack+jill.toml](https://raw.github.com/mdlacasse/Owl/main/examples/case_jack+jill.toml)
     in editable *toml* format.
     - Wages and contributions file named
     [jack+jill.xlsx](https://raw.github.com/mdlacasse/Owl/main/examples/jack+jill.xlsx)
     in Excel format.
-1) Navigate to the ***Basic Info*** page and drag and drop the case parameter file
+1) Navigate to the **Basic Info** page and drag and drop the case parameter file
 you just downloaded (*case_jack+jill.toml*).
-1) Navigate to the ***Wages and Contributions*** page and
+1) Navigate to the **Wages and Contributions** page and
 drag and drop the wages and contributions file you downloaded (*jack+jill.xlsx*).
-1) Move to the ***Case Results*** page and click on the `Run single case` button.
+1) Move to the **Case Results** page and click on the `Run single case` button.
 
 Congratulations! :balloon: You just ran your first case. You can now explore each page and
 experiment with different parameters.
 
 For creating your own cases, you can start
-from scratch by selecting `New Case...` in the selection box while on the ***Basic Info*** page,
+from scratch by selecting `New Case...` in the selection box while on the **Basic Info** page,
 and fill in the information needed on each page of the `Case Setup` section.
 Once a case has been fully parameterized and successfully optimized,
 it can then be saved as a parameter file
@@ -52,5 +54,5 @@ the `Duplicate case` button, and then edit its values to fit your situation.
 Multiple cases can coexist and can be called using the `Select case` box
 at the bottom of the margin.
 
-More information can be found on the :material/help: ***Documentation*** page located in the **Resources** section.
+More information can be found on the :material/help: **Documentation** page located in the **Resources** section.
 ''')

{owlplanner-2025.2 → owlplanner-2025.2.2}/ui/owlbridge.py

@@ -103,6 +103,8 @@ def prepareRun(plan):
     plan.setLongTermCapitalTaxRate(kz.getKey('gainTx'))
     plan.setDividendRate(kz.getKey('divRate'))
 
+    setInterpolationMethod()
+    setAllocationRatios()
     setRates()
     setContributions()
 

{owlplanner-2025.2 → owlplanner-2025.2.2}/ui/requirements.txt

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

{owlplanner-2025.2 → owlplanner-2025.2.2}/ui/sskeys.py

@@ -186,8 +186,6 @@ def duplicateCase():
     ss.cases[dupname]['duplicate'] = True
     refreshCase(ss.cases[dupname])
     ss.currentCase = dupname
-    # resetTimeLists()
-    # print(dupname, '->', ss.cases[dupname])
 
 
 def createCaseFromFile(confile):

owlplanner-2025.2/src/owlplanner/version.py

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