owlplanner 2025.12.3__tar.gz → 2025.12.5__tar.gz

{owlplanner-2025.12.3 → owlplanner-2025.12.5}/PKG-INFO

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

{owlplanner-2025.12.3 → owlplanner-2025.12.5}/RELEASE_NOTES.md

@@ -1,3 +1,7 @@
+### Version 2025.12.05
+- Added instructions for obtaining PIA
+- Bug fix in Fixed Income UI
+
 ### Version 2025.12.03
 - Coded social security to use monthly PIA instead of annual amount
     - Added exact routines for FRA and increase/decrease factors due to claiming age

owlplanner-2025.12.5/docker/buildPackage.cmd

@@ -0,0 +1,7 @@
+::
+:: A simple script to build Python package
+::
+cd ..
+del /Q dist\*
+python -m build .
+twine upload --repository pypi dist\*

{owlplanner-2025.12.3 → owlplanner-2025.12.5}/examples/case_jon+jane.toml

@@ -12,7 +12,7 @@ Names = [ "Jon", "Jane",]
 [Assets]
 "taxable savings balances" = [ 50.0, 0.0,]
 "tax-deferred savings balances" = [ 900.0, 500.0,]
-"tax-free savings balances" = [ 0.0, 0.0,]
+"tax-free savings balances" = [ 0.0, 50.0,]
 "Beneficiary fractions" = [ 1.0, 1.0, 1.0,]
 "Spousal surplus deposit fraction" = 0.0
 

owlplanner-2025.12.5/examples/ttt.toml

@@ -0,0 +1,58 @@
+"Plan Name" = "jack+jill"
+Description = "This example aims to demonstrate some of Owl's capabilities. Jack and Jill are a married couple a few years from retirement. A wages and contributions file called 'jack+jill.xlsx' is associated with this case. This case uses the historical rate sequence of 1969 as a test case for guiding spending amounts from a near worst-case historical scenario. This case also demonstrates that the optimal strategy for Roth conversions does not necessarily involve surfing a tax bracket.  \nA good exercise for learning Owl's capabilities is to duplicate this case and compare two scenarios: one with optimized Roth conversions and one without. Another possible exercise could involve comparing a historical retirement in 1969 vs. one taken in 1966. Or anything else you can think of..."
+
+["Basic Info"]
+Status = "married"
+Names = [ "Jack", "Jill",]
+"Birth year" = [ 1962, 1965,]
+"Birth month" = [ 1, 1,]
+"Life expectancy" = [ 89, 92,]
+"Start date" = "01-01"
+
+[Assets]
+"taxable savings balances" = [ 120.5, 60.2,]
+"tax-deferred savings balances" = [ 600.2, 150.0,]
+"tax-free savings balances" = [ 280.6, 260.8,]
+"Beneficiary fractions" = [ 1, 1, 1,]
+"Spousal surplus deposit fraction" = 0.0
+
+["Wages and Contributions"]
+"Contributions file name" = "jack+jill.xlsx"
+
+["Fixed Income"]
+"Pension amounts" = [ 0.0, 10.5,]
+"Pension ages" = [ 65, 65,]
+"Pension indexed" = [ false, false,]
+"Social security PIA amounts" = [ 2360, 1642,]
+"Social security ages" = [ 70, 62,]
+
+["Rates Selection"]
+"Heirs rate on tax-deferred estate" = 30.0
+"Dividend rate" = 1.8
+"OBBBA expiration year" = 2032
+Method = "historical"
+From = 1969
+To = 2002
+
+["Asset Allocation"]
+"Interpolation method" = "s-curve"
+"Interpolation center" = 15
+"Interpolation width" = 5
+Type = "individual"
+generic = [ [ [ 60, 40, 0, 0,], [ 70, 30, 0, 0,],], [ [ 60, 40, 0, 0,], [ 80, 0, 10, 10,],],]
+
+["Optimization Parameters"]
+"Spending profile" = "smile"
+"Smile dip" = 15
+"Smile increase" = 12
+"Smile delay" = 0
+"Surviving spouse spending percent" = 60
+Objective = "maxSpending"
+
+["Solver Options"]
+maxRothConversion = 100
+bequest = 500
+noRothConversions = "Jill"
+
+[Results]
+"Default plots" = "today"

{owlplanner-2025.12.3 → owlplanner-2025.12.5}/src/owlplanner/plan.py

@@ -1160,25 +1160,26 @@ class Plan(object):
             h = self.horizons[i]
             for n in range(h):
                 rhs = 0
