owlplanner 2025.2.8__tar.gz → 2025.2.10__tar.gz

{owlplanner-2025.2.8 → owlplanner-2025.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owlplanner
-Version: 2025.2.8
+Version: 2025.2.10
 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.8 → owlplanner-2025.2.10}/docs/owl.tex

@@ -205,7 +205,7 @@ Parameter values are either set by the user, historical data, or by the tax code
 \item [$\Gamma_{tn}$]
 	Bound for Federal income tax bracket. We define $\Gamma_{(-1)n} := 0$, so that
 	$\Gamma_{0n}$ is the upper bound for the 10\% tax bracket in year $n$. As the filing status
-		can change for couples, and so can the tax code, $\Gamma_{tn}$ will be changing over $n$.
+	can change for couples, and so can the tax code, $\Gamma_{tn}$ will be changing over $n$.
 \item [$\Delta_{tn}$]
 	Difference between upper bound $\Gamma_t$ and lower bound $\Gamma_{t-1}$
 	of a federal income tax bracket,

{owlplanner-2025.2.8 → owlplanner-2025.2.10}/examples/case_jack+jill.toml

@@ -24,7 +24,7 @@ Names = [ "Jack", "Jill",]
 "Social security amounts" = [ 28.4, 19.7,]
 "Social security ages" = [ 70, 62,]
 
-["Rate Selection"]
+["Rates Selection"]
 "Heirs rate on tax-deferred estate" = 30.0
 "Long-term capital gain tax rate" = 15.0
 "Dividend tax rate" = 2.0
@@ -32,7 +32,7 @@ Method = "historical"
 From = 1969
 To = 2002
 
-["Asset Allocations"]
+["Asset Allocation"]
 "Interpolation method" = "s-curve"
 "Interpolation center" = 15
 "Interpolation width" = 5

{owlplanner-2025.2.8 → owlplanner-2025.2.10}/examples/case_joe.toml

@@ -22,7 +22,7 @@ Names = [ "Joe",]
 "Social security amounts" = [ 28.4,]
 "Social security ages" = [ 67,]
 
-["Rate Selection"]
+["Rates Selection"]
 "Heirs rate on tax-deferred estate" = 30.0
 "Long-term capital gain tax rate" = 15.0
 "Dividend tax rate" = 2.0
@@ -30,7 +30,7 @@ Method = "historical average"
 From = 1969
 To = 2002
 
-["Asset Allocations"]
+["Asset Allocation"]
 "Interpolation method" = "s-curve"
 "Interpolation center" = 15
 "Interpolation width" = 5

{owlplanner-2025.2.8 → owlplanner-2025.2.10}/examples/case_john+sally.toml

@@ -24,7 +24,7 @@ Names = [ "John", "Sally",]
 "Social security amounts" = [ 36.0, 21.6,]
 "Social security ages" = [ 67, 67,]
 
-["Rate Selection"]
+["Rates Selection"]
 "Heirs rate on tax-deferred estate" = 30.0
 "Long-term capital gain tax rate" = 15.0
 "Dividend tax rate" = 2.0
@@ -32,7 +32,7 @@ Method = "historical average"
 From = 1990
 To = 2023
 
-["Asset Allocations"]
+["Asset Allocation"]
 "Interpolation method" = "linear"
 "Interpolation center" = 15
 "Interpolation width" = 5

{owlplanner-2025.2.8 → owlplanner-2025.2.10}/examples/case_kim+sam-bequest.toml

@@ -24,7 +24,7 @@ Names = [ "Kim", "Sam",]
 "Social security amounts" = [ 45.0, 25.0,]
 "Social security ages" = [ 70, 68,]
 
-["Rate Selection"]
+["Rates Selection"]
 "Heirs rate on tax-deferred estate" = 33.0
 "Long-term capital gain tax rate" = 15.0
 "Dividend tax rate" = 2.0
@@ -32,7 +32,7 @@ Method = "conservative"
 From = 1922
 To = 2023
 
-["Asset Allocations"]
+["Asset Allocation"]
 "Interpolation method" = "s-curve"
 "Interpolation center" = 15
 "Interpolation width" = 5

{owlplanner-2025.2.8 → owlplanner-2025.2.10}/examples/case_kim+sam-spending.toml

@@ -24,7 +24,7 @@ Names = [ "Kim", "Sam",]
 "Social security amounts" = [ 45.0, 25.0,]
 "Social security ages" = [ 70, 68,]
 
-["Rate Selection"]
+["Rates Selection"]
 "Heirs rate on tax-deferred estate" = 33.0
 "Long-term capital gain tax rate" = 15.0
 "Dividend tax rate" = 2.0
@@ -32,7 +32,7 @@ Method = "conservative"
 From = 1922
 To = 2023
 
-["Asset Allocations"]
+["Asset Allocation"]
 "Interpolation method" = "s-curve"
 "Interpolation center" = 15
 "Interpolation width" = 5

{owlplanner-2025.2.8 → owlplanner-2025.2.10}/pyproject.toml

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

{owlplanner-2025.2.8 → owlplanner-2025.2.10}/src/owlplanner/abcapi.py

@@ -43,7 +43,7 @@ class Row(object):
         """
         Add an element at index ``ind`` of value ``val`` to the row.
         """
-        assert 0 <= ind and ind < self.nvars, 'Index %d out of range.' % ind
+        assert 0 <= ind and ind < self.nvars, f"Index {ind} out of range."
         self.ind.append(ind)
         self.val.append(val)
 
@@ -96,11 +96,11 @@ class ConstraintMatrix(object):
         self.lb.append(lb)
         self.ub.append(ub)
         if lb == ub:
-            self.key.append('fx')
+            self.key.append("fx")
         elif ub == np.inf:
-            self.key.append('lo')
+            self.key.append("lo")
         else:
-            self.key.append('ra')
+            self.key.append("ra")
         self.ncons += 1
 
     def addNewRow(self, rowDic, lb, ub):
@@ -154,39 +154,39 @@ class Bounds(object):
         self.integrality = []
 
     def setBinary(self, ii):
-        assert 0 <= ii and ii < self.nvars, 'Index %d out of range.' % ii
+        assert 0 <= ii and ii < self.nvars, f"Index {ii} out of range."
         self.ind.append(ii)
         self.lb.append(0)
         self.ub.append(1)
-        self.key.append('ra')
+        self.key.append("ra")
         self.integrality.append(ii)
 
     def set0_Ub(self, ii, ub):
-        assert 0 <= ii and ii < self.nvars, 'Index %d out of range.' % ii
+        assert 0 <= ii and ii < self.nvars, f"Index {ii} out of range."
         self.ind.append(ii)
         self.lb.append(0)
         self.ub.append(ub)
-        self.key.append('ra')
+        self.key.append("ra")
 
     def setLb_Inf(self, ii, lb):
-        assert 0 <= ii and ii < self.nvars, 'Index %d out of range.' % ii
+        assert 0 <= ii and ii < self.nvars, f"Index {ii} out of range."
         self.ind.append(ii)
         self.lb.append(lb)
         self.ub.append(np.inf)
-        self.key.append('lo')
+        self.key.append("lo")
 
     def setRange(self, ii, lb, ub):
-        assert 0 <= ii and ii < self.nvars, 'Index %d out of range.' % ii
+        assert 0 <= ii and ii < self.nvars, f"Index {ii} out of range."
         self.ind.append(ii)
         self.lb.append(lb)
         self.ub.append(ub)
         if lb == ub:
-            self.key.append('fx')
+            self.key.append("fx")
         else:
-            self.key.append('ra')
+            self.key.append("ra")
 
     def keys(self):
-        keys = ['lo'] * self.nvars
+        keys = ["lo"] * self.nvars
         for ii in range(len(self.ind)):
             keys[self.ind[ii]] = self.key[ii]
 
@@ -223,7 +223,7 @@ class Objective(object):
         self.val = []
 
     def setElem(self, ind, val):
-        assert 0 <= ind and ind < self.nvars, 'Index %d out of range.' % ind
+        assert 0 <= ind and ind < self.nvars, f"Index {ind} out of range."
         self.ind.append(ind)
         self.val.append(val)
 

owlplanner-2025.2.10/src/owlplanner/config.py

@@ -0,0 +1,299 @@
+"""
+
+Owl/conftoml
+
+This file contains utility functions to save case parameters.
+
+Copyright (C) 2024 -- Martin-D. Lacasse
+
+Disclaimer: This program comes with no guarantee. Use at your own risk.
+"""
+
+import toml as toml
+from io import StringIO, BytesIO
+import numpy as np
+import os
+
+from owlplanner import plan
+from owlplanner import logging
+from owlplanner.rates import FROM, TO
+
+
+def saveConfig(plan, file, mylog):
+    """
+    Save case parameters and return a dictionary containing all parameters.
+    """
+    # np.set_printoptions(legacy='1.21')
+    accountTypes = ["taxable", "tax-deferred", "tax-free"]
+
+    diconf = {}
+    diconf["Plan Name"] = plan._name
+
+    # Basic Info.
+    diconf["Basic Info"] = {
+        "Status": ["unknown", "single", "married"][plan.N_i],
+        "Names": plan.inames,
+        "Birth year": plan.yobs.tolist(),
+        "Life expectancy": plan.expectancy.tolist(),
+        "Start date": plan.startDate,
+    }
+
+    # Assets.
+    diconf["Assets"] = {}
+    for j in range(plan.N_j):
+        amounts = plan.beta_ij[:, j] / 1000
+        diconf["Assets"][f"{accountTypes[j]} savings balances"] = amounts.tolist()
+    if plan.N_i == 2:
+        diconf["Assets"]["Beneficiary fractions"] = plan.phi_j.tolist()
+        diconf["Assets"]["Spousal surplus deposit fraction"] = plan.eta
+
+    # Wages and Contributions.
+    diconf["Wages and Contributions"] = {"Contributions file name": plan.timeListsFileName}
+
+    # Fixed Income.
+    diconf["Fixed Income"] = {
+        "Pension amounts": (plan.pensionAmounts / 1000).tolist(),
+        "Pension ages": plan.pensionAges.tolist(),
+        "Pension indexed": plan.pensionIndexed,
+        "Social security amounts": (plan.ssecAmounts / 1000).tolist(),
+        "Social security ages": plan.ssecAges.tolist(),
+    }
+
+    # Rates Selection.
+    diconf["Rates Selection"] = {
+        "Heirs rate on tax-deferred estate": float(100 * plan.nu),
+        "Long-term capital gain tax rate": float(100 * plan.psi),
+        "Dividend tax rate": float(100 * plan.mu),
+        "Method": plan.rateMethod,
+    }
+    if plan.rateMethod in ["user", "stochastic"]:
+        diconf["Rates Selection"]["Values"] = (100 * plan.rateValues).tolist()
+    if plan.rateMethod in ["stochastic"]:
+        diconf["Rates Selection"]["Standard deviations"] = (100 * plan.rateStdev).tolist()
+        diconf["Rates Selection"]["Correlations"] = plan.rateCorr.tolist()
+    if plan.rateMethod in ["historical average", "historical", "histochastic"]:
+        diconf["Rates Selection"]["From"] = int(plan.rateFrm)
+        diconf["Rates Selection"]["To"] = int(plan.rateTo)
+    else:
+        diconf["Rates Selection"]["From"] = int(FROM)
+        diconf["Rates Selection"]["To"] = int(TO)
+
+    # Asset Allocation.
+    diconf["Asset Allocation"] = {
+        "Interpolation method": plan.interpMethod,
+        "Interpolation center": float(plan.interpCenter),
+        "Interpolation width": float(plan.interpWidth),
+        "Type": plan.ARCoord,
+    }
+    if plan.ARCoord == "account":
+        for accType in accountTypes:
+            diconf["Asset Allocation"][accType] = plan.boundsAR[accType]
+    else:
+        diconf["Asset Allocation"]["generic"] = plan.boundsAR["generic"]
+
+    # Optimization Parameters.
+    diconf["Optimization Parameters"] = {
+        "Spending profile": plan.spendingProfile,
+        "Surviving spouse spending percent": int(100 * plan.chi),
+    }
+    if plan.spendingProfile == "smile":
+        diconf["Optimization Parameters"]["Smile dip"] = int(plan.smileDip)
+        diconf["Optimization Parameters"]["Smile increase"] = int(plan.smileIncrease)
+        diconf["Optimization Parameters"]["Smile delay"] = int(plan.smileDelay)
+
+    diconf["Optimization Parameters"]["Objective"] = plan.objective
+    diconf["Solver Options"] = plan.solverOptions
+
+    # Results.
+    diconf["Results"] = {"Default plots": plan.defaultPlots}
+
+    if isinstance(file, str):
+        filename = file
+        if not file.endswith(".toml"):
+            filename = filename + ".toml"
+        if not filename.startswith("case_"):
+            filename = "case_" + filename
+        mylog.vprint(f"Saving plan case file as '{filename}'.")
+
+        try:
+            with open(filename, "w") as casefile:
+                toml.dump(diconf, casefile, encoder=toml.TomlNumpyEncoder())
+        except Exception as e:
+            raise RuntimeError(f"Failed to save case file {filename}: {e}")
+    elif isinstance(file, StringIO):
+        try:
+            string = toml.dumps(diconf, encoder=toml.TomlNumpyEncoder())
+            file.write(string)
+        except Exception as e:
+            raise RuntimeError(f"Failed to save case to StringIO: {e}")
+    elif file is None:
+        pass
+    else:
+        raise ValueError(f"Argument {type(file)} has unknown type")
+
+    return diconf
+
+
+def readConfig(file, *, verbose=True, logstreams=None, readContributions=True):
+    """
+    Read plan parameters from case file *basename*.toml.
+    A new plan is created and returned.
+    Argument file can be a filename, a file, or a stringIO.
+    """
+    mylog = logging.Logger(verbose, logstreams)
+
+    accountTypes = ["taxable", "tax-deferred", "tax-free"]
+
+    dirname = ""
+    if isinstance(file, str):
+        filename = file
+        dirname = os.path.dirname(filename)
+        if not filename.endswith(".toml"):
+            filename = filename + ".toml"
+
+        mylog.vprint(f"Reading plan from case file '{filename}'.")
+
+        try:
+            with open(filename, "r") as f:
+                diconf = toml.load(f)
+        except Exception as e:
+            raise FileNotFoundError(f"File {filename} not found: {e}")
+    elif isinstance(file, BytesIO):
+        try:
+            string = file.getvalue().decode("utf-8")
+            diconf = toml.loads(string)
+        except Exception as e:
+            raise RuntimeError(f"Cannot read from BytesIO: {e}")
+    elif isinstance(file, StringIO):
+        try:
+            string = file.getvalue()
+            diconf = toml.loads(string)
+        except Exception as e:
+            raise RuntimeError(f"Cannot read from StringIO: {e}")
+    else:
+        raise ValueError(f"Type {type(file)} not a valid type")
+
+    # Basic Info.
+    name = diconf["Plan Name"]
+    inames = diconf["Basic Info"]["Names"]
+    # status = diconf['Basic Info']['Status']
+    yobs = diconf["Basic Info"]["Birth year"]
+    expectancy = diconf["Basic Info"]["Life expectancy"]
+    startDate = diconf["Basic Info"]["Start date"]
+    icount = len(yobs)
+    s = ["", "s"][icount - 1]
+    mylog.vprint(f"Plan for {icount} individual{s}: {inames}.")
+    p = plan.Plan(inames, yobs, expectancy, name, startDate=startDate, verbose=True, logstreams=logstreams)
+
+    # Assets.
+    balances = {}
+    for acc in accountTypes:
+        balances[acc] = diconf["Assets"][f"{acc} savings balances"]
+    p.setAccountBalances(
+        taxable=balances["taxable"], taxDeferred=balances["tax-deferred"], taxFree=balances["tax-free"]
+    )
+    if icount == 2:
+        phi_j = diconf["Assets"]["Beneficiary fractions"]
+        p.setBeneficiaryFractions(phi_j)
+        eta = diconf["Assets"]["Spousal surplus deposit fraction"]
+        p.setSpousalDepositFraction(eta)
+
+    # Wages and Contributions.
+    timeListsFileName = diconf["Wages and Contributions"]["Contributions file name"]
+    if timeListsFileName != "None":
+        if readContributions:
+            if os.path.exists(timeListsFileName):
+                myfile = timeListsFileName
+            elif dirname != "" and os.path.exists(dirname + "/" + timeListsFileName):
+                myfile = dirname + "/" + timeListsFileName
+            else:
+                raise FileNotFoundError(f"File '{timeListsFileName}' not found.")
+            p.readContributions(myfile)
+        else:
+            p.timeListsFileName = timeListsFileName
+            mylog.vprint(f"Ignoring to read contributions file {timeListsFileName}.")
+
+    # Fixed Income.
+    ssecAmounts = np.array(diconf["Fixed Income"]["Social security amounts"], dtype=np.float32)
+    ssecAges = np.array(diconf["Fixed Income"]["Social security ages"], dtype=np.int32)
+    p.setSocialSecurity(ssecAmounts, ssecAges)
+    pensionAmounts = np.array(diconf["Fixed Income"]["Pension amounts"], dtype=np.float32)
+    pensionAges = np.array(diconf["Fixed Income"]["Pension ages"], dtype=np.int32)
+    pensionIndexed = diconf["Fixed Income"]["Pension indexed"]
+    p.setPension(pensionAmounts, pensionAges, pensionIndexed)
+
+    # Rates Selection.
+    p.setDividendRate(float(diconf["Rates Selection"]["Dividend tax rate"]))
+    p.setLongTermCapitalTaxRate(float(diconf["Rates Selection"]["Long-term capital gain tax rate"]))
+    p.setHeirsTaxRate(float(diconf["Rates Selection"]["Heirs rate on tax-deferred estate"]))
+
+    frm = None
+    to = None
+    rateValues = None
+    stdev = None
+    rateCorr = None
+    rateMethod = diconf["Rates Selection"]["Method"]
+    if rateMethod in ["historical average", "historical", "histochastic"]:
+        frm = diconf["Rates Selection"]["From"]
+        if not isinstance(frm, int):
+            frm = int(frm)
+        to = int(diconf["Rates Selection"]["To"])
+        if not isinstance(to, int):
+            to = int(to)
+    if rateMethod in ["user", "stochastic"]:
+        rateValues = np.array(diconf["Rates Selection"]["Values"], dtype=np.float32)
+    if rateMethod in ["stochastic"]:
+        stdev = np.array(diconf["Rates Selection"]["Standard deviations"], dtype=np.float32)
+        rateCorr = np.array(diconf["Rates Selection"]["Correlations"], dtype=np.float32)
+    p.setRates(rateMethod, frm, to, rateValues, stdev, rateCorr)
+
+    # Asset Allocation.
+    boundsAR = {}
+    p.setInterpolationMethod(
+        diconf["Asset Allocation"]["Interpolation method"],
+        float(diconf["Asset Allocation"]["Interpolation center"]),
+        float(diconf["Asset Allocation"]["Interpolation width"]),
+    )
+    allocType = diconf["Asset Allocation"]["Type"]
+    if allocType == "account":
+        for aType in accountTypes:
+            boundsAR[aType] = np.array(diconf["Asset Allocation"][aType], dtype=np.float32)
+
+        p.setAllocationRatios(
+            allocType,
+            taxable=boundsAR["taxable"],
+            taxDeferred=boundsAR["tax-deferred"],
+            taxFree=boundsAR["tax-free"],
+        )
+    elif allocType == "individual" or allocType == "spouses":
+        boundsAR["generic"] = np.array(diconf["Asset Allocation"]["generic"], dtype=np.float32)
+        p.setAllocationRatios(
+            allocType,
+            generic=boundsAR["generic"],
+        )
+    else:
+        raise ValueError(f"Unknown asset allocation type {allocType}.")
+
+    # Optimization Parameters.
+    p.objective = diconf["Optimization Parameters"]["Objective"]
+
+    profile = diconf["Optimization Parameters"]["Spending profile"]
+    survivor = int(diconf["Optimization Parameters"]["Surviving spouse spending percent"])
+    if profile == "smile":
+        dip = int(diconf["Optimization Parameters"]["Smile dip"])
+        increase = int(diconf["Optimization Parameters"]["Smile increase"])
+        delay = int(diconf["Optimization Parameters"]["Smile delay"])
+    else:
+        dip = 15
+        increase = 12
+        delay = 0
+
+    p.setSpendingProfile(profile, survivor, dip, increase, delay)
+
+    # Solver Options.
+    p.solverOptions = diconf["Solver Options"]
+
+    # Results.
+    p.setDefaultPlots(diconf["Results"]["Default plots"])
+
+    return p

{owlplanner-2025.2.8 → owlplanner-2025.2.10}/src/owlplanner/logging.py

@@ -19,15 +19,15 @@ class Logger(object):
         self._prevState = self._verbose
         if logstreams is None or logstreams == [] or len(logstreams) > 2:
             self._logstreams = [sys.stdout, sys.stderr]
-            self.vprint('Using stdout and stderr as stream loggers.')
+            self.vprint("Using stdout and stderr as stream loggers.")
         elif len(logstreams) == 2:
             self._logstreams = logstreams
-            self.vprint('Using logstreams as stream loggers.')
+            self.vprint("Using logstreams as stream loggers.")
         elif len(logstreams) == 1:
-            self._logstreams = 2*logstreams
-            self.vprint('Using logstream as stream logger.')
+            self._logstreams = 2 * logstreams
+            self.vprint("Using logstream as stream logger.")
         else:
-            raise ValueError('Log streams %r must be a list.' % logstreams)
+            raise ValueError(f"Log streams {logstreams} must be a list.")
 
     def setVerbose(self, verbose=True):
         """
@@ -36,7 +36,7 @@ class Logger(object):
         """
         self._prevState = self._verbose
         self._verbose = verbose
-        self.vprint('Setting verbose to', verbose)
+        self.vprint("Setting verbose to", verbose)
 
         return self._prevState
 
@@ -51,9 +51,9 @@ class Logger(object):
         Unconditional printing regardless of the value of the verbose variable
         previously set.
         """
-        if 'file' not in kwargs:
+        if "file" not in kwargs:
             file = self._logstreams[0]
-            kwargs['file'] = file
+            kwargs["file"] = file
 
         print(*args, **kwargs)
         file.flush()
@@ -71,14 +71,14 @@ class Logger(object):
         Print message and exit. Use to print error messages on stderr.
         The exit() used throws an exception in an interactive environment.
         """
-        if 'file' not in kwargs:
+        if "file" not in kwargs:
             file = self._logstreams[1]
-            kwargs['file'] = file
+            kwargs["file"] = file
 
         if self._verbose:
-            print('ERROR:', *args, **kwargs)
-            print('Exiting...')
+            print("ERROR:", *args, **kwargs)
+            print("Exiting...")
             file.flush()
 
-        raise Exception('Fatal error.')
+        raise Exception("Fatal error.")
         # sys.exit(-1)