owlplanner 2025.12.20__py3-none-any.whl → 2026.2.2__py3-none-any.whl

owlplanner/plotting/__init__.py

@@ -1,10 +1,23 @@
 """
-Plotting backends for Owl.
+Plotting backends package for Owl retirement planner.
 
-Copyright © 2025 - Martin-D. Lacasse
+This package provides a factory pattern for creating plot backends (matplotlib,
+plotly) for visualizing retirement planning results.
 
-Disclaimers: This code is for educatonal purposes only and does not constitute financial advice.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 from .factory import PlotFactory

owlplanner/plotting/base.py

@@ -1,10 +1,24 @@
 """
-Base classes for plot backends.
+Abstract base classes for plot backends.
 
-Copyright © 2025 - Martin-D. Lacasse
+This module defines the abstract base class interface that all plotting
+backends must implement for consistent plotting functionality across
+different visualization libraries.
 
-Disclaimers: This code is for educatonal purposes only and does not constitute financial advice.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 from abc import ABC, abstractmethod

owlplanner/plotting/factory.py

@@ -1,10 +1,23 @@
 """
-Factory for creating plot backends.
+Factory for creating plot backend instances.
 
-Copyright © 2025 - Martin-D. Lacasse
+This module provides a factory class to create plot backends (matplotlib or
+plotly) based on the specified backend type.
 
-Disclaimers: This code is for educatonal purposes only and does not constitute financial advice.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 from .base import PlotBackend

owlplanner/plotting/matplotlib_backend.py

@@ -1,10 +1,23 @@
 """
-Matplotlib implementation of plot backend.
+Matplotlib backend implementation for plotting retirement planning results.
 
-Copyright © 2025 - Martin-D. Lacasse
+This module provides the Matplotlib-based implementation of the plot backend
+interface for creating static visualizations of retirement planning data.
 
-Disclaimers: This code is for educatonal purposes only and does not constitute financial advice.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 import numpy as np
@@ -65,10 +78,20 @@ class MatplotlibBackend(PlotBackend):
         """Core function for stacked plots."""
         nonzeroSeries = {}
         for sname in snames:
-            for i in irange:
-                tmp = series[sname][i]
-                if sum(tmp) > 1.0:
-                    nonzeroSeries[sname + " " + inames[i]] = tmp
+            source_data = series[sname]
+            # Check if this is a household-level source (shape (1, N_n) when N_i > 1)
+            is_household = source_data.shape[0] == 1 and len(inames) > 1
+            if is_household:
+                # Show household total once without individual name
+                tmp = source_data[0]
+                if abs(sum(tmp)) > 1.0:  # Use abs for debts
+                    nonzeroSeries[sname] = tmp
+            else:
+                # Show per individual
+                for i in irange:
+                    tmp = source_data[i]
+                    if abs(sum(tmp)) > 1.0:  # Use abs for debts
+                        nonzeroSeries[sname + " " + inames[i]] = tmp
 
         if len(nonzeroSeries) == 0:
             return None, None

owlplanner/plotting/plotly_backend.py