-                # To add compounded gains to original amount.
+                # To add compounded gains to cumulative amounts. Always keep cgains >= 1.
                 cgains = 1
                 row = self.A.newRow()
                 row.addElem(_q3(self.C["b"], i, 2, n, self.N_i, self.N_j, self.N_n + 1), 1)
                 row.addElem(_q3(self.C["w"], i, 2, n, self.N_i, self.N_j, self.N_n), -1)
                 for dn in range(1, 6):
                     nn = n - dn
-                    if nn >= 0:       # Past of future is now or in the future: use variables and parameters.
+                    if nn >= 0:   # Past of future is now or in the future: use variables or parameters.
                         Tau1 = 1 + np.sum(self.alpha_ijkn[i, 2, :, nn] * self.tau_kn[:, nn], axis=0)
-                        cgains *= Tau1
+                        # Ignore market downs.
+                        cgains *= max(1, Tau1)
                         row.addElem(_q2(self.C["x"], i, nn, self.N_i, self.N_n), -cgains)
-                        # If a contribution - it can be withdrawn but not the gains.
+                        # If a contribution, it has only penalty on gains, not on deposited amount.
                         rhs += (cgains - 1) * self.kappa_ijn[i, 2, nn]
                     else:  # Past of future is in the past:
-                        # Parameters are stored at the end of contributions and conversions arrays.
                         cgains *= oldTau1
-                        # If a contribution, it has no penalty, but assume a conversion.
-                        # rhs += (cgains - 1) * self.kappa_ijn[i, 2, nn] + cgains * self.myRothX_in[i, nn]
-                        rhs += cgains * self.kappa_ijn[i, 2, nn] + cgains * self.myRothX_in[i, nn]
+                        # Past years are stored at the end of contributions and conversions arrays.
+                        # Use negative index to access tail of array.
+                        rhs += (cgains - 1) * self.kappa_ijn[i, 2, nn] + cgains * self.myRothX_in[i, nn]
+                        # rhs += cgains * self.kappa_ijn[i, 2, nn] + cgains * self.myRothX_in[i, nn]
 
                 self.A.addRow(row, rhs, np.inf)
 

owlplanner-2025.12.5/src/owlplanner/version.py

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

{owlplanner-2025.12.3 → owlplanner-2025.12.5}/tests/test_repro.py

@@ -38,7 +38,7 @@ def test_case1():
     p.setRates('historical', 1969)
     p.solve('maxSpending', options={'maxRothConversion': 100, 'bequest': 500})
     assert p.caseStatus == "solved"
-    assert p.basis == pytest.approx(87372.2, abs=0.5)
+    assert p.basis == pytest.approx(87373.1, abs=0.5)
     assert p.bequest == pytest.approx(500000, abs=0.5)
 
 
@@ -48,7 +48,7 @@ def test_case2():
     p.solve('maxBequest', options={'maxRothConversion': 100, 'netSpending': 80})
     assert p.caseStatus == "solved"
     assert p.basis == pytest.approx(80000, abs=0.5)
-    assert p.bequest == pytest.approx(855709.4, abs=0.5)
+    assert p.bequest == pytest.approx(855562.5, abs=0.5)
 
 
 def test_config1():
@@ -58,7 +58,7 @@ def test_config1():
     p.solve('maxBequest', options={'maxRothConversion': 100, 'netSpending': 80})
     assert p.caseStatus == "solved"
     assert p.basis == pytest.approx(80000, abs=0.5)
-    assert p.bequest == pytest.approx(855709.4, abs=0.5)
+    assert p.bequest == pytest.approx(855562.5, abs=0.5)
     p.saveConfig()
     base_filename = 'case_' + name
     full_filename = 'case_' + name + '.toml'
@@ -67,12 +67,12 @@ def test_config1():
     p2.solve('maxBequest', options={'maxRothConversion': 100, 'netSpending': 80})
     assert p2.caseStatus == "solved"
     assert p2.basis == pytest.approx(80000, abs=0.5)
-    assert p2.bequest == pytest.approx(855709.4, abs=0.5)
+    assert p2.bequest == pytest.approx(855562.5, abs=0.5)
     p3 = owl.readConfig(full_filename)
     p3.solve('maxBequest', options={'maxRothConversion': 100, 'netSpending': 80})
     assert p3.caseStatus == "solved"
     assert p3.basis == pytest.approx(80000, abs=0.5)
-    assert p3.bequest == pytest.approx(855709.4, abs=0.5)
+    assert p3.bequest == pytest.approx(855562.5, abs=0.5)
     os.remove(full_filename)
 
 
@@ -83,7 +83,7 @@ def test_config2():
     p.solve('maxBequest', options={'maxRothConversion': 100, 'netSpending': 80})
     assert p.caseStatus == "solved"
     assert p.basis == pytest.approx(80000, abs=0.5)
