owlplanner 2025.9.15__tar.gz → 2025.11.3__tar.gz

{owlplanner-2025.9.15 → owlplanner-2025.11.3}/INSTALL.md

@@ -2,7 +2,7 @@
 
 ## A retirement exploration tool based on linear programming
 
-<img align=right src="https://raw.github.com/mdlacasse/Owl/main/docs/images/owl.png" width="250">
+<img align=right src="https://github.com/mdlacasse/Owl/blob/main/docs/images/owl.png?raw=true" width="250">
 
 ------------------------------------------------------------------------------------
 ### About

{owlplanner-2025.9.15 → owlplanner-2025.11.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owlplanner
-Version: 2025.9.15
+Version: 2025.11.3
 Summary: Owl: Retirement planner with great wisdom
 Project-URL: HomePage, https://github.com/mdlacasse/owl
 Project-URL: Repository, https://github.com/mdlacasse/owl
@@ -709,7 +709,7 @@ Description-Content-Type: text/markdown
 
 ## A retirement exploration tool based on linear programming
 
-<img align=right src="https://raw.github.com/mdlacasse/Owl/main/docs/images/owl.png" width="250">
+<img align=right src="https://github.com/mdlacasse/Owl/blob/main/docs/images/owl.png?raw=true" width="250">
 
 -------------------------------------------------------------------------------------
 
@@ -739,7 +739,7 @@ Strictly speaking, it is not a planning tool, but more an environment for explor
 It provides different realizations of a financial strategy through the rigorous
 mathematical optimization of relevant decision variables. Two major objective goals can be set: either
 maximize net spending, or after-tax bequest under various constraints.
-Look at *Basic capabilities* below for more detail.
+Look at the *Capabilities* section below for more detail.
 
 One can certainly have a savings plan, but due to the volatility of financial investments,
 it is impossible to have a certain asset earnings plan. This does not mean one cannot make decisions.
@@ -758,7 +758,7 @@ collecting your data, or academic papers that share the results without really s
 the underlying mathematical models.
 The algorithms in Owl rely on the open-source HiGHS linear programming solver. The complete formulation and
 detailed description of the underlying
-mathematical model can be found [here](https://raw.github.com/mdlacasse/Owl/main/docs/owl.pdf).
+mathematical model can be found [here](https://github.com/mdlacasse/Owl/blob/main/docs/owl.pdf).
 
 It is anticipated that most end users will use Owl through the graphical interface
 either at [owlplanner.streamlit.app](https://owlplanner.streamlit.app)
@@ -768,7 +768,7 @@ as described [here](USER_GUIDE.md).
 
 Not every retirement decision strategy can be framed as an easy-to-solve optimization problem.
 In particular, if one is interested in comparing different withdrawal strategies,
-[FI Calc](ficalc.app) is an elegant application that addresses this need.
+[FI Calc](https://ficalc.app) is an elegant application that addresses this need.
 If, however, you also want to optimize spending, bequest, and Roth conversions, with
 an approach also considering Medicare and federal income tax over the next few years,
 then Owl is definitely a tool that can help guide your decisions.
@@ -840,7 +840,9 @@ Tax status covers married filing jointly and single, depending on the number of
 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.
+They can also be optimized explicitly as an option, but this choice can lead to longer calculations
+due to the use of the many additional binary variables required by the formulation.
+Future Medicare and IRMAA values are simple projections of current values with the assumed inflation rates.
 
 ### Limitations
 Owl is work in progress. At the current time:
@@ -851,15 +853,16 @@ These cases are detected and will generate an error message.
 - Social security rule for surviving spouse assumes that benefits were taken at full retirement age.
 - Current version has no optimization of asset allocations between individuals and/or types of savings accounts.
 If there is interest, that could be added in the future.
-- In the current implementation, social securiy is always taxed at 85%.
-- Medicare calculations are done through a self-consistent loop.
-This means that the Medicare premiums are calculated after an initial solution is generated,
+- In the current implementation, social securiy is always taxed at 85%, assuming that your taxable income will be larger than 34 k$ (single) or 44 k$ (married filing jointly).
+- When Medicare calculations are done through a self-consistent loop,
+the Medicare premiums are calculated after an initial solution is generated,
 and then a new solution is re-generated with these premiums as a constraint.
 In some situations, when the income (MAGI) is near an IRMAA bracket, oscillatory solutions can arise.
 While the solutions generated are very close to one another, Owl will pick the smallest solution
-for being conservative.
-- Part D is not included in the IRMAA calculations. Being considerably more significant,
-only Part B is taken into account. 
+for being conservative. While sometimes computationally costly,
+a comparison with a full Medicare optimization should always be performed.
+- Part D is not included in the IRMAA calculations. Only Part B is taken into account, 
+which is considerably more significant.
 - Future tax brackets are pure speculations derived from the little we know now and projected to the next 30 years.
 Your guesses are as good as mine.
 
@@ -886,8 +889,11 @@ assets to support, even with no estate being left.
 - Optimization solver from [HiGHS](https://highs.dev)
 - Streamlit Community Cloud [Streamlit](https://streamlit.io)
 - Contributors: Josh (noimjosh@gmail.com) for Docker image code,
+ kg333 for fixing an error in Docker's instructions,
  Dale Seng (sengsational) for great insights and suggestions,
- Robert E. Anderson (NH-RedAnt) for bug fixes and suggestions, Clark Jefcoat (hubcity) for fruitful interactions.
+ Robert E. Anderson (NH-RedAnt) for bug fixes and suggestions,
+ Clark Jefcoat (hubcity) for fruitful interactions,
+ Benjamin Quinn (blquinn) and Gene Wood (gene1wood) for improvements and bug fixes.
 
 ---------------------------------------------------------------------
 

{owlplanner-2025.9.15 → owlplanner-2025.11.3}/README.md

@@ -3,7 +3,7 @@
 
 ## A retirement exploration tool based on linear programming
 
-<img align=right src="https://raw.github.com/mdlacasse/Owl/main/docs/images/owl.png" width="250">
+<img align=right src="https://github.com/mdlacasse/Owl/blob/main/docs/images/owl.png?raw=true" width="250">
 
 -------------------------------------------------------------------------------------
 
@@ -33,7 +33,7 @@ Strictly speaking, it is not a planning tool, but more an environment for explor
 It provides different realizations of a financial strategy through the rigorous
 mathematical optimization of relevant decision variables. Two major objective goals can be set: either
 maximize net spending, or after-tax bequest under various constraints.
-Look at *Basic capabilities* below for more detail.
+Look at the *Capabilities* section below for more detail.
 
 One can certainly have a savings plan, but due to the volatility of financial investments,
 it is impossible to have a certain asset earnings plan. This does not mean one cannot make decisions.
@@ -52,7 +52,7 @@ collecting your data, or academic papers that share the results without really s
 the underlying mathematical models.
 The algorithms in Owl rely on the open-source HiGHS linear programming solver. The complete formulation and
 detailed description of the underlying
-mathematical model can be found [here](https://raw.github.com/mdlacasse/Owl/main/docs/owl.pdf).
+mathematical model can be found [here](https://github.com/mdlacasse/Owl/blob/main/docs/owl.pdf).
 
 It is anticipated that most end users will use Owl through the graphical interface
 either at [owlplanner.streamlit.app](https://owlplanner.streamlit.app)
@@ -62,7 +62,7 @@ as described [here](USER_GUIDE.md).
 
 Not every retirement decision strategy can be framed as an easy-to-solve optimization problem.
 In particular, if one is interested in comparing different withdrawal strategies,
-[FI Calc](ficalc.app) is an elegant application that addresses this need.
+[FI Calc](https://ficalc.app) is an elegant application that addresses this need.
 If, however, you also want to optimize spending, bequest, and Roth conversions, with
 an approach also considering Medicare and federal income tax over the next few years,
 then Owl is definitely a tool that can help guide your decisions.
@@ -134,7 +134,9 @@ Tax status covers married filing jointly and single, depending on the number of
 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.
+They can also be optimized explicitly as an option, but this choice can lead to longer calculations
+due to the use of the many additional binary variables required by the formulation.
+Future Medicare and IRMAA values are simple projections of current values with the assumed inflation rates.
 
 ### Limitations
 Owl is work in progress. At the current time:
@@ -145,15 +147,16 @@ These cases are detected and will generate an error message.
 - Social security rule for surviving spouse assumes that benefits were taken at full retirement age.
 - Current version has no optimization of asset allocations between individuals and/or types of savings accounts.
 If there is interest, that could be added in the future.
-- In the current implementation, social securiy is always taxed at 85%.
-- Medicare calculations are done through a self-consistent loop.
-This means that the Medicare premiums are calculated after an initial solution is generated,
+- In the current implementation, social securiy is always taxed at 85%, assuming that your taxable income will be larger than 34 k$ (single) or 44 k$ (married filing jointly).
+- When Medicare calculations are done through a self-consistent loop,
+the Medicare premiums are calculated after an initial solution is generated,
 and then a new solution is re-generated with these premiums as a constraint.
 In some situations, when the income (MAGI) is near an IRMAA bracket, oscillatory solutions can arise.
 While the solutions generated are very close to one another, Owl will pick the smallest solution
-for being conservative.
-- Part D is not included in the IRMAA calculations. Being considerably more significant,
-only Part B is taken into account. 
+for being conservative. While sometimes computationally costly,
+a comparison with a full Medicare optimization should always be performed.
+- Part D is not included in the IRMAA calculations. Only Part B is taken into account, 
+which is considerably more significant.
 - Future tax brackets are pure speculations derived from the little we know now and projected to the next 30 years.
 Your guesses are as good as mine.
 
@@ -180,8 +183,11 @@ assets to support, even with no estate being left.
 - Optimization solver from [HiGHS](https://highs.dev)
 - Streamlit Community Cloud [Streamlit](https://streamlit.io)
 - Contributors: Josh (noimjosh@gmail.com) for Docker image code,
+ kg333 for fixing an error in Docker's instructions,
  Dale Seng (sengsational) for great insights and suggestions,
- Robert E. Anderson (NH-RedAnt) for bug fixes and suggestions, Clark Jefcoat (hubcity) for fruitful interactions.
+ Robert E. Anderson (NH-RedAnt) for bug fixes and suggestions,
+ Clark Jefcoat (hubcity) for fruitful interactions,
+ Benjamin Quinn (blquinn) and Gene Wood (gene1wood) for improvements and bug fixes.
 
 ---------------------------------------------------------------------
 

{owlplanner-2025.9.15 → owlplanner-2025.11.3}/USER_GUIDE.md

@@ -2,7 +2,7 @@
 
 ## A retirement exploration tool based on linear programming
 
-<img align=right src="https://raw.github.com/mdlacasse/Owl/main/docs/images/owl.png" width="250">
+<img align=right src="https://github.com/mdlacasse/Owl/blob/main/docs/images/owl.png?raw=true" width="250">
 
 ------------------------------------------------------------------------------------
 ### About
@@ -64,7 +64,7 @@ the boundaries of tax brackets.
 ```python
 plan.showGrossIncome(value='nominal')
 ```
-<img src="https://raw.github.com/mdlacasse/Owl/main/docs/images/taxIncomePlot.png" width="75%">
+<img src="https://github.com/mdlacasse/Owl/blob/main/docs/images/taxIncomePlot.png?raw=true" width="75%">
 
 The optimal spending profile is shown in the next plot (in today's dollars). Notice the drop
 (recall we selected 60% survivor needs) at the passing of the first spouse.
@@ -72,26 +72,26 @@ The optimal spending profile is shown in the next plot (in today's dollars). Not
 plan.showProfile('today')
 ```
 
-<img src="https://raw.github.com/mdlacasse/Owl/main/docs/images/spendingPlot.png" width="75%">
+<img src="https://github.com/mdlacasse/Owl/blob/main/docs/images/spendingPlot.png?raw=true" width="75%">
 
 The following plot shows the account balances in nominal value for all savings accounts owned by Jack and Jill.
 It was generated using
 ```python
 plan.showAccounts(value='nominal')
 ```
-<img src="https://raw.github.com/mdlacasse/Owl/main/docs/images/savingsPlot.png" width="75%">
+<img src="https://github.com/mdlacasse/Owl/blob/main/docs/images/savingsPlot.png?raw=true" width="75%">
 
 while this plot shows the complex cash flow from all sources, which was generated with
 ```python
 plan.showSources(value='nominal')
 ```
-<img src="https://raw.github.com/mdlacasse/Owl/main/docs/images/sourcesPlot.png" width="75%">
+<img src="https://github.com/mdlacasse/Owl/blob/main/docs/images/sourcesPlot.png?raw=true" width="75%">
 
 For taxes, the following call will display Medicare premiums (including Part B IRMAA fees) and federal income tax
 ```python
 plan.showTaxes(value='nominal')
 ```
-<img src="https://raw.github.com/mdlacasse/Owl/main/docs/images/taxesPlot.png" width="75%">
+<img src="https://github.com/mdlacasse/Owl/blob/main/docs/images/taxesPlot.png?raw=true" width="75%">
 
 For the case at hand, recall that asset allocations were selected above through
 
@@ -103,9 +103,9 @@ Assets distribution in all accounts in today's $ over time can be displayed from
 ```python
 plan.showAssetDistribution(value='today')
 ```
-<img src="https://raw.github.com/mdlacasse/Owl/main/docs/images/AD-taxable.png" width="75%">
-<img src="https://raw.github.com/mdlacasse/Owl/main/docs/images/AD-taxDef.png" width="75%">
-<img src="https://raw.github.com/mdlacasse/Owl/main/docs/images/AD-taxFree.png" width="75%">
+<img src="https://github.com/mdlacasse/Owl/blob/main/docs/images/AD-taxable.png?raw=true" width="75%">
+<img src="https://github.com/mdlacasse/Owl/blob/main/docs/images/AD-taxDef.png?raw=true" width="75%">
+<img src="https://github.com/mdlacasse/Owl/blob/main/docs/images/AD-taxFree.png?raw=true" width="75%">
 
 These plots are irregular because we used historical rates from 1969. The volatility of
 the rates offers Roth conversion benefits which are exploited by the optimizer.
@@ -113,7 +113,7 @@ The rates used can be displayed by:
 ```python
 plan.showRates()
 ```
-<img src="https://raw.github.com/mdlacasse/Owl/main/docs/images/ratesPlot.png" width="75%">
+<img src="https://github.com/mdlacasse/Owl/blob/main/docs/images/ratesPlot.png?raw=true" width="75%">
 
 Values between brackets <> are the average values and volatility over the selected period. 
 
@@ -121,7 +121,7 @@ For the statisticians, rates distributions and correlations between them can be
 ```python
 plan.showRatesCorrelations()
 ```
-<img src="https://raw.github.com/mdlacasse/Owl/main/docs/images/ratesCorrelations.png" width="75%">
+<img src="https://github.com/mdlacasse/Owl/blob/main/docs/images/ratesCorrelations.png?raw=true" width="75%">
 
 A short text summary of the outcome of the optimization can be displayed through using:
 ```python
@@ -169,13 +169,13 @@ by selecting *stochastic* rates and using
 ```
 plan.runMC('maxSpending', ...)
 ```
-<img src="https://raw.github.com/mdlacasse/Owl/main/docs/images/MC-tutorial2a.png" width="75%">
+<img src="https://github.com/mdlacasse/Owl/blob/main/docs/images/MC-tutorial2a.png?raw=true" width="75%">
 
 Similarly, the next one was generated using
 ```
 plan.runMC('maxBequest', ...)
 ```
-<img src="https://raw.github.com/mdlacasse/Owl/main/docs/images/MC-tutorial2b.png" width="75%">
+<img src="https://github.com/mdlacasse/Owl/blob/main/docs/images/MC-tutorial2b.png?raw=true" width="75%">
 
 
 See tutorial notebooks [1](https://github.com/mdlacasse/Owl/blob/main/notebooks/tutorial_1.ipynb),
@@ -195,7 +195,7 @@ The simplest way to get started with Owl is to use the `streamlit` browser-based
 that is started by the `owlplanner.cmd` script, which  will start a user interface on your own browser.
 Here is a screenshot of one of the multiple tabs of the interface:
 
-<img src="https://raw.github.com/mdlacasse/Owl/main/docs/images/OwlUI.png" width="100%">
+<img src="https://github.com/mdlacasse/Owl/blob/main/docs/images/OwlUI.png?raw=true" width="100%">
 
 Alternatively, one can prefer using Owl from Jupyter notebooks. For that purpose, the `examples` directory
 contains many files as a tutorial. The Jupyter Notebook interface is a browser-based application

owlplanner-2025.9.15/docker/Dockerfile.build → owlplanner-2025.11.3/docker/Dockerfile.bare

@@ -1,16 +1,10 @@
 # docker/Dockerfile
 
-FROM python:3.13-slim
+FROM python:3.13-alpine
 
 WORKDIR /app
 
-RUN apt-get update; \
-    apt-get upgrade; \
-    apt-get install -y --no-install-recommends \
-        curl \
-        git \
-    ; \
-    rm -rf /var/lib/apt/lists/*
+RUN apk update; apk upgrade; apk add curl git bash
 
 COPY buildentrypoint.sh /usr/bin/entrypoint.sh
 COPY runentrypoint.sh /usr/bin/runentrypoint.sh

owlplanner-2025.9.15/docker/Dockerfile.run → owlplanner-2025.11.3/docker/Dockerfile.static

@@ -1,16 +1,10 @@
 # docker/Dockerfile
 
-FROM python:3.13-slim
+FROM python:3.13-alpine
 
 WORKDIR /app
 
-RUN apt-get update; \
-    apt-get upgrade; \
-    apt-get install -y --no-install-recommends \
-        curl \
-        git \
-    ; \
-    rm -rf /var/lib/apt/lists/*
+RUN apk update; apk upgrade; apk add bash curl git
 
 COPY runentrypoint.sh /usr/bin/entrypoint.sh
 

{owlplanner-2025.9.15 → owlplanner-2025.11.3}/docker/README.md

@@ -14,37 +14,49 @@ Using this approach only requires downloading the Docker image from
 the [Docker Hub](http://hub.docker.com) and having the [Docker](http://docker.com)
 application installed on your computer.
 
-Downloading the Docker image from the command line:
+There are two versions of the Docker image: one that has been provisioned
+with all the necessary Python modules
+named 'owldocker.static' and one bare image that self-installs the Owl application from
+GitHub at runtime named 'owldocker.bare'.
+The 'static' version, while being larger than the 'bare' version (1.6 GB vs 96 MB),
+will start much faster as all the required code is contained in the image. However,
+the version of Owl is fixed at the time when the container was built. Conversely,
+the 'bare' version will dynamically clone Owl from GitHub and download/install all its requirements.
+The resulting Owl version is the one available from GitHub at the time when the container is launched.
+This leads to a slower start, but this approach guarantees to have Owl's latest version.
+
+For downloading the Docker image from the command line (select one from 'static' or 'bare'):
+
 ```
-docker pull owlplanner/owldocker
+docker pull owlplanner/owldocker.{static or bare}
 ```
 Then the container can be started (and stopped) from the command line:
 ```
-docker run -p 8501:8501 --rm owlplanner/owldocker
+docker run -p 8501:8501 --rm owlplanner/owldocker.{static or bare}
 ```
 
 Just point your browser to http://localhost:8501 to access the Owl user interface.
 Owl will run locally and safely through a container on your computer.
 
 One can also use the Docker Desktop graphical user interface for performing the same steps.
-The image *owlplanner/owldocker* can be searched for and downloaded in the 
+The image *owlplanner/owldocker.{static or bare}* can be searched for and downloaded in the 
 *Docker Hub* section of Docker Desktop. Then, on the *Images* section,
 click on the run icon for the image, and use host port 8501 to map to container port 8501.
 
 ------------------------------------------------------------------------------------
-### Building the docker image
+### Building the docker images
 This approach requires cloning the Owl package from GitHub,
 and having both Python and Docker installed on your computer.
 
-##### Docker image
+##### Building the Docker images
 There are two images you can create. One builds Owl at run time, while
 the other builds it statically in the image.
 These two approaches trade startup time for image space
-(~300 MB vs. 1.8 GB, ~22 vs. 200 sec).
+(~96 MB vs. 1.5 GB, ~22 vs. 200 sec).
 First build the Docker image from the `docker` directory:
 ```shell
 cd docker
-docker build --no-cache -f Dockerfile.{build or run} -t owldocker .
+docker build --no-cache -f Dockerfile.{static or bare} -t owlplanner/owldocker.{static or bare}:latest .
 ```
 
 #### Running the container
@@ -52,7 +64,7 @@ The container can be run directly from the command line,
 with the desired port mapping.
 
 ```shell
-docker run -p 8501:8501 --rm owldocker
+docker run -p 8501:8501 --rm owlplanner/owldocker.{static or bare}
 ```
 
 #### Running with docker-compose
@@ -64,7 +76,7 @@ The compose file maps the host-side port to the container-side port.
 ```yml
 services:
   owl:
-    image: owldocker
+    image: owldocker.{static or bare}
     restart: always
     ports:
       - 8501:8501
@@ -75,4 +87,4 @@ As before, just point your browser to http://localhost:8501 to access the Owl us
 ------------------------------------------------------------------------------------
 
 #### Credits
-Josh (noimjosh@gmail.com)
+Josh (noimjosh@gmail.com), kg333 (matthew@kyengineer.com)

{owlplanner-2025.9.15 → owlplanner-2025.11.3}/pyproject.toml

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

{owlplanner-2025.9.15 → owlplanner-2025.11.3}/requirements.txt

@@ -5,8 +5,8 @@ seaborn
 pandas
 openpyxl
 odfpy
-plotly
+plotly >= 6.3
 pulp
 scipy
-streamlit >= 1.49
+streamlit
 toml

{owlplanner-2025.9.15 → owlplanner-2025.11.3}/src/owlplanner/plan.py

@@ -1223,8 +1223,8 @@ class Plan(object):
 
         for i in range(self.N_i):
             for j in range(self.N_j):
-                backTau = 1 - yearSpent * np.sum(self.tau_kn[:, 0] * self.alpha_ijkn[i, j, :, 0])
-                rhs = self.beta_ij[i, j] * backTau
+                backTau = 1 + yearSpent * np.sum(self.tau_kn[:, 0] * self.alpha_ijkn[i, j, :, 0])
+                rhs = self.beta_ij[i, j] / backTau
                 self.B.setRange(_q3(self.C["b"], i, j, 0, self.N_i, self.N_j, self.N_n + 1), rhs, rhs)
 
     def _add_surplus_deposit_linking(self):

{owlplanner-2025.9.15 → owlplanner-2025.11.3}/src/owlplanner/tax2025.py

@@ -70,7 +70,7 @@ taxBrackets_preTCJA = np.array(
     ]
 )
 
-# These are 2025 current (adjusted for inflation).
+# These are 2025 current.
 stdDeduction_OBBBA = np.array([15750, 31500])    # Single, MFJ
 # These are speculated (adjusted for inflation).
 stdDeduction_preTCJA = np.array([8300, 16600])  # Single, MFJ
@@ -78,7 +78,7 @@ stdDeduction_preTCJA = np.array([8300, 16600])  # Single, MFJ
 # These are current (adjusted for inflation) per individual.
 extra65Deduction = np.array([2000, 1600])       # Single, MFJ
 
-# Thresholds for capital gains (adjusted for inflation).
+# Thresholds setting capital gains brackets 0%, 15%, 20% (adjusted for inflation).
 capGainRates = np.array(
     [
         [48350, 533400],