owlplanner 2025.2.27__tar.gz → 2025.3.7__tar.gz

{owlplanner-2025.2.27 → owlplanner-2025.3.7}/.github/workflows/github-actions-runtests.yml

@@ -5,6 +5,7 @@ name: Python package
 
 run-name: ${{ github.actor }} running tests
 on: [push]
+permissions: read-all
 jobs:
   build:
     runs-on: ubuntu-latest

{owlplanner-2025.2.27 → owlplanner-2025.3.7}/INSTALL.md

@@ -14,7 +14,7 @@ or, if one prefers to have everything on their own computer,
 to install and run a Docker image as described in these [instructions](docker/README.md).
 
 ### Requirements
-You will need Python and `pip` installed on your computer for that purpose.
+You will need Python and `pip` installed on your computer for completing the installation.
 
 ### Installation steps for developers
 These instructions are command-line instructions.
@@ -29,7 +29,8 @@ From the top directory of the source code run:
 python -m build 
 pip install -e .
 ```
-The -e instructs Python to load the live version in the current directory tree. 
+The -e instructs `pip` to install in *editable* mode and use the live version
+in the current directory tree.
 
 ### Running the streamlit frontend 
 Running the Owl user interface locally from Windows:
@@ -42,7 +43,7 @@ Running the Owl user interface locally from Linux or MacOS:
 ```
 
 ### Publishing a version (for reference only)
