owlplanner 2025.2.2__tar.gz → 2025.2.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owlplanner
-Version: 2025.2.2
+Version: 2025.2.3
 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.2 → owlplanner-2025.2.3}/notebooks/template.ipynb

@@ -211,7 +211,7 @@
     "The most manageable part of retirement planning is the control one has over work income, contributions to savings accounts, Roth conversions, and other big spending items in the near- and mid-term future.\n",
     "In order to execute a realization, one must provide an earning, saving, and Roth conversion plan. This is done through providing an Excel workbook with one spreadsheet (tab) per spouse with the following information:\n",
     "\n",
-    "|year|anticipated wages|ctrb taxable | ctrb 401k | ctrb Roth 401k | ctrb IRA | ctrb Roth IRA | Roth X | big-ticket items|\n",
+    "|year|anticipated wages|taxable ctrb| 401k ctrb | Roth 401k ctrb | IRA ctrb | Roth IRA ctrb | Roth conv | big-ticket items|\n",
     "|--|--|--|--|--|--|--|--|--|\n",
     "|2024 | | | | | | | | |\n",
     "|2025 | | | | | | | | |\n",
@@ -224,7 +224,7 @@
     "\n",
     "Contributions to your savings accounts are marked as *ctrb*. Contributions to your 401k must also include your employer's contributions, if any. As this file is in Excel, one can use the native calculator to enter a percentage of the anticipated wages for contributions as this can sometimes be easier. Considering a specific example, assume that Jack earns 100k\\\\$ and contributes 5% to his 401k which his employer matches at up to 4%, then Jack's anticipated wages will be $(1-.05)*100000 = 95000$ and his 401k contributions will be $.09/(1 - .05) * 95000 = 9000 $. \n",
     "\n",
-    "Roth conversion are specified in the column marked *Roth X*. Roth conversion are typically performed in the years when the income is lower (and therefore lower tax rates), typically in the bridge years between having a full-time regular salary and collecting social security. This column is provided to override the Roth conversion optimization in Owl. When the solver is given the option `maxConversion='file'`, then these values will be used and no optimization over Roth conversions will be performed. This column is provided for flexibility and allowing comparisons.\n",
+    "Roth conversion are specified in the column marked *Roth conv*. Roth conversion are typically performed in the years when the income is lower (and therefore lower tax rates), typically in the bridge years between having a full-time regular salary and collecting social security. This column is provided to override the Roth conversion optimization in Owl. When the solver is given the option `maxConversion='file'`, then these values will be used and no optimization over Roth conversions will be performed. This column is provided for flexibility and allowing comparisons.\n",
     "\n",
     "Finally, *big-ticket items* are used for accounting for the sale or purchase of a house, or any other major expense or money that you would give or receive (e.g., inheritance, or large gifts to or from you). Therefore, the sign (+/-) of entries in this column is important. Positive numbers will be considered in the cash flow for the year and surplus will be deposited in taxable savings accounts. Negative numbers will generate withdrawals and distributions from retirement accounts. This is the only column that can contain negative numbers: all other column entries should be positive.\n",
     "\n",

{owlplanner-2025.2.2 → owlplanner-2025.2.3}/notebooks/tutorial_1.ipynb

@@ -208,7 +208,7 @@
     "The most manageable part of retirement planning is the control one has over work income, contributions to savings accounts, Roth conversions, and other big spending items in the near- and mid-term future.\n",
     "In order to execute a realization, one must provide an earning, saving, and optionally a Roth conversion plan for overriding the optimizer. This is done through providing an Excel workbook with one spreadsheet (tab) per spouse with the following information:\n",
     "\n",
-    "|year|anticipated wages|ctrb taxable | ctrb 401k | ctrb Roth 401k | ctrb IRA | ctrb Roth IRA | Roth X | big-ticket items|\n",
+    "|year|anticipated wages|taxable ctrb | 401k ctrb | Roth 401k ctrb | IRA ctrb | Roth IRA ctrb | Roth conv | big-ticket items|\n",
     "|--|--|--|--|--|--|--|--|--|\n",
     "|2024 | | | | | | | | |\n",
     "|2025 | | | | | | | | |\n",
