chore: add VanguardDynamicSpending to wealth and cashflow calculations

Author: chilango74

main.py

@@ -16,26 +16,26 @@
 
 rs = ok.Rebalance(
     period="year",
-    abs_deviation=0.10,
-    rel_deviation=0.40
+    # abs_deviation=0.10,
+    # rel_deviation=0.40
 )
 weights = [0.12, 0.21, 0.42, 0.25]
 pf = ok.Portfolio(
     ['RGBITR.INDX', 'RUCBTRNS.INDX', 'MCFTR.INDX', 'GC.COMM'],
     weights=weights,
-    first_date='2014-06',
+    # first_date='2014-06',
     ccy="RUB",
     inflation=True,
     rebalancing_strategy=rs,
     symbol="My_portfolio.PF",
 )
 pf.dcf.discount_rate = 0.09
-# Percentage CF strategy
-cf_strategy = ok.PercentageStrategy(pf)  # create PercentageStrategy linked to the portfolio
-
-cf_strategy.initial_investment = 83_000_000  # initial investments size
-cf_strategy.frequency = "year"  # withdrawals frequency
-cf_strategy.percentage = -0.40
+# # Percentage CF strategy
+# cf_strategy = ok.PercentageStrategy(pf)  # create PercentageStrategy linked to the portfolio
+#
+# cf_strategy.initial_investment = 83_000_000  # initial investments size
+# cf_strategy.frequency = "year"  # withdrawals frequency
+# cf_strategy.percentage = -0.40
 
 # # Indexation CF strategy
 # cf_strategy = ok.IndexationStrategy(pf)
@@ -45,27 +45,56 @@
 # cf_strategy.amount = 1_500_000 * 12
 # cf_strategy.indexation = 0.09
 
-d = {
-    "2015-06": -35_000_000,
-}
-
-cf_strategy.time_series_dic = d
-cf_strategy.time_series_discounted_values = False
+# d = {
+#     "2015-06": -35_000_000,
+# }
+#
+# cf_strategy.time_series_dic = d
+# cf_strategy.time_series_discounted_values = False
+
+# Fixed Percentage strategy
+cf_strategy = ok.VanguardDynamicSpending(pf)
+cf_strategy.initial_investment = 10_000_000
+cf_strategy.frequency = "year"
+cf_strategy.percentage = -0.15
+cf_strategy.indexation = 0.09
+cf_strategy.maximum_annual_withdrawal = 10_000_000 / 5  # 20%
+cf_strategy.minimum_annual_withdrawal = 10_000_000 / 10  # 10%
+cf_strategy.ceiling = 0.10
+cf_strategy.floor = -0.10
 
 pf.dcf.cashflow_parameters = cf_strategy  # assign the cash flow strategy to portfolio
 
+# w = cf_strategy.calculate_withdrawal_size(
+#     last_withdrawal=0,
+#     balance=cf_strategy.initial_investment,
+#     number_of_periods=1
+# )
+
+# print(w)
 pf.dcf.set_mc_parameters(
     distribution="norm",
     period=15,
     number=100
 )
 
-# wi = pf.dcf.wealth_index(discounting="fv", include_negative_values=True)
-# cf = pf.dcf.cash_flow_ts(discounting="fv", remove_if_wealth_index_negative=False).resample("Y").sum()
-cf = pf.dcf.monte_carlo_cash_flow(discounting="fv", remove_if_wealth_index_negative=True)
-print(cf)
+# wi = pf.dcf.wealth_index(discounting="fv", include_negative_values=False)
+# cf = pf.dcf.cash_flow_ts(discounting="pv", remove_if_wealth_index_negative=True).resample("Y").sum()
+wi = pf.dcf.monte_carlo_wealth(discounting="fv", include_negative_values=False)
+# cf = pf.dcf.monte_carlo_cash_flow(discounting="fv", remove_if_wealth_index_negative=True)
+# print(cf)
+
+wi.plot(
+    # kind="bar",
+    legend=False
+)
+plt.yscale('log')  # linear or log
+plt.show()
 
-# cf[0].plot(kind="bar", legend=False)
+# cf.plot(
+#     kind="bar",
+#     legend=False
+# )
 # plt.yscale('linear')  # linear or log
 # plt.show()
 

main_notebook.ipynb

@@ -2,7 +2,7 @@
  "cells": [
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 1,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2025-07-29T11:26:06.735435Z",
@@ -36,7 +36,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 2,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2025-07-29T11:26:09.894658Z",
@@ -54,7 +54,7 @@
        "'1.5.0'"
       ]
      },
-     "execution_count": 3,
+     "execution_count": 2,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -77,7 +77,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 3,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2025-07-29T11:26:11.913869Z",
@@ -93,7 +93,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 4,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2025-07-29T11:26:55.347301Z",
@@ -109,7 +109,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "symbol                                                       portfolio_6434.PF\n",
+      "symbol                                                       portfolio_7799.PF\n",
       "assets                       [RGBITR.INDX, RUCBTRNS.INDX, MCFTR.INDX, GC.COMM]\n",
       "weights                                                 [0.1, 0.1, 0.55, 0.25]\n",
       "rebalancing_period                                                        year\n",