@@ -1,10 +1,23 @@
 """
-Plotly implementation of plot backend.
+Plotly backend implementation for plotting retirement planning results.
 
-Copyright © 2025 - Martin-D. Lacasse
+This module provides the Plotly-based implementation of the plot backend
+interface for creating interactive visualizations of retirement planning data.
 
-Disclaimers: This code is for educatonal purposes only and does not constitute financial advice.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 import numpy as np
@@ -749,7 +762,7 @@ class PlotlyBackend(PlotBackend):
 
                 # Add each individual's data as a separate series
                 for i in range(len(inames)):
-                    if np.sum(values[i]) > 1.0:  # Only show non-zero series
+                    if np.abs(np.sum(values[i])) > 1.0:  # Only show non-zero series (use abs for debts)
                         stack_data.append((values[i], f"{namek} {inames[i]}"))
 
             # Add stacked area traces
@@ -887,7 +900,7 @@ class PlotlyBackend(PlotBackend):
         for sname in savings:
             for i in range(len(inames)):
                 data = savings[sname][i] / 1000
-                if np.sum(data) > 1.0e-3:  # Only show non-zero series
+                if np.abs(np.sum(data)) > 1.0e-3:  # Only show non-zero series (use abs for debts)
                     nonzero_series[f"{sname} {inames[i]}"] = data
 
         # Add stacked area traces for each account type
@@ -942,10 +955,20 @@ class PlotlyBackend(PlotBackend):
         # Filter out zero series and create individual series names
         nonzero_series = {}
         for sname in sources:
-            for i in range(len(inames)):
-                data = sources[sname][i] / 1000
-                if np.sum(data) > 1.0e-3:  # Only show non-zero series
-                    nonzero_series[f"{sname} {inames[i]}"] = data
+            source_data = sources[sname]
+            # Check if this is a household-level source (shape (1, N_n) when N_i > 1)
+            is_household = source_data.shape[0] == 1 and len(inames) > 1
+            if is_household:
+                # Show household total once without individual name
+                data = source_data[0] / 1000
+                if np.abs(np.sum(data)) > 1.0e-3:  # Only show non-zero series (use abs for debts)
+                    nonzero_series[sname] = data
+            else:
+                # Show per individual
+                for i in range(len(inames)):
+                    data = source_data[i] / 1000
+                    if np.abs(np.sum(data)) > 1.0e-3:  # Only show non-zero series (use abs for debts)
+                        nonzero_series[f"{sname} {inames[i]}"] = data
 
         # Add stacked area traces for each source type
         for source_name, data in nonzero_series.items():

owlplanner/progress.py

@@ -1,10 +1,23 @@
 """
-A simple object to display progress.
+Progress indicator for long-running operations.
 
-Copyright © 2024 - Martin-D. Lacasse
+This module provides a simple progress indicator class that displays
+progress as a percentage on a single line that updates in place.
 
-Disclaimers: This code is for educational purposes only and does not constitute financial advice.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 from typing import Optional

owlplanner/rates.py

@@ -1,30 +1,25 @@
 """
+Historical and statistical rate of return data for asset classes.
 
-Owl/rates
----
+This module provides historical annual rates of return for different asset
+classes: S&P500, Baa corporate bonds, real estate, 3-mo T-Bills, 10-year Treasury
+notes, and inflation as measured by CPI from 1928 to present. Values were
+extracted from NYU's Stern School of business historical returns data.
 
-A retirement planner using linear programming optimization.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
-See companion document for a complete explanation and description
-of all variables and parameters.
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
 
-This class provides the historical annual rate of returns for different
-classes of assets: S&P500, Aaa and Baa corporate bonds, 3-mo T-Bills,
-10-year Treasury notes, and inflation as measured by CPI all from
-1928 until now.
-
-Values were extracted from NYU's Stern School of business:
-https://pages.stern.nyu.edu/~adamodar/New_Home_Page/datafile/histretSP.html
-from references therein.
-
-Rate lists will need to be updated with values for current year.
-When doing so, the TO bound defined below will need to be adjusted
-to the last current data year.
-
-Copyright © 2024 - Martin-D. Lacasse
-
-Disclaimers: This code is for educational purposes only and does not constitute financial advice.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
 
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 ###################################################################
@@ -36,10 +31,21 @@ import sys
 from owlplanner import mylogging as log
 from owlplanner import utils as u
 
-# All data goes from 1928 to 2024. Update the TO value when data
+# All data goes from 1928 to 2025. Update the TO value when data
 # becomes available for subsequent years.
 FROM = 1928
-TO = 2024
+TO = 2025
+
+# Rate methods that use the same rate every year (reverse/roll are no-ops).
+CONSTANT_RATE_METHODS = (
+    "default", "optimistic", "conservative", "user",
+    "historical average", "mean",
+)
+# Rate methods that produce deterministic series (no regeneration needed).
+RATE_METHODS_NO_REGEN = (
+    "default", "optimistic", "conservative", "user",
+    "historical average", "historical",
+)
 
 where = os.path.dirname(sys.modules["owlplanner"].__file__)
 file = os.path.join(where, "data/rates.csv")
@@ -55,8 +61,8 @@ SP500 = df["S&P 500"]
 # Annual rate of return (%) of Baa Corporate Bonds since 1928.
 BondsBaa = df["Bonds Baa"]
 
-# Annual rate of return (%) of Aaa Corporate Bonds since 1928.
-BondsAaa = df["Bonds Aaa"]
+# Annual rate of return (%) of Real Estate since 1928.
+RealEstate = df["real estate"]
 
 # Annual rate of return (%) for 10-y Treasury notes since 1928.
 TNotes = df["TNotes"]
@@ -101,8 +107,8 @@ def getRatesDistributions(frm, to, mylog=None):
     stdev = df.std()
     covar = df.cov()
 
-    mylog.print("means: (%)\n", means)
-    mylog.print("standard deviation: (%)\n", stdev)
+    mylog.vprint("means: (%)\n", means)
+    mylog.vprint("standard deviation: (%)\n", stdev)
 
     # Convert to NumPy array and from percent to decimal.
     means = np.array(means) / 100.0
@@ -114,7 +120,7 @@ def getRatesDistributions(frm, to, mylog=None):
     # Fold round-off errors in proper bounds.
     corr[corr > 1] = 1
     corr[corr < -1] = -1
-    mylog.print("correlation matrix: \n\t\t%s" % str(corr).replace("\n", "\n\t\t"))
+    mylog.vprint("correlation matrix: \n\t\t%s" % str(corr).replace("\n", "\n\t\t"))
 
     return means, stdev, corr, covar
 
@@ -131,15 +137,25 @@ class Rates(object):
     then ``mySeries = r.genSeries()``
     """
 
-    def __init__(self, mylog=None):
+    def __init__(self, mylog=None, seed=None):
         """
         Default constructor.
+
+        Args:
+            mylog: Logger instance (optional)
+            seed: Random seed for reproducible stochastic rates (optional)
         """
         if mylog is None:
             self.mylog = log.Logger()
         else:
             self.mylog = mylog
 
+        # Store seed for stochastic rate generation
+        # Always use a Generator instance for thread safety and modern API
+        # If seed is None, default_rng() will use entropy/current time
+        self._seed = seed
+        self._rng = np.random.default_rng(seed)
+
         # Default rates are average over last 30 years.
         self._defRates = np.array([0.1101, 0.0736, 0.0503, 0.0251])
 
@@ -335,18 +351,18 @@ class Rates(object):
 
     def _histRates(self, n):
         """
-        Return a list of 4 values representing the historical rates
+        Return an array of 4 values representing the historical rates
         of stock, Corporate Baa bonds, Treasury notes, and inflation,
         respectively.
         """
         hrates = np.array([SP500[n], BondsBaa[n], TNotes[n], Inflation[n]])
 
-        # Convert from percent to decimal.
+        # Historical rates are stored in percent. Convert from percent to decimal.
         return hrates / 100
 
     def _stochRates(self, n):
         """
-        Return a list of 4 values representing the historical rates
+        Return an array of 4 values representing the historical rates
         of stock, Corporate Baa bonds, Treasury notes, and inflation,
         respectively. Values are pulled from normal distributions
         having the same characteristics as the historical data for
@@ -354,8 +370,8 @@ class Rates(object):
 
         But these variables need to be looked at together
         through multivariate analysis. Code below accounts for
-        covariance between stocks, bonds, and inflation.
+        covariance between stocks, corp bonds, t-notes, and inflation.
         """
-        srates = np.random.multivariate_normal(self.means, self.covar)
+        srates = self._rng.multivariate_normal(self.means, self.covar)
 
         return srates

owlplanner/socialsecurity.py

@@ -1,16 +1,23 @@
 """
+Social Security benefit calculation rules and utilities.
 
-Owl/socialsecurity
---------
+This module implements Social Security rules including full retirement age
+calculations, benefit computations, and related retirement planning functions.
 
-A retirement planner using linear programming optimization.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
-This file contains the rules related to social security.
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
 
-Copyright © 2025 - Martin-D. Lacasse
-
-Disclaimers: This code is for educational purposes only and does not constitute financial advice.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
 
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 import numpy as np
@@ -91,7 +98,7 @@ def getSpousalBenefits(pias):
     return benefits
 
 
-def getSelfFactor(fra, convage, bornOnFirst):
+def getSelfFactor(fra, convage, bornOnFirstDays):
     """
     Return the reduction/increase factor to multiply PIA based on claiming age.
 
@@ -102,7 +109,8 @@ def getSelfFactor(fra, convage, bornOnFirst):
     - After FRA: Benefits are increased by 8% per year (up to 132% at age 70)
 
     The function automatically adjusts for Social Security age if the birthday is on
-    the first day of the month (adds 1/12 year to conventional age).
+    the 1st or 2nd day of the month (adds 1/12 year to conventional age), consistent
+    with SSA rules that treat both days the same for age calculation purposes.
 
     Parameters
     ----------
@@ -111,8 +119,8 @@ def getSelfFactor(fra, convage, bornOnFirst):
     convage : float
         Conventional age when benefits start, in years (can be fractional with 1/12 increments).
         Must be between 62 and 70 inclusive.
-    bornOnFirst : bool
-        True if birthday is on the first day of the month, False otherwise.
+    bornOnFirstDays : bool
+        True if birthday is on the 1st or 2nd day of the month, False otherwise.
         If True, the function adds 1/12 year to convert to Social Security age.
 
     Returns
@@ -131,8 +139,8 @@ def getSelfFactor(fra, convage, bornOnFirst):
     if convage < 62 or convage > 70:
         raise ValueError(f"Age {convage} out of range.")
 
-    # Add a month to conventional age if born on the first.
-    offset = 0 if not bornOnFirst else 1/12
+    # Add a month to conventional age if born on the 1st or 2nd (SSA treats both the same).
+    offset = 0 if not bornOnFirstDays else 1/12
     ssage = convage + offset
 
     diff = fra - ssage
@@ -146,7 +154,7 @@ def getSelfFactor(fra, convage, bornOnFirst):
         return .8 - 0.05 * (diff - 3)
 
 
-def getSpousalFactor(fra, convage, bornOnFirst):
+def getSpousalFactor(fra, convage, bornOnFirstDays):
     """
     Return the reduction factor to multiply spousal benefits based on claiming age.
 
@@ -156,7 +164,8 @@ def getSpousalFactor(fra, convage, bornOnFirst):
     - At or after FRA: Full spousal benefit (50% of spouse's PIA, no increase for delay)
 
     The function automatically adjusts for Social Security age if the birthday is on
-    the first day of the month (adds 1/12 year to conventional age).
+    the 1st or 2nd day of the month (adds 1/12 year to conventional age), consistent
+    with SSA rules that treat both days the same for age calculation purposes.
 
     Parameters
     ----------
@@ -165,8 +174,8 @@ def getSpousalFactor(fra, convage, bornOnFirst):
     convage : float
         Conventional age when benefits start, in years (can be fractional with 1/12 increments).
         Must be at least 62 (no maximum, but no increase beyond FRA).
-    bornOnFirst : bool
-        True if birthday is on the first day of the month, False otherwise.
+    bornOnFirstDays : bool
+        True if birthday is on the 1st or 2nd day of the month, False otherwise.
         If True, the function adds 1/12 year to convert to Social Security age.
 
     Returns
@@ -185,8 +194,8 @@ def getSpousalFactor(fra, convage, bornOnFirst):
     if convage < 62:
         raise ValueError(f"Age {convage} out of range.")
 
-    # Add a month to conventional age if born on the first.
-    offset = 0 if not bornOnFirst else 1/12
+    # Add a month to conventional age if born on the 1st or 2nd (SSA treats both the same).
+    offset = 0 if not bornOnFirstDays else 1/12
     ssage = convage + offset
 
     diff = fra - ssage