@@ -221,7 +221,7 @@
     "\n",
     "Contributions to your savings accounts are marked as *ctrb*. We use 401k as a term which includes contributions to 403b as well. Contributions to your 401k/403b must also include your employer's contributions, if any. As this file is in Excel, one can use the native calculator to enter a percentage of the anticipated wages for contributions as this can sometimes be easier. Considering a specific example, assume that Jack earns 100k\\\\$ and contributes 5% to his 401k which his employer matches at up to 4%, then Jack's anticipated wages will be $(1-.05)*100000 = 95000$ and his 401k contributions will be $.09/(1 - .05) * 95000 = 9000 $. The reason for using $95000$ in the last equation allows for making cross-reference between the cells, as the number 100k\\\\$ will not appear directly. Another approach could be to use an additional column with for the total salary and derive numbers from there.\n",
     "\n",
-    "Roth conversion are specified in the column marked *Roth X*. Roth conversion are typically performed in the years when the income is lower (and therefore lower tax rates), typically in the bridge years between having a full-time regular salary and collecting social security. This column is provided to override the Roth conversion optimization in Owl. When the solver is given the option `maxConversion='file'`, then these values will be used and no optimization over Roth conversions will be performed. This column is provided for flexibility and allowing comparisons between an optimized solution and your best guess.\n",
+    "Roth conversion are specified in the column marked *Roth conv*. Roth conversion are typically performed in the years when the income is lower (and therefore lower tax rates), typically in the bridge years between having a full-time regular salary and collecting social security. This column is provided to override the Roth conversion optimization in Owl. When the solver is given the option `maxConversion='file'`, then these values will be used and no optimization over Roth conversions will be performed. This column is provided for flexibility and allowing comparisons between an optimized solution and your best guess.\n",
     "\n",
     "Finally, *big-ticket items* are used for accounting for the sale or purchase of a house, or any other major expense or money that you would give or receive (e.g., inheritance, or large gifts to or from you). Therefore, the sign (+/-) of entries in this column is important. Positive numbers will be considered in the cash flow for the year and surplus, if any, will be deposited in the taxable savings accounts. Negative numbers will potentially generate additional withdrawals and distributions from retirement accounts. This is the only column that can contain negative numbers: all other column entries should be positive.\n",
     "\n",

{owlplanner-2025.2.2 → owlplanner-2025.2.3}/pyproject.toml

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

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

@@ -2781,6 +2781,7 @@ class Plan(object):
                 self.b_ijn[i][2][-1],
                 0,
                 0,
+                0,
             ]
             ws.append(lastRow)
             _formatSpreadsheet(ws, 'currency')

owlplanner-2025.2.3/src/owlplanner/version.py

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

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

@@ -10,7 +10,7 @@ kz.caseHeader("Case Results")
 if ret is None or kz.caseHasNoPlan():
     st.info('Case(s) must be first created before running this page.')
 else:
-    st.write("Optimize a single scenario based on the parameters selected in the *Case setup* section.")
+    st.write("Optimize a single scenario based on the parameters selected in the **Case setup** section.")
     col1, col2 = st.columns(2, gap='large', vertical_alignment='bottom')
     with col1:
         choices = ['nominal', 'today']

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

@@ -21,7 +21,7 @@ It provides different realizations of a financial strategy through the rigorous
 mathematical optimization of relevant decision variables. Using a linear programming approach,
 two different objectives can currently be optimized: either
 maximize the net spending amount under the constraint of a desired bequest,
-or maximize an after-tax bequest under the consraint of a desired net spending amount.
+or maximize an after-tax bequest under the constraint of a desired net spending amount.
 In each case, Roth conversions are optimized to reduce the tax burden,
 while federal income tax and Medicare premiums (including IRMAA) are calculated.
 A full description of the package can be found on the GitHub
