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

owlplanner/config.py

@@ -81,6 +81,8 @@ _KEY_TRANSLATION = {
     "Correlations": "correlations",
     "From": "from",
     "To": "to",
+    "Reverse sequence": "reverse_sequence",
+    "Roll sequence": "roll_sequence",
     # Asset Allocation keys
     "Interpolation method": "interpolation_method",
     "Interpolation center": "interpolation_center",
@@ -266,6 +268,8 @@ def saveConfig(myplan, file, mylog):
     else:
         diconf["rates_selection"]["from"] = int(FROM)
         diconf["rates_selection"]["to"] = int(TO)
+    diconf["rates_selection"]["reverse_sequence"] = bool(myplan.rateReverse)
+    diconf["rates_selection"]["roll_sequence"] = int(myplan.rateRoll)
 
     # Asset Allocation.
     diconf["asset_allocation"] = {
@@ -427,7 +431,10 @@ def readConfig(file, *, verbose=True, logstreams=None, readContributions=True):
             rateSeed = int(rateSeed)
         reproducibleRates = diconf["rates_selection"].get("reproducible_rates", False)
         p.setReproducible(reproducibleRates, seed=rateSeed)
-    p.setRates(rateMethod, frm, to, rateValues, stdev, rateCorr)
+    reverseSequence = diconf["rates_selection"].get("reverse_sequence", False)
+    rollSequence = diconf["rates_selection"].get("roll_sequence", 0)
+    p.setRates(rateMethod, frm, to, rateValues, stdev, rateCorr,
+               reverse=reverseSequence, roll=rollSequence)
 
     # Asset Allocation.
     boundsAR = {}
@@ -473,11 +480,18 @@ def readConfig(file, *, verbose=True, logstreams=None, readContributions=True):
     p.setSpendingProfile(profile, survivor, dip, increase, delay)
 
     # Solver Options.
-    p.solverOptions = diconf["solver_options"]
+    p.solverOptions = dict(diconf["solver_options"])
+
+    # Defaults for options not present in case file (e.g. Case_joe.toml).
+    # Ensures Medicare is computed in loop mode and self-consistent loop runs.
+    if "withMedicare" not in p.solverOptions:
+        p.solverOptions["withMedicare"] = "loop"
+    if "withSCLoop" not in p.solverOptions:
+        p.solverOptions["withSCLoop"] = True
 
     # Address legacy case files.
     # Convert boolean values (True/False) to string format, but preserve string values
-    withMedicare = diconf["solver_options"].get("withMedicare")
+    withMedicare = p.solverOptions.get("withMedicare")
     if isinstance(withMedicare, bool):
         p.solverOptions["withMedicare"] = "loop" if withMedicare else "None"
 

owlplanner/plan.py

@@ -46,14 +46,26 @@ from .plotting.factory import PlotFactory
 
 
 # Default values
-BIGM_XOR = 5e7     # 100 times large withdrawals or conversions
-BIGM_IRMAA = 5e7   # 100 times large MAGI
+BIGM_AMO = 5e7     # 100 times large withdrawals or conversions
 GAP = 1e-4
 MILP_GAP = 10 * GAP
 MAX_ITERATIONS = 29
-ABS_TOL = 20
-REL_TOL = 1e-6
+ABS_TOL = 50
+REL_TOL = 5e-6
 TIME_LIMIT = 900
+EPSILON = 1e-9
+
+
+def _apply_rate_sequence_transform(tau_kn, reverse, roll):
+    """
+    Apply reverse and/or roll to a rate series (N_k x N_n).
+    Returns a new array; does not modify the input.
+    """
+    if reverse:
+        tau_kn = tau_kn[:, ::-1]
+    if roll != 0:
+        tau_kn = np.roll(tau_kn, int(roll), axis=1)
+    return tau_kn
 
 
 def _genGamma_n(tau):
@@ -398,6 +410,8 @@ class Plan:
         self.rateMethod = None
         self.reproducibleRates = False
         self.rateSeed = None
+        self.rateReverse = False
+        self.rateRoll = 0
 
         self.ARCoord = None
         self.objective = "unknown"
@@ -600,9 +614,9 @@ class Plan:
         for i in range(self.N_i):
             if amounts[i] != 0:
                 # Check if claim age added to birth month falls next year.
-                realage = ages[i] + (self.mobs[i] - 1)/12
-                iage = int(realage)
-                fraction = 1 - (realage % 1.)
+                yearage = ages[i] + (self.mobs[i] - 1)/12
+                iage = int(yearage)
+                fraction = 1 - (yearage % 1.)
                 realns = iage - thisyear + self.yobs[i]
                 ns = max(0, realns)
                 nd = self.horizons[i]
@@ -757,7 +771,8 @@ class Plan:
             # setRates() will generate a new seed each time it's called
             self.rateSeed = None
 
-    def setRates(self, method, frm=None, to=None, values=None, stdev=None, corr=None, override_reproducible=False):
+    def setRates(self, method, frm=None, to=None, values=None, stdev=None, corr=None,
+                 override_reproducible=False, reverse=False, roll=0):
         """
         Generate rates for return and inflation based on the method and
         years selected. Note that last bound is included.
@@ -780,6 +795,8 @@ class Plan:
         Args:
             override_reproducible: If True, override reproducibility setting and always generate new rates.
                                  Used by Monte-Carlo runs to ensure different rates each time.
+            reverse: If True, reverse the rate sequence along the time axis (default False).
+            roll: Number of years to roll the sequence; positive rolls toward the end (default 0).
         """
         if frm is not None and to is None:
             to = frm + self.N_n - 1  # 'to' is inclusive.
@@ -807,7 +824,15 @@ class Plan:
         self.rateMethod = method
         self.rateFrm = frm
         self.rateTo = to
+        self.rateReverse = bool(reverse)
+        self.rateRoll = int(roll)
         self.tau_kn = dr.genSeries(self.N_n).transpose()
+        # Reverse and roll are no-ops for constant (fixed) rate methods; ignore with a warning.
+        if method in rates.CONSTANT_RATE_METHODS and (reverse or roll != 0):
+            self.mylog.print("Warning: reverse and roll are ignored for constant (fixed) rate methods.")
+        else:
+            self.tau_kn = _apply_rate_sequence_transform(
+                self.tau_kn, self.rateReverse, self.rateRoll)
         self.mylog.vprint(f"Generating rate series of {len(self.tau_kn[0])} years using '{method}' method.")
         if method in ["stochastic", "histochastic"]:
             repro_status = "reproducible" if self.reproducibleRates else "non-reproducible"
@@ -831,9 +856,7 @@ class Plan:
                                  Used by Monte-Carlo runs to ensure each run gets different rates.
         """
         # Fixed rate methods don't need regeneration - they produce the same values
-        fixed_methods = ["default", "optimistic", "conservative", "user",
-                         "historical average", "historical"]
-        if self.rateMethod in fixed_methods:
+        if self.rateMethod in rates.RATE_METHODS_NO_REGEN:
             return
 
         # Only stochastic methods reach here
@@ -851,6 +874,8 @@ class Plan:
             stdev=100 * self.rateStdev,
             corr=self.rateCorr,
             override_reproducible=override_reproducible,
+            reverse=self.rateReverse,
+            roll=self.rateRoll,
         )
 
     def setAccountBalances(self, *, taxable, taxDeferred, taxFree, startDate=None, units="k"):
@@ -1318,7 +1343,7 @@ class Plan:
                 if self.pensionIsIndexed[i]:
                     self.piBar_in[i] *= gamma_n[:-1]
 
-            self.nm, self.L_nq, self.C_nq = tx.mediVals(self.yobs, self.horizons, gamma_n, self.N_n, self.N_q)
+            self.nm, self.Lbar_nq, self.Cbar_nq = tx.mediVals(self.yobs, self.horizons, gamma_n, self.N_n, self.N_q)
 
             self._adjustedParameters = True
 
@@ -1331,6 +1356,7 @@ class Plan:
         All binary variables must be lumped at the end of the vector.
         """
         medi = options.get("withMedicare", "loop") == "optimize"
+        Nmed = self.N_n - self.nm
 
         # Stack all variables in a single block vector with all binary variables at the end.
         C = {}
@@ -1339,13 +1365,17 @@ class Plan:
         C["e"] = _qC(C["d"], self.N_i, self.N_n)
         C["f"] = _qC(C["e"], self.N_n)
         C["g"] = _qC(C["f"], self.N_t, self.N_n)
-        C["m"] = _qC(C["g"], self.N_n)
+        if medi:
+            C["h"] = _qC(C["g"], self.N_n)
+            C["m"] = _qC(C["h"], Nmed, self.N_q)
+        else:
+            C["m"] = _qC(C["g"], self.N_n)
         C["s"] = _qC(C["m"], self.N_n)
         C["w"] = _qC(C["s"], self.N_n)
         C["x"] = _qC(C["w"], self.N_i, self.N_j, self.N_n)
         C["zx"] = _qC(C["x"], self.N_i, self.N_n)
         C["zm"] = _qC(C["zx"], self.N_n, self.N_zx)
-        self.nvars = _qC(C["zm"], self.N_n - self.nm, self.N_q - 1) if medi else C["zm"]
+        self.nvars = _qC(C["zm"], Nmed, self.N_q) if medi else C["zm"]
         self.nbins = self.nvars - C["zx"]
         self.nconts = C["zx"]
         self.nbals = C["d"]
@@ -1383,7 +1413,7 @@ class Plan:
         self._configure_Medicare_binary_variables(options)
         self._add_Medicare_costs(options)
         self._configure_exclusion_binary_variables(options)
-        self._build_objective_vector(objective)
+        self._build_objective_vector(objective, options)
 
     def _add_rmd_inequalities(self):
         for i in range(self.N_i):
@@ -1689,7 +1719,8 @@ class Plan:
                 rhs += self.omega_in[i, n] + self.Psi_n[n] * self.zetaBar_in[i, n] + self.piBar_in[i, n]
                 row.addElem(_q3(self.C["w"], i, 1, n, self.N_i, self.N_j, self.N_n), -1)
                 row.addElem(_q2(self.C["x"], i, n, self.N_i, self.N_n), -1)
-                fak = np.sum(self.tau_kn[1:self.N_k, n] * self.alpha_ijkn[i, 0, 1:self.N_k, n], axis=0)
+                # Only positive returns are taxable (interest/dividends); losses don't reduce income.
+                fak = np.sum(np.maximum(0, self.tau_kn[1:self.N_k, n]) * self.alpha_ijkn[i, 0, 1:self.N_k, n], axis=0)
                 rhs += 0.5 * fak * self.kappa_ijn[i, 0, n]
                 row.addElem(_q3(self.C["b"], i, 0, n, self.N_i, self.N_j, self.N_n + 1), -fak)
                 row.addElem(_q3(self.C["w"], i, 0, n, self.N_i, self.N_j, self.N_n), fak)
@@ -1702,7 +1733,7 @@ class Plan:
         if not options.get("amoConstraints", True):
             return
 
-        bigM = u.get_numeric_option(options, "bigMamo", BIGM_XOR, min_value=0)
+        bigM = u.get_numeric_option(options, "bigMamo", BIGM_AMO, min_value=0)
 
         if options.get("amoSurplus", True):
             for n in range(self.N_n):
@@ -1730,9 +1761,11 @@ class Plan:
                 )
 
         if "maxRothConversion" in options:
-            rhsopt = u.get_numeric_option(options, "maxRothConversion", 0)
-            if rhsopt < -1:
-                return
+            rhsopt = options.get("maxRothConversion")
+            if rhsopt != "file":
+                rhsopt = u.get_numeric_option(options, "maxRothConversion", 0)
+                if rhsopt < -1:
+                    return
 
         # Turning off this constraint for maxRothConversions = 0 makes solution infeasible.
         if options.get("amoRoth", True):
@@ -1764,61 +1797,92 @@ class Plan:
         if options.get("withMedicare", "loop") != "optimize":
             return
 
-        # Default: 5e7 (50 million) - bounds aggregate MAGI, typically larger than bigMamo
-        bigM = u.get_numeric_option(options, "bigMirmaa", BIGM_IRMAA, min_value=0)
-
+        bigM = u.get_numeric_option(options, "bigMamo", BIGM_AMO, min_value=0)
         Nmed = self.N_n - self.nm
-        offset = 0
-        if self.nm < 2:
-            offset = 2 - self.nm
-            for nn in range(offset):
-                n = self.nm + nn
-                for q in range(self.N_q - 1):
-                    self.A.addNewRow({_q2(self.C["zm"], nn, q, Nmed, self.N_q - 1): bigM},
-                                     self.prevMAGI[n] - self.L_nq[nn, q], np.inf)
-
-        for nn in range(offset, Nmed):
-            n2 = self.nm + nn - 2  # n - 2
-            for q in range(self.N_q - 1):
-                rhs = self.L_nq[nn, q]
-                rhs -= (self.fixed_assets_ordinary_income_n[n2]
-                        + self.fixed_assets_capital_gains_n[n2])
-                row = self.A.newRow()
+        # Select exactly one IRMAA bracket per year (SOS1 behavior).
+        for nn in range(Nmed):
+            row = self.A.newRow()
+            for q in range(self.N_q):
+                row.addElem(_q2(self.C["zm"], nn, q, Nmed, self.N_q), 1)
+            self.A.addRow(row, 1, 1)
 
-                row.addElem(_q2(self.C["zm"], nn, q, Nmed, self.N_q - 1), -bigM*self.gamma_n[nn])
-                # Using e_n slows convergence like crazy.
-                # Maybe replace with full exemption at the risk of creating negative income?
-                # rhs -= self.sigmaBar_n[n2]
-                row.addElem(_q1(self.C["e"], n2, self.N_n), +1)
-                for i in range(self.N_i):
-                    row.addElem(_q3(self.C["w"], i, 1, n2, self.N_i, self.N_j, self.N_n), +1)
-                    row.addElem(_q2(self.C["x"], i, n2, self.N_i, self.N_n), +1)
+        # MAGI decomposition into bracket portions: sum_q h_{q} = MAGI.
+        for nn in range(Nmed):
+            n = self.nm + nn
+            row = self.A.newRow()
+            for q in range(self.N_q):
+                row.addElem(_q2(self.C["h"], nn, q, Nmed, self.N_q), 1)
+
+            if n < 2:
+                self.A.addRow(row, self.prevMAGI[n], self.prevMAGI[n])
+                # Fix bracket selection for known previous MAGI.
+                magi = self.prevMAGI[n]
+                qsel = 0
+                for q in range(1, self.N_q):
+                    if magi > self.Lbar_nq[nn, q - 1]:
+                        qsel = q
+                for q in range(self.N_q):
+                    idx = _q2(self.C["zm"], nn, q, Nmed, self.N_q)
+                    val = 1 if q == qsel else 0
+                    self.B.setRange(idx, val, val)
+                continue
 
-                    # Dividends and interest gains for year n2.
-                    afac = (self.mu*self.alpha_ijkn[i, 0, 0, n2]
-                            + np.sum(self.alpha_ijkn[i, 0, 1:, n2]*self.tau_kn[1:, n2]))
+            n2 = n - 2
+            rhs = (self.fixed_assets_ordinary_income_n[n2]
+                   + self.fixed_assets_capital_gains_n[n2])
 
-                    row.addElem(_q3(self.C["b"], i, 0, n2, self.N_i, self.N_j, self.N_n + 1), +afac)
-                    row.addElem(_q2(self.C["d"], i, n2, self.N_i, self.N_n), +afac)
+            row.addElem(_q1(self.C["e"], n2, self.N_n), -1)
+            for i in range(self.N_i):
+                row.addElem(_q3(self.C["w"], i, 1, n2, self.N_i, self.N_j, self.N_n), -1)
+                row.addElem(_q2(self.C["x"], i, n2, self.N_i, self.N_n), -1)
+
+                # Dividends and interest gains for year n2. Only positive returns are taxable.
+                afac = (self.mu * self.alpha_ijkn[i, 0, 0, n2]
+                        + np.sum(self.alpha_ijkn[i, 0, 1:, n2] * np.maximum(0, self.tau_kn[1:, n2])))
+
+                row.addElem(_q3(self.C["b"], i, 0, n2, self.N_i, self.N_j, self.N_n + 1), -afac)
+                row.addElem(_q2(self.C["d"], i, n2, self.N_i, self.N_n), -afac)
+
+                # Capital gains on stocks sold from taxable account accrued in year n2 - 1.
+                # Capital gains = price appreciation only (total return - dividend rate)
+                #  to avoid double taxation of dividends.
+                tau_prev = self.tau_kn[0, max(0, n2 - 1)]
+                bfac = self.alpha_ijkn[i, 0, 0, n2] * max(0, tau_prev - self.mu)
+                row.addElem(_q3(self.C["w"], i, 0, n2, self.N_i, self.N_j, self.N_n), afac - bfac)
+
+                # MAGI includes total Social Security (taxable + non-taxable) for IRMAA.
+                sumoni = (self.omega_in[i, n2]
+                          + self.zetaBar_in[i, n2]
+                          + self.piBar_in[i, n2]
+                          + 0.5 * self.kappa_ijn[i, 0, n2] * afac)
+                rhs += sumoni
 
-                    # Capital gains on stocks sold from taxable account accrued in year n2 - 1.
-                    # Capital gains = price appreciation only (total return - dividend rate)
-                    #  to avoid double taxation of dividends.
-                    tau_prev = self.tau_kn[0, max(0, n2-1)]
-                    bfac = self.alpha_ijkn[i, 0, 0, n2] * max(0, tau_prev - self.mu)
-                    row.addElem(_q3(self.C["w"], i, 0, n2, self.N_i, self.N_j, self.N_n), -afac + bfac)
+            self.A.addRow(row, rhs, rhs)
 
-                    # MAGI includes total Social Security (taxable + non-taxable) for IRMAA.
-                    sumoni = (self.omega_in[i, n2]
-                              + self.zetaBar_in[i, n2]
-                              + self.piBar_in[i, n2]
-                              + 0.5 * self.kappa_ijn[i, 0, n2] * afac)
-                    rhs -= sumoni
+        # Bracket bounds: L_{q-1} z_q <= mg_q <= L_q z_q.
+        for nn in range(Nmed):
+            for q in range(self.N_q):
+                mg_idx = _q2(self.C["h"], nn, q, Nmed, self.N_q)
+                zm_idx = _q2(self.C["zm"], nn, q, Nmed, self.N_q)
 
-                self.A.addRow(row, -np.inf, rhs)
+                lower = 0 if q == 0 else self.Lbar_nq[nn, q - 1]
+                if lower > 0:
+                    self.A.addNewRow({mg_idx: 1, zm_idx: -lower}, 0, np.inf)
+
+                if q < self.N_q - 1:
+                    upper = self.Lbar_nq[nn, q]
+                    self.A.addNewRow({mg_idx: 1, zm_idx: -upper}, -np.inf, 0)
+                else:
+                    # Upper bound for last bracket so h_qn = 0 when z_q = 0.
+                    upper = bigM * self.gamma_n[self.nm + nn]
+                    self.A.addNewRow({mg_idx: 1, zm_idx: -upper}, -np.inf, 0)
 
     def _add_Medicare_costs(self, options):
         if options.get("withMedicare", "loop") != "optimize":
+            # In loop mode, Medicare costs are computed outside the solver (M_n).
+            # Ensure the in-model Medicare variable (m_n) stays at zero.
+            for n in range(self.N_n):
+                self.B.setRange(_q1(self.C["m"], n, self.N_n), 0, 0)
             return
 
         for n in range(self.nm):
@@ -1829,30 +1893,54 @@ class Plan:
             n = self.nm + nn
             row = self.A.newRow()
             row.addElem(_q1(self.C["m"], n, self.N_n), 1)
-            for q in range(self.N_q - 1):
-                row.addElem(_q2(self.C["zm"], nn, q, Nmed, self.N_q - 1), -self.C_nq[nn, q+1])
-            self.A.addRow(row, self.C_nq[nn, 0], self.C_nq[nn, 0])
+            for q in range(self.N_q):
+                row.addElem(_q2(self.C["zm"], nn, q, Nmed, self.N_q), -self.Cbar_nq[nn, q])
+            self.A.addRow(row, 0, 0)
 
-    def _build_objective_vector(self, objective):
-        c = abc.Objective(self.nvars)
+    def _build_objective_vector(self, objective, options):
+        c_arr = np.zeros(self.nvars)
         if objective == "maxSpending":
             for n in range(self.N_n):
-                c.setElem(_q1(self.C["g"], n, self.N_n), -1/self.gamma_n[n])
+                c_arr[_q1(self.C["g"], n, self.N_n)] = -1/self.gamma_n[n]
         elif objective == "maxBequest":
             for i in range(self.N_i):
-                c.setElem(_q3(self.C["b"], i, 0, self.N_n, self.N_i, self.N_j, self.N_n + 1), -1)
-                c.setElem(_q3(self.C["b"], i, 1, self.N_n, self.N_i, self.N_j, self.N_n + 1), -(1 - self.nu))
-                c.setElem(_q3(self.C["b"], i, 2, self.N_n, self.N_i, self.N_j, self.N_n + 1), -1)
+                c_arr[_q3(self.C["b"], i, 0, self.N_n, self.N_i, self.N_j, self.N_n + 1)] = -1
+                c_arr[_q3(self.C["b"], i, 1, self.N_n, self.N_i, self.N_j, self.N_n + 1)] = -(1 - self.nu)
+                c_arr[_q3(self.C["b"], i, 2, self.N_n, self.N_i, self.N_j, self.N_n + 1)] = -1
         else:
             raise RuntimeError("Internal error in objective function.")
+
+        # Turn on epsilon by default when optimizing Medicare.
+        withMedicare = options.get("withMedicare", "loop")
+        default_epsilon = EPSILON if withMedicare == "optimize" else 0
+        epsilon = u.get_numeric_option(options, "epsilon", default_epsilon, min_value=0)
+        if epsilon > 0:
+            # Penalize Roth conversions to reduce churn.
+            for i in range(self.N_i):
+                for n in range(self.N_n):
+                    c_arr[_q2(self.C["x"], i, n, self.N_i, self.N_n)] += epsilon
+
+            if self.N_i == 2:
+                # Favor withdrawals from spouse 0 by penalizing spouse 1 withdrawals.
+                for j in range(self.N_j):
+                    for n in range(self.N_n):
+                        c_arr[_q3(self.C["w"], 1, j, n, self.N_i, self.N_j, self.N_n)] += epsilon
+
+        c = abc.Objective(self.nvars)
+        for idx in np.flatnonzero(c_arr):
+            c.setElem(idx, c_arr[idx])
         self.c = c
 
     @_timer
-    def runHistoricalRange(self, objective, options, ystart, yend, *, verbose=False, figure=False, progcall=None):
+    def runHistoricalRange(self, objective, options, ystart, yend, *, verbose=False, figure=False,
+                           progcall=None, reverse=False, roll=0):
         """
         Run historical scenarios on plan over a range of years.
-        """
 
+        For each year in [ystart, yend], rates are set to the historical sequence
+        starting at that year. Optional reverse and roll apply to each sequence
+        (same semantics as setRates).
+        """
         if yend + self.N_n > self.year_n[0]:
             yend = self.year_n[0] - self.N_n - 1
             self.mylog.print(f"Warning: Upper bound for year range re-adjusted to {yend}.")
@@ -1882,7 +1970,7 @@ class Plan:
             progcall.start()
 
         for year in range(ystart, yend + 1):
-            self.setRates("historical", year)
+            self.setRates("historical", year, reverse=reverse, roll=roll)
             self.solve(objective, options)
             if not verbose:
                 progcall.show((year - ystart + 1) / N)
@@ -2002,8 +2090,8 @@ class Plan:
             "amoRoth",
             "amoSurplus",
             "bequest",
-            "bigMirmaa",  # Big-M value for Medicare IRMAA constraints (default: 5e7)
-            "bigMamo",    # Big-M value for XOR constraints (default: 5e7)
+            "bigMamo",    # Big-M value for AMO constraints (default: 5e7)
+            "epsilon",
             "gap",
             "maxIter",
             "maxRothConversion",
@@ -2064,7 +2152,7 @@ class Plan:
         if "gap" not in myoptions and myoptions.get("withMedicare", "loop") == "optimize":
             fac = 1
             maxRoth = myoptions.get("maxRothConversion", 100)
-            if maxRoth <= 15:
+            if maxRoth != "file" and maxRoth <= 15:
                 fac = 10
             # Loosen default MIP gap when Medicare is optimized. Even more if rothX == 0
             gap = fac * MILP_GAP
@@ -2160,6 +2248,14 @@ class Plan:
                 break
 
             if not withSCLoop:
+                # When Medicare is in loop mode, M_n was zero in the constraint for this
+                # single solve. Update M_n (and J_n) from solution for reporting.
+                if includeMedicare:
+                    self._computeNLstuff(xx, includeMedicare)
+                    self.mylog.print(
+                        "Warning: Self-consistent loop is off; Medicare premiums are "
+                        "computed for display but were not in the budget constraint."
+                    )
                 break
 
             self._computeNLstuff(xx, includeMedicare)
@@ -2182,7 +2278,9 @@ class Plan:
                 prev_scaled_obj = (-old_objfns[-1]) * objFac
             scale = max(1.0, abs(scaled_obj), abs(prev_scaled_obj))
             tol = max(abs_tol, rel_tol * scale)
-            if absObjDiff <= tol:
+            # With Medicare in loop mode, the first solve uses M_n=0; require at least
+            # one re-solve so the accepted solution had Medicare in the budget.
+            if absObjDiff <= tol and (not includeMedicare or it >= 1):
                 # Check if convergence was monotonic or oscillatory
                 # old_objfns stores -objfn values, so we need to scale them to match displayed values
                 # For monotonic convergence, the scaled objective (objfn * objFac) should be non-increasing
@@ -2522,6 +2620,7 @@ class Plan:
         Ce = self.C["e"]
         Cf = self.C["f"]
         Cg = self.C["g"]
+        Ch = self.C.get("h", self.C["m"])
         Cm = self.C["m"]
         Cs = self.C["s"]
         Cw = self.C["w"]
@@ -2545,7 +2644,11 @@ class Plan:
         self.f_tn = np.array(x[Cf:Cg])
         self.f_tn = self.f_tn.reshape((Nt, Nn))
 
-        self.g_n = np.array(x[Cg:Cm])
+        self.g_n = np.array(x[Cg:Ch])
+
+        if "h" in self.C:
+            self.h_qn = np.array(x[Ch:Cm])
+            self.h_qn = self.h_qn.reshape((self.N_n - self.nm, self.N_q))
 
         self.m_n = np.array(x[Cm:Cs])
 
@@ -2586,9 +2689,10 @@ class Plan:
         self.MAGI_n = (self.G_n + self.e_n + self.Q_n
                        + np.sum((1 - self.Psi_n) * self.zetaBar_in, axis=0))
 
+        # Only positive returns count as interest/dividend income (matches _add_taxable_income).
         I_in = ((self.b_ijn[:, 0, :-1] + self.d_in - self.w_ijn[:, 0, :])
-                * np.sum(self.alpha_ijkn[:, 0, 1:, :Nn] * self.tau_kn[1:, :], axis=1))
-        # Clamp interest/dividend income to non-negative. Sum over individuals to share losses across spouses.
+                * np.sum(self.alpha_ijkn[:, 0, 1:, :Nn] * np.maximum(0, self.tau_kn[1:, :]), axis=1))
+        # Sum over individuals to share losses across spouses; clamp to non-negative.
         self.I_n = np.maximum(0, np.sum(I_in, axis=0))
 
         # Stop after building minimum required for self-consistent loop.