-Run checks before commit:
+Run checks before all commits:
 ```
 flake8 ui src tests
 pytest

{owlplanner-2025.2.27 → owlplanner-2025.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owlplanner
-Version: 2025.2.27
+Version: 2025.3.7
 Summary: Owl: Retirement planner with great wisdom
 Project-URL: HomePage, https://github.com/mdlacasse/owl
 Project-URL: Repository, https://github.com/mdlacasse/owl
@@ -711,7 +711,13 @@ Description-Content-Type: text/markdown
 -------------------------------------------------------------------------------------
 
 ### TL;DR
-Owl is a planning tool that uses a linear programming optimization algorithm to provide guidance on retirement decisions. There are a few ways to run Owl.
+Owl is a retirement planning tool that uses a linear programming optimization algorithm
+to provide guidance on retirement decisions, including Roth conversions.
+Users can select varying return rates to perform historical back testing,
+stochastic rates for performing Monte Carlo analyses,
+or fixed rates either derived from historical averages, or set by the user.
+
+There are a few ways to run Owl:
 
 - Run Owl directly on the Streamlit Community Server at [owlplanner.streamlit.app](https://owlplanner.streamlit.app).
 
@@ -868,7 +874,7 @@ assets to support, even with no estate being left.
 ---------------------------------------------------------------
 ## Documentation
 
-- Documentation for the app user interface is available from the interface itself.
+- Documentation for the app user interface is available from the interface [itself](https://owlplanner.streamlit.app/Documentation).
 - Installation guide and software requirements can be found [here](INSTALL.md).
 - User guide for the underlying Python package as used in a Jupyter notebook can be found [here](USER_GUIDE.md).
 

{owlplanner-2025.2.27 → owlplanner-2025.3.7}/README.md

@@ -8,7 +8,13 @@
 -------------------------------------------------------------------------------------
 
 ### TL;DR
-Owl is a planning tool that uses a linear programming optimization algorithm to provide guidance on retirement decisions. There are a few ways to run Owl.
+Owl is a retirement planning tool that uses a linear programming optimization algorithm
+to provide guidance on retirement decisions, including Roth conversions.
+Users can select varying return rates to perform historical back testing,
+stochastic rates for performing Monte Carlo analyses,
+or fixed rates either derived from historical averages, or set by the user.
+
+There are a few ways to run Owl:
 
 - Run Owl directly on the Streamlit Community Server at [owlplanner.streamlit.app](https://owlplanner.streamlit.app).
 
@@ -165,7 +171,7 @@ assets to support, even with no estate being left.
 ---------------------------------------------------------------
 ## Documentation
 
-- Documentation for the app user interface is available from the interface itself.
+- Documentation for the app user interface is available from the interface [itself](https://owlplanner.streamlit.app/Documentation).
 - Installation guide and software requirements can be found [here](INSTALL.md).
 - User guide for the underlying Python package as used in a Jupyter notebook can be found [here](USER_GUIDE.md).
 

{owlplanner-2025.2.27 → owlplanner-2025.3.7}/pyproject.toml

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

{owlplanner-2025.2.27 → owlplanner-2025.3.7}/src/owlplanner/plan.py

@@ -1968,8 +1968,8 @@ class Plan(object):
         self.dist_in = self.w_ijn[:, 1, :] - self.rmd_in
         self.dist_in[self.dist_in < 0] = 0
         self.G_n = np.sum(self.F_tn, axis=0)
-        T_tn = self.F_tn * self.theta_tn
-        self.T_n = np.sum(T_tn, axis=0)
+        self.T_tn = self.F_tn * self.theta_tn
+        self.T_n = np.sum(self.T_tn, axis=0)
 
         tau_0 = np.array(self.tau_kn[0, :])
         tau_0[tau_0 < 0] = 0
@@ -2105,6 +2105,12 @@ class Plan(object):
         taxPaidNow = np.sum(self.T_n / self.gamma_n[:-1], axis=0)
         dic["Total income tax paid on ordinary income"] = f"{u.d(taxPaidNow)}"
         dic["- Total income tax paid on ordinary income (nominal)"] = f"{u.d(taxPaid)}"
+        for t in range(self.N_t):
+            taxPaid = np.sum(self.T_tn[t], axis=0)
+            taxPaidNow = np.sum(self.T_tn[t] / self.gamma_n[:-1], axis=0)
+            tname = tx.taxBracketNames[t]
+            dic[f"-- Subtotal in tax bracket {tname}"] = f"{u.d(taxPaidNow)}"
+            dic[f"--- Subtotal in tax bracket {tname} (nominal)"] = f"{u.d(taxPaid)}"
 
         taxPaid = np.sum(self.U_n, axis=0)
         taxPaidNow = np.sum(self.U_n / self.gamma_n[:-1], axis=0)
@@ -2129,12 +2135,17 @@ class Plan(object):
             iname_s = self.inames[self.i_s]
             iname_d = self.inames[self.i_d]
             dic[f"Sum of spousal transfer to {iname_s} in year {ynx}"] = (f"{u.d(totSpousalNow)}")
-            dic[f"- Sum of spousal transfer to {iname_s} in year {ynx} (nominal)"] = (f"{u.d(totSpousal)}")
-            dic[f"-- Spousal transfer to {iname_s} in year {ynx} - taxable (nominal)"] = (f"{u.d(q_j[0])}")
-            dic[f"-- Spousal transfer to {iname_s} in year {ynx} - tax-def (nominal)"] = (f"{u.d(q_j[1])}")
-            dic[f"-- Spousal transfer to {iname_s} in year {ynx} - tax-free (nominal)"] = (f"{u.d(q_j[2])}")
-
-            dic[f"Sum of post-tax non-spousal bequests from {iname_d} in year {ynx}"] = (f"{u.d(totOthersNow)}")
+            dic[f"- Sum of spousal transfer to {iname_s} in year {ynx} (nominal)"] = (
+                f"{u.d(totSpousal)}")
+            dic[f"-- Spousal transfer to {iname_s} in year {ynx} - taxable (nominal)"] = (
+                f"{u.d(q_j[0])}")
+            dic[f"-- Spousal transfer to {iname_s} in year {ynx} - tax-def (nominal)"] = (
+                f"{u.d(q_j[1])}")
+            dic[f"-- Spousal transfer to {iname_s} in year {ynx} - tax-free (nominal)"] = (
+                f"{u.d(q_j[2])}")
+
+            dic[f"Sum of post-tax non-spousal bequests from {iname_d} in year {ynx}"] = (
+                f"{u.d(totOthersNow)}")
             dic[f"- Sum of post-tax non-spousal bequests from {iname_d} in year {ynx} (nominal)"] = (
                 f"{u.d(totOthers)}")
             dic[f"-- Post-tax non-spousal bequests from {iname_d} in year {ynx} - taxable (nominal)"] = (
@@ -2156,7 +2167,7 @@ class Plan(object):
         dic[f"-- Post-tax account value at the end of {lastyear} - tax-free (nominal)"] = (f"{u.d(estate[2])}")
 
         dic["Plan starting date"] = str(self.startDate)
-        dic[f"Cumulative inflation factor from start date to end of {lastyear}"] = f"{self.gamma_n[-1]:.2f}"
+        dic[f"Cumulative inflation factor from start date to end of {lastyear}"] = (f"{self.gamma_n[-1]:.2f}")
         for i in range(self.N_i):
             dic[f"{self.inames[i]:>12}'s {self.horizons[i]:02}-year life horizon"] = (
                 f"{now} -> {now + self.horizons[i] - 1}")

owlplanner-2025.3.7/src/owlplanner/version.py

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

{owlplanner-2025.2.27 → owlplanner-2025.3.7}/ui/Create_Case.py

@@ -25,7 +25,7 @@ elif ret == kz.loadCaseFile:
     st.info(
         "#### Starting a case from a *case* parameter file.\n\n"
         "Upload your own case or select one from multiple examples."
-        " Alternatively, you can select `New Case...` in the margin selector box to start a case from scratch.\n\n"
+        " Alternatively, you can select `New Case...` in the top selector box to start a case from scratch.\n\n"
         "Look at the :material/help: [Documentation](Documentation) for more details."
     )
     st.write("#### Upload your own case file")
@@ -121,7 +121,7 @@ else:
     st.divider()
     cantcreate = kz.isIncomplete() or diz1
     if not cantcreate and kz.getKey("plan") is None:
-        st.info("Plan needs to be created once all the information needed has been entered.")
+        st.info("Plan needs to be created once desired changes are completed.")
 
     cantmodify = kz.currentCaseName() == kz.newCase or kz.currentCaseName() == kz.loadCaseFile
     cantcopy = cantmodify or kz.caseHasNoPlan()

{owlplanner-2025.2.27 → owlplanner-2025.3.7}/ui/Documentation.py

@@ -34,16 +34,28 @@ formulation of the optimization problem can be found
 
 --------------------------------------------------------------------------------------
 ### Getting started with the user interface
-Functions of each page are described below in the same order as they appear in the sidebar.
+Functions of each page are described below in the same order as they appear in the left sidebar.
 Typically, pages would be accessed in order, starting from the top.
+
 The `Case selector` box at the top of the page 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
-and allows to compare different scenarios.
+and allows to access and compare different scenarios.
+
+A typical workflow for exploring different scenarios involves starting with a base
+case and then duplicating/creating derived scenarios with slight changes in the parameters,
+which are configured in the **Case Setup** section. The comparison between the
+different resulting outcomes is shown on the [Output Files](#output-files) page.
+
+Owl uses a year as the standard time unit. All values are therefore entered and
+reported as yearly values. These include wages, income, rates, social security, etc.
+Dollar values are typically entered in thousands, unless in tables, where they
+are entered and reported in unit dollars.
 
 There are four sections in the user interface:
 **Case Setup**, **Single Scenario**, **Multiple Scenarios**, and **Resources**.
+The sections below follow the same logical order.
 
 -------------------------------------------------
 ### :orange[Case Setup]
@@ -307,24 +319,28 @@ The first line of the *Sources* worksheets are the most important
 as these lines are the only ones that are actionable.
 
 #### Output Files
-This page allow to compare cases and save files for future use.
-First it shows a synopsis of the computed scenario by
+This page allows to compare cases and save files for future use.
+First, it shows a synopsis of the computed scenario by
 displaying sums of income, bequest, and spending values over the duration of the plan.
-If more than one case was run, they will be compared provided they were made
-for the same individuals.
+If multiple cases were configured and run (most likely through duplication and
+modifying the configuration), they will be compared in that panel provided they were made
+for the same individuals. Column on the left shows the values for the selected case
+while those on the right will show the differences.
 The contents of the synopsis can be downloaded as a plain text file by
 clicking the button below it.
 
-Similarly, parameters used to generate the case are collected in *toml* format and displayed.
-The `Download case file...` button allows to save the parameters used to generate the
-outcome of this case to a *case* file.
-
 Another section called `Excel workbooks` allows
-to save the contents of the tables on the corresponding page to an Excel workbook.
+to save the contents of the tables on the corresponding page as an Excel workbook.
+These data are displayed on the *Worksheets* and the *Wages and Contributions* pages.
+
+Similarly, all parameters used to generate the case are collected in *toml* format and displayed.
+The `Download case file...` button allows to save the parameters of the selected scenario
+to a *case* file.
 
-With the case parameter and the wages and contributions files,
+With the case parameter file and the wages and contributions worksheet,
 the same case can be reproduced at a later time by uploading
-them through the widgets on the `Create Case` and `Wages and Contributions` pages.
+them through the widgets on the `Create Case` and `Wages and Contributions` pages,
+respectively.
 
 --------------------------------------------------------------------------------------
 ### :orange[Multiple Scenarios]

{owlplanner-2025.2.27 → owlplanner-2025.3.7}/ui/Output_Files.py

@@ -18,9 +18,8 @@ else:
         df = kz.compareSummaries()
         if df is not None:
             st.write("#### Synopsis")
-            # st.code(lines, language=None)
-            # st.markdown(df.to_markdown())
             st.dataframe(df[1:], use_container_width=True)
+            st.caption("Values are in today's \\$ unless marked otherwise.")
             st.download_button(
                 "Download synopsis", data=df[1:].to_string(), file_name=f"Synopsis_{caseName}.txt",
                 mime="text/plain;charset=UTF-8"

{owlplanner-2025.2.27 → owlplanner-2025.3.7}/ui/Quick_Start.py

@@ -49,12 +49,11 @@ 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 **Create Case** page,
 and fill in the information needed on each page in the `Case Setup` section.
-Once a case has been fully parameterized and successfully optimized,
-its parameters can be saved by using the `Download case file...` button on the `Output Files` page.
-
 Alternatively, you can duplicate any existing case by using
 the `Duplicate case` button, and then edit its values to fit your situation.
 
+Once a case has been fully parameterized and successfully optimized,
+its parameters can be saved by using the `Download case file...` button on the `Output Files` page.
 Multiple cases can coexist and can be called and compared using the `Case selector` box
 at the top of the page.
 

{owlplanner-2025.2.27 → owlplanner-2025.3.7}/ui/requirements.txt

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

{owlplanner-2025.2.27 → owlplanner-2025.3.7}/ui/sskeys.py

@@ -260,7 +260,7 @@ def storepull(key):
 def setKey(key, val):
     ss.cases[ss.currentCase][key] = val
     ss.cases[ss.currentCase]["caseStatus"] = "modified"
-    # print("setKey", key, val)
+    ss.cases[ss.currentCase]["summaryDf"] = None
     return val
 
 
@@ -326,7 +326,7 @@ def compareSummaries():
         df = pd.concat([df, odf])
 
     if df.shape[0] > 1:
-        # Unroll to subtract strings representations of numbers.
+        # Unroll to subtract $tring representation of numbers.
         for col in range(1, df.shape[1] - 5):
             strval = df.iloc[0, col]
             if isinstance(strval, str) and strval[0] == "$":
@@ -334,9 +334,9 @@ def compareSummaries():
                 for row in range(1, df.shape[0]):
                     fnval = float(df.iloc[row, col][1:].replace(",", ""))
                     diff = fnval - f0val
-                    sign = "+" if diff >= 0 else "-"
-                    sign = "" if diff == 0 else sign
-                    df.iloc[row, col] = f"{sign}${abs(diff):,.0f}"
+                    sign = "\u2191" if diff >= 0 else "\u2193"
+                    sign = "\u2192" if diff == 0 else sign
+                    df.iloc[row, col] = f"{sign} ${abs(diff):,.0f}"
 
     return df.transpose()
 

owlplanner-2025.2.27/src/owlplanner/version.py

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