@@ -36,11 +36,11 @@ Typically, pages would be accessed in order, starting from the top.
 The `Select case` selection box at the bottom of the margin allows to select an existing case
 or create a new one from scratch, or from a *case* parameter file, which
 would then populate all parameter values.
-This box is present in all pages except those in the `Resources` section
+This box is present in all pages except those in the **Resources** section
 and allows to compare different scenarios.
 
 There are four sections in the user interface:
-`Case Setup`, `Single Scenario`, `Multiple Scenarios`, and `Resources`.
+**Case Setup**, **Single Scenario**, **Multiple Scenarios**, and **Resources**.
 
 -------------------------------------------------
 ### :orange[Case Setup]
@@ -58,7 +58,7 @@ and life expectancies are required. A starting date for the plan determines when
 starts in the first year. Plan still ends at the end of the year when all individuals
 have passed according to the specified life expectancies.
 
-When duplicating a scenario, make sure to visit all pages in the `Case Setup` section
+When duplicating a scenario, make sure to visit all pages in the **Case Setup** section
 and verify that all parameters are as intended.
 
 ##### Initializing the life parameters for the realization
@@ -111,9 +111,9 @@ 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
-varying rates, and not so common when using fixed rates.
+Setting a surplus fraction that deposits some or all surpluses in the survivor's account
+can sometimes lead to slow convergence. This is especially noticeable when solving with
+varying rates and not so common when using fixed rates.
 This is due to the triggering of binary variables which add
 considerable computing effort in solving the problem.
 When using varying rates, it is recommended to set surpluses to be
@@ -178,7 +178,7 @@ withdrawals and distributions from retirement accounts. This is the only column
 negative numbers: all other column entries should be positive.
 
 When loading an Excel workbook, each individual in the plan must have an associated sheet
-for reporting yearly transations affecting the plan. The association is made by having
+for reporting yearly transactions affecting the plan. The association is made by having
 the individual's name as the sheet name in the workbook.
 Therefore, if preparing your own case using a template, you will need to rename the tabs in the file to
 match the names used when creating the plan
@@ -207,7 +207,7 @@ There are two major types of rates:
     - *user* - rates are provided by the user
 - *Varying rates* - changing from year to year
     - *historical* - using a rate sequence which happened in the past
-    - *histochastic* - using stochastic rates derived from statistics of historical rates
+    - *histochastic* - using stochastic rates derived from statistics over a time range of historical rates
     - *stochastic* - using stochastic rates created from statistical parameters specified by the user.
 
 These rates are the annual rates of return for each of the assets considered. The types of asset are described
@@ -231,24 +231,24 @@ to a *final* allocation ratio at the passing of the individual.
 It is assumed that the accounts are regularly
 rebalanced to maintain the prescribed allocation ratios.
 
-An gliding function (either *linear* or an *s-curve*) interpolates the values
+A gliding function (either *linear* or an *s-curve*) interpolates the values
 of the allocation ratios from the *initial* values to the *final* values as the plan progresses in time.
 When an *s-curve* is selected, two additional parameters controlling the shape of the transition
 will appear, one for the timing of the inflection point measured in years from now,
 and the other for the width of the transition, measured in +/- years from the inflection point.
 
 ### Optimization Parameters
-This page allows you to select the problem to optimize.
+This page allows you to select the objective to optimize.
 One can choose between maximizing the net spending amount subject to the constraint
 of a desired bequest, or maximizing a bequest, subject to the constraint of providing
 a desired net spending amount.
 As one of the two choices (net spending or bequest) is selected as the value to maximize,
 the other becomes a constraint to obey.
 
-Maximum amount for Roth conversions and who can execute them need to be
-specified. If a contribution file has been uploaded and the `Convert from contributions file`
-is toggled, Roth conversions will not be optimized, but will rather be performed according to
-the column `RothX` found in the
+The maximum amount for Roth conversions and who can execute them is configurable.
+If a *Wages and Contributions* file has been uploaded and the `Convert from contributions file`
+button is toggled, Roth conversions will not be optimized, but will rather be performed according to
+the `Roth conv` column on the
 [Wages and Contributions](#wages-and-contributions) page.
 
 Calculations of Medicare and IRMAA can be turned on or off. This will typically speed up
@@ -257,7 +257,7 @@ If the age of individuals makes them eligible for Medicare within the next two y
 additional cells will appear for entering the Modified Adjusted Gross Income (MAGI) for past years.
 These numbers are needed to calculate the Income-Related Monthly Adjusted Amounts (IRMAA).
 
-The time profile of the net spending amount
+The time profile modulating the net spending amount
 can be selected to either be *flat* or follow a *smile* shape.
 The smile shape has three configurable parameters: a *dip* percentage
 a linear *increase*, or *decrease if negative, over the time period (apart from inflation),
@@ -265,9 +265,9 @@ and a time delay, in years from today, before the non-flat behavior starts to ac
 Values default to 15%, 12%, and 0 year respectively, but they are fully configurable
 for experimentation and to fit your anticipated lifestyle.
 
-For married couples, a survivor's
+For married couples, the survivor's
 net spending percentage is also configurable. A value of 60% is typically used.
-The selected profile curve multiplies
+The selected profile multiplies
 the net spending *basis* which sets the resulting spending
 amounts over the duration of the plan.
 Notice that *smile* curves are re-scaled to have the same total spending as flat curves:
@@ -282,16 +282,16 @@ than on January 1$^{st}$, the value of the first year will be reduced accordingl
 This page allows to run a single scenario based on the selections made
 in the [Case Setup](#case-setup) section.
 This simulation uses a single instance of a series of rates, either fixed or varying,
-as previously selected.
+as selected in the **Case Setup** section.
 The outcome is optimized according to the chosen parameters: either maximize the
 net spending, of maximize the bequest under the constraint of a net spending amount.
 If `Convert from contributions file` is not toggled on,
-Roth conversions are optimized for maximizing the selected objective function.
+Roth conversions are optimized for reducing taxes and maximizing the selected objective function.
 Various plots show the results, which can be displayed in today's \\$ or
 in nominal value.
 
 When a case has run successfully, different graphs will show the time evolution
-of different quatities over the duration of the plan. Below
+of different quantities over the duration of the plan. Below
 these graphs, two additional buttons will appear. The
 `Download case file...` button allows to save all the parameters used to generate the
 outcome of this case to a *case* file.

{owlplanner-2025.2.2 → owlplanner-2025.2.3}/ui/Optimization_Parameters.py

@@ -4,8 +4,8 @@ import sskeys as kz
 import owlbridge as owb
 
 
-profileChoices = ['smile', 'flat']
-kz.initKey('spendingProfile', profileChoices[0])
+profileChoices = ['flat', 'smile']
+kz.initKey('spendingProfile', profileChoices[1])
 kz.initKey('survivor', 60)
 kz.initKey('smileDip', 15)
 kz.initKey('smileIncrease', 12)

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

@@ -25,7 +25,8 @@ This file is in Excel or LibreOffice format, and has one tab per individual in t
 
 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 GitHub repository:
+1) Download these two files from the GitHub repository
+ (right-click on the link and select `Save link as...`):
     - Case parameter file named
     [case_jack+jill.toml](https://raw.github.com/mdlacasse/Owl/main/examples/case_jack+jill.toml)
     in editable *toml* format.

{owlplanner-2025.2.2 → owlplanner-2025.2.3}/ui/Wages_And_Contributions.py

@@ -51,6 +51,7 @@ else:
         newdf = st.data_editor(kz.getKey('timeList'+str(i)), column_config=colfor,
                                hide_index=True, key=kz.currentCaseName()+'_wages'+str(i))
         st.caption('Values are in nominal $.')
+        newdf.fillna(0, inplace=True)
         kz.storeKey('_timeList'+str(i), newdf)
 
     st.button('Reset to zero', help='Reset all values to zero.', on_click=resetTimeLists)

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

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

owlplanner-2025.2.2/src/owlplanner/version.py

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