@@ -142,7 +142,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 222,
+   "execution_count": 5,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -1641,15 +1641,15 @@
     {
      "data": {
       "text/plain": [
-       "Portfolio symbol                portfolio_6434.PF\n",
-       "Cash flow initial investment             10000000\n",
-       "Cash flow frequency                          year\n",
-       "Cash flow strategy                            VDS\n",
-       "Cash flow percentage                     -0.07000\n",
-       "Minimum annual withdrawal           400,000.00000\n",
-       "Maximum annual withdrawal         1,000,000.00000\n",
-       "Ceiling                                   0.10000\n",
-       "Floor                                    -0.10000\n",
+       "Portfolio symbol                  Portfolio.PF\n",
+       "Cash flow initial investment          10000000\n",
+       "Cash flow frequency                       year\n",
+       "Cash flow strategy                         VDS\n",
+       "Cash flow percentage                  -0.07000\n",
+       "Minimum annual withdrawal        400,000.00000\n",
+       "Maximum annual withdrawal      1,000,000.00000\n",
+       "Ceiling                                0.10000\n",
+       "Floor                                 -0.10000\n",
        "dtype: object"
       ]
      },
@@ -1664,12 +1664,25 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 9,
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "-0.0"
+      ]
+     },
+     "execution_count": 9,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
    "source": [
     "vds.calculate_withdrawal_size(\n",
-    "    last_withdrawal=\n",
+    "    last_withdrawal=0,\n",
+    "    balance=1000,\n",
+    "    number_of_periods=1\n",
     ")"
    ]
   },

okama/portfolios/cashflow_strategies.py

@@ -90,6 +90,7 @@ def initial_investment(self, initial_investment):
     @property
     def time_series_dic(self) -> dict:
         """
+        # TODO: rename to extra_cashflow_ts
         Cash flow time series in form of dictionary.
 
         Negative number corresponds to withdrawals, positive number corresponds to contributions.
@@ -378,27 +379,43 @@ def __repr__(self):
         }
         return repr(pd.Series(dic))
 
-    def calculate_withdrawal_size(self, last_withdrawal: float, balance: float, number_of_months: int) -> float:
-        withdrawal_size_by_percentage = balance * self.percentage
-        ceiling = last_withdrawal * (1 + self.ceiling)
-        floor = last_withdrawal * (1 + self.floor)
-        min_indexed = self.minimum_annual_withdrawal * (1 + self.indexation) ** number_of_months
-        max_indexed = self.maximum_annual_withdrawal * (1 + self.indexation) ** number_of_months
+    def calculate_withdrawal_size(self, last_withdrawal: float, balance: float, number_of_periods: int) -> float:
+        """
+        Calculate regular withdrawal size (Extra Withdrawals are not taken into account).
+        """
+        # All values are postive
+        withdrawal_size_by_percentage = balance * abs(self.percentage)
+        ceiling = abs(last_withdrawal) * (1 + self.ceiling)
+        floor = abs(last_withdrawal) * (1 + self.floor)
+        min_indexed = abs(self.minimum_annual_withdrawal) * (1 + self.indexation) ** number_of_periods
+        max_indexed = abs(self.maximum_annual_withdrawal) * (1 + self.indexation) ** number_of_periods
+        # Chek what limitation is actual
+        # Upper limit
         if ceiling > max_indexed:
             max_final = max_indexed
-        else:
+        elif min_indexed < ceiling <= max_indexed:
             max_final = ceiling
-        if floor < min_indexed:
-            min_final = min_indexed
         else:
+            # ceiling = 0
+            max_final = max_indexed
+        # Lower limit
+        if floor > min_indexed:
             min_final = floor
-
+        elif 0 < floor <= min_indexed:
+            min_final = min_indexed
+        else:
+            # floor = 0
+            min_final = min_indexed
+        # Apply the limitation to the withdrawal
         if min_final <= withdrawal_size_by_percentage <= max_final:
-            withdrawal = withdrawal_size_by_percentage
+            withdrawal = - withdrawal_size_by_percentage
+            # print(f"withdrawal by percentage. Max: {max_final: .0f}, Min: {min_final: .0f}")
         elif withdrawal_size_by_percentage > max_final:
-            withdrawal = max_final
+            withdrawal = - max_final
+            # print(f"withdrawal by max_final. By percentage was {withdrawal_size_by_percentage: .0f}")
         elif withdrawal_size_by_percentage < min_final:
-            withdrawal = min_final
+            withdrawal = - min_final
+            # print(f"withdrawal by min_final. By percentage was {withdrawal_size_by_percentage: .0f}")
         else:
             raise ValueError('Wrong withdrawal size. Check the calculation.')
         return withdrawal

okama/portfolios/dcf_calculations.py

@@ -26,6 +26,7 @@ def get_wealth_indexes_fv_with_cashflow(
     dcf_object.cashflow_parameters = cashflow_parameters
     period_initial_amount = cashflow_parameters.initial_investment
     period_initial_amount_cached = period_initial_amount
+    last_regular_cash_flow = 0
     amount = getattr(cashflow_parameters, "amount", None)
     if isinstance(ror, pd.DataFrame):
         portfolio_position = ror.columns.get_loc(portfolio_symbol)
@@ -66,6 +67,12 @@ def get_wealth_indexes_fv_with_cashflow(
                 cashflow = cashflow_parameters.percentage / periods_per_year * period_initial_amount
             elif cashflow_parameters.NAME == "time_series":
                 cashflow = 0
+            elif cashflow_parameters.NAME == "VDS":
+                cashflow = cashflow_parameters.calculate_withdrawal_size(
+                    last_withdrawal=last_regular_cash_flow if n > 0 else 0,
+                    balance=period_initial_amount,
+                    number_of_periods=n,
+                )
             else:
                 raise ValueError("Wrong cashflow strategy name value.")
             period_initial_amount = period_initial_amount * (r + 1) + cashflow + cash_flow_ts[date]
@@ -94,6 +101,12 @@ def get_wealth_indexes_fv_with_cashflow(
                 cashflow_value = amount * (1 + cashflow_parameters.indexation / periods_per_year) ** n
             elif cashflow_parameters.NAME == "fixed_percentage":
                 cashflow_value = cashflow_parameters.percentage / periods_per_year * period_initial_amount
+            elif cashflow_parameters.NAME == "VDS":
+                cashflow_value = cashflow_parameters.calculate_withdrawal_size(
+                    last_withdrawal=last_regular_cash_flow if n > 0 else 0,
+                    balance=period_initial_amount,
+                    number_of_periods=n,
+                )
             else:
                 raise ValueError("Wrong cashflow_method value.")
             period_final_balance = period_wealth_index.iloc[-1] + cashflow_value
@@ -126,6 +139,7 @@ def get_cash_flow_fv(
     dcf_object = cashflow_parameters.parent.dcf
     dcf_object.cashflow_parameters = cashflow_parameters
     period_initial_amount = cashflow_parameters.initial_investment
+    last_regular_cash_flow = 0
     cs_fv = pd.Series(dtype=float, name="cash_flow_fv")
     amount = getattr(cashflow_parameters, "amount", None)
     if isinstance(ror, pd.DataFrame):
@@ -162,14 +176,23 @@ def get_cash_flow_fv(
         for n, row in enumerate(ror.itertuples()):
             date = row[0]
             r = row[portfolio_position + 1]
+            # Calculate regular cash flow
             if cashflow_parameters.NAME == "fixed_amount":
                 cashflow = amount * (1 + cashflow_parameters.indexation / settings._MONTHS_PER_YEAR) ** n
             elif cashflow_parameters.NAME == "fixed_percentage":
                 cashflow = cashflow_parameters.percentage / periods_per_year * period_initial_amount
             elif cashflow_parameters.NAME == "time_series":
                 cashflow = 0
+            elif cashflow_parameters.NAME == "VDS":
+                cashflow = cashflow_parameters.calculate_withdrawal_size(
+                    last_withdrawal=last_regular_cash_flow if n > 0 else 0,
+                    balance=period_initial_amount,
+                    number_of_periods=n,
+                )
             else:
                 raise ValueError("Wrong cashflow strategy name value.")
+            # add Extra Withdrawals/Contributions
+            last_regular_cash_flow = cashflow
             cs_value = cashflow + cash_flow_ts[date]
             period_initial_amount = period_initial_amount * (r + 1) + cs_value
             cs_fv[date] = cs_value
@@ -179,7 +202,7 @@ def get_cash_flow_fv(
         for n, x in enumerate(ror_cashflow_df.resample(rule=pandas_frequency, convention="start")):
             ror_ts = x[1].iloc[:, portfolio_position]  # select ror part of the grouped data
             cashflow_ts_local = x[1].loc[:, "cashflow_ts"].copy()
-            # CashFlow inside period
+            # CashFlow inside period (Extra cash flow)
             if (cashflow_ts_local != 0).any():
                 period_wealth_index = pd.Series(dtype=float, name=portfolio_symbol)
                 for k, (date, r) in enumerate(ror_ts.items()):
@@ -190,11 +213,17 @@ def get_cash_flow_fv(
                     period_wealth_index[date] = month_balance
             else:
                 period_wealth_index = period_initial_amount * (1 + ror_ts).cumprod()
-            # CashFlow END period
+            # CashFlow END period (Regular Cash Flow)
             if cashflow_parameters.NAME == "fixed_amount":
                 cashflow_value = amount * (1 + cashflow_parameters.indexation / periods_per_year) ** n
             elif cashflow_parameters.NAME == "fixed_percentage":
                 cashflow_value = cashflow_parameters.percentage / periods_per_year * period_initial_amount
+            elif cashflow_parameters.NAME == "VDS":
+                cashflow_value = cashflow_parameters.calculate_withdrawal_size(
+                    last_withdrawal=last_regular_cash_flow if n > 0 else 0,
+                    balance=period_initial_amount,
+                    number_of_periods=n,
+                )
             else:
                 raise ValueError("Wrong cashflow_method value.")
             period_final_balance = period_wealth_index.iloc[-1] + cashflow_value