-    assert p.bequest == pytest.approx(855709.4, abs=0.5)
+    assert p.bequest == pytest.approx(855562.5, abs=0.5)
     iostring = StringIO()
     p.saveConfig(iostring)
     # print('iostream:', iostream.getvalue())
@@ -91,7 +91,7 @@ def test_config2():
     p2.solve('maxBequest', options={'maxRothConversion': 100, 'netSpending': 80})
     assert p2.caseStatus == "solved"
     assert p2.basis == pytest.approx(80000, abs=0.5)
-    assert p2.bequest == pytest.approx(855709.4, abs=0.5)
+    assert p2.bequest == pytest.approx(855562.5, abs=0.5)
 
 
 def test_clone1():
@@ -101,13 +101,13 @@ def test_clone1():
     p.solve('maxBequest', options={'maxRothConversion': 100, 'netSpending': 80})
     assert p.caseStatus == "solved"
     assert p.basis == pytest.approx(80000, abs=0.5)
-    assert p.bequest == pytest.approx(855709.4, abs=0.5)
+    assert p.bequest == pytest.approx(855562.5, abs=0.5)
     name2 = 'testclone1.2'
     p2 = owl.clone(p, name2)
     p2.solve('maxBequest', options={'maxRothConversion': 100, 'netSpending': 80})
     assert p2.caseStatus == "solved"
     assert p2.basis == pytest.approx(80000, abs=0.5)
-    assert p2.bequest == pytest.approx(855709.4, abs=0.5)
+    assert p2.bequest == pytest.approx(855562.5, abs=0.5)
 
 
 def test_clone2():
@@ -116,11 +116,11 @@ def test_clone2():
     p.setRates('historical', 1969)
     p.solve('maxSpending', options={'maxRothConversion': 100, 'bequest': 10})
     assert p.caseStatus == "solved"
-    assert p.basis == pytest.approx(97550.5, abs=0.5)
+    assert p.basis == pytest.approx(97549.8, abs=0.5)
     assert p.bequest == pytest.approx(10000, abs=0.5)
     name2 = 'testclone2.2'
     p2 = owl.clone(p, name2)
     p2.solve('maxSpending', options={'maxRothConversion': 100, 'bequest': 10})
     assert p2.caseStatus == "solved"
-    assert p2.basis == pytest.approx(97550.5, abs=0.5)
+    assert p2.basis == pytest.approx(97549.8, abs=0.5)
     assert p2.bequest == pytest.approx(10000, abs=0.5)

{owlplanner-2025.12.3 → owlplanner-2025.12.5}/ui/About_Owl.py

@@ -42,7 +42,7 @@ It can also run on [MOSEK](https://mosek.com) if available on your computer.
  Dale Seng (sengsational) for great insights and suggestions,
  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 for bug fixes.
+ Benjamin Quinn (blquinn) and Gene Wood (gene1wood) for improvements and bug fixes.
 - Owl image is from [freepik](https://freepik.com).
 
 #### :orange[Bugs and Feature Requests]

{owlplanner-2025.12.3 → owlplanner-2025.12.5}/ui/Documentation.py

@@ -275,19 +275,28 @@ by reloading the same **Wages and Contributions** file.
 #### :material/currency_exchange: Fixed Income
 This page is for entering data related to the individual's anticipated fixed income
 from pensions and social security.
-Unlike other parts of the interface, amounts on this page are
+Unlike other parts of the user interface, amounts on this page are
 monthly amounts in today's \\$ and not in thousands.
 The monthly amounts to be entered for social security are the Primary Insurance Amounts (PIA)
-as reported on annual statements issued by the Social Security Administration (SSA).
-The PIA monthly amounts are always reported in today's \\$ by the SSA.
-Before the full retirement age (FRA),
-the current value of the PIA is close to the amount reported for disability benefits.
-The SSA also provides a future estimate of the PIA at FRA by projecting current
-earnings until reaching FRA. For individuals planning to continue to work, use the projection at FRA
-or use a future benefit calculator such
-as the one provided by [SSA](https://www.ssa.gov/OACT/quickcalc/).
-For those part of the FIRE crowd and planning to retire early,
-the number reported for disability benefits should be used instead.
+which are a critical part used for calculating benefits by the Social Security Administration (SSA).
+The PIA monthly amounts are always in today's \\$. It is equivalent to the monthly benefit
+that you would receive at full retirement age (FRA), which varies between 65 and 67 depending
+on your birth year.
+The SSA also provides a future estimate of benefits at FRA by projecting current
+earnings until reaching FRA. You can use this number if you are comfortable
+with the underlying assumption that you will continue to work until FRA, at a salary
+similar to last year's.
+A way to get a more robust PIA estimate
+is to use an online calculator such as [ssa.tools](https://ssa.tools/calculator).
+To use this tool, you will need to get your full earning records from your personal account
+on the SSA website. Copy the table listing your records from the SSA web page and paste
+into the tool. Follow instructions carefully and do not cut from the PDF version
+as it can contain aggregated years.
+Please see
+[this page](https://ssa.tools/guides/earnings-record-paste) for common input errors.
+After making sure that all entries are valid, paste in the tool.
+Enter your birth year and month and the number of years you are planning
+to continue to work, if any.
 
 Owl considers the exact FRA associated with the individual's birth year and adjusts the PIA
 according to the age (year and month) when benefits are claimed. Total amount received

{owlplanner-2025.12.3 → owlplanner-2025.12.5}/ui/Fixed_Income.py

@@ -52,6 +52,7 @@ else:
         msg1 = "This is the **monthly** amount at Full Retirement Age (FRA)."
         msg2 = "Starting age of benefits in years and months."
         getIntInput(0, "ssAmt", "**monthly** PIA amount (in today's \\$)", helpmsg=msg1)
+        st.markdown(f"Use this [tool](https://ssa.tools/calculator) to get {kz.getCaseKey('iname0')}'s PIA.")
         incol1, incol2 = st.columns(2, gap="large", vertical_alignment="top")
         with incol1:
             ret = getIntInput(0, "ssAge_y", "claiming at age...", 67, msg2, max_val=70)
@@ -62,12 +63,13 @@ else:
     with col2:
         if kz.getCaseKey("status") == "married":
             getIntInput(1, "ssAmt", "**monthly** PIA amount (in today's \\$)", helpmsg=msg1)
+            st.markdown(f"Use this [tool](https://ssa.tools/calculator) to get {kz.getCaseKey('iname1')}'s PIA.")
             incol1, incol2 = st.columns(2, gap="large", vertical_alignment="top")
             with incol1:
                 ret = getIntInput(1, "ssAge_y", "claiming at age...", 67, msg2, max_val=70)
             with incol2:
                 maxmonth = 0 if ret == 70 else 11
-                getIntInput(-1, "ssAge_m", "...and month(s)", 0, msg2, max_val=maxmonth, prompt=False)
+                getIntInput(1, "ssAge_m", "...and month(s)", 0, msg2, max_val=maxmonth, prompt=False)
 
     st.divider()
     st.write("#### :orange[Pension]")

{owlplanner-2025.12.3 → owlplanner-2025.12.5}/ui/Quick_Start.py

@@ -7,20 +7,22 @@ with col3:
     st.image("http://github.com/mdlacasse/Owl/blob/main/docs/images/owl.png?raw=true")
     st.caption("Retirement planner with great wisdom")
 with col1:
-    st.write("# :orange[Welcome to Owl - Optimal Wealth Lab]\nA retirement financial exploration tool based on linear programming")
+    st.write("""# :orange[Welcome to Owl - Optimal Wealth Lab]
+\nA retirement financial exploration tool based on linear programming""")
     kz.divider("orange")
     st.write("### :material/campaign: News")
     st.markdown("""
 This version :mega: includes:
 - A much improved social security calculator.
-New approach is to use the monthly Primary Insurance Amount as reported in statements from
-the Social Security Administration.
-- Month granularity for birthday and fixed income claiming age. This approach enables
-more precise calculations for determining benefits and for representing potentially partial
-years when social security starts.
+New approach uses the monthly Primary Insurance Amount as reported in
+personal statements issued by the Social Security Administration.
+- Month granularity for birth and fixed-income claiming age. This addition enables
+more accurate calculations for determining benefits and for capturing partial
+year of benefits when social security starts.
 
-Older case files can be read, but please verify your birthday month
-and the `Fixed Income` page to ensure your information is correctly entered.
+Older case files can be read, but please verify your birth month
+and the `Fixed Income` page to ensure your information is correctly entered
+(Hint: Use `duplicate` for updating birth month).
 
 As always, please report bugs :bug: and suggestions through the
 GitHub [channel](http://github.com/mdlacasse/Owl/issues)
@@ -33,8 +35,8 @@ Take the time to give a :star: on GitHub if you use Owl. That's all you have to
     st.write("### :material/rocket_launch: Quick Start")
     st.markdown("""
 To respect your privacy, Owl does not store any information related to a case:
-all is lost after a session is closed. For this reason,
-two files can be used to store the specifications of a case so that it can be reproduced
+all informattion is lost after a session is closed. For this reason,
+two ancillary files can be used to store the specifications of a case so that it can be reproduced
 at a later time:
 - A *case* parameter file
 specifying account balances, asset allocation, social security and pension, rates,

owlplanner-2025.12.3/src/owlplanner/version.py

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