Documentation/OSEM_Documentation_draft.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "d318d79d",
   "metadata": {},
   "source": [
    "# Open-Source Economic Model"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3a717345",
   "metadata": {},
   "source": [
    "Open-Source Economic Model (OSEM) is a modelling solution that allows financial companies to simulate their future financial performance. It is envisioned to be an alternative to classical internal models offten found in insurance companies, pension funds, banks etc. The open design is especially suitable for medium size companies that do not have the resources for an end-to-end internal development team, but have the volume of assets that could benefit from tailored insights and scenario analysis made posible by such models. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8acec05b",
   "metadata": {},
   "source": [
    "OSEM takes into consideration the company's current assets and liabilities. It also allows the user to define any future investments and liability business. Through a simplified representation of the economy, it simulates decision-making such as trading and balance sheet rebalancing that a company would make as time progresses.\n",
    "\n",
    "\n",
    "OSEM consists of different modules such as:\n",
    " - Data preparation\n",
    " - Investment universe definition\n",
    " - Asset preparation and calibration\n",
    " - Liability preparation and calibration\n",
    " - Asset Liability preparation\n",
    " - Asset Liability run\n",
    " - Reporting\n",
    " \n",
    "<b>Note that in the prototype stage not all modules are implemented. Reach out to one of the contributors to find out what parts can be used with a higher degree of confidence and which parts are still very much in development.</b>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "457d4aea",
   "metadata": {},
   "source": [
    "## Modelling parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e434bebc",
   "metadata": {},
   "source": [
    "OSEM can be configured to the varied needs of the user. The user can specify the model granularity, length of the modelling (in years), the type of run, the type of curve used as the risk-free rate, the country, and the specific modelling date. Bellow we describe in more details each specific setting."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "768d3ba5",
   "metadata": {},
   "source": [
    "#### Modelling granularity"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f1b0fd4",
   "metadata": {},
   "source": [
    "The modelling granularity is yearly in the initial POC prototype. In the future, this will be extended to monthly, yearly or every 5 years. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a2bdf41f",
   "metadata": {},
   "source": [
    "#### Length of the modelling horizon"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "14dc14cd",
   "metadata": {},
   "source": [
    "This parameter sets the length of the modelling horizon. In the POC prototype, the length is in years. For example, a value of 20 means a modelling horizon of 20 years from the modelling date."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f3e72b87",
   "metadata": {},
   "source": [
    "$$ END $$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "82e63a4d",
   "metadata": {},
   "source": [
    "#### Run type"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ab6d6848",
   "metadata": {},
   "source": [
    "This parameter differentiates different kinds of runs. The types of runs envisioned for OSL are:\n",
    "\n",
    " - Risk neutral\n",
    " - Market consistent\n",
    " - Real world\n",
    "\n",
    "The POC prototype supports only a risk neutral run, however further the roadmap envisions the development of other types of runs."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "576a42aa",
   "metadata": {},
   "source": [
    "### Selection of the risk-free curve"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "45328a19",
   "metadata": {},
   "source": [
    "This parameter determines the type of curve used as the risk-free rate. The POC prototype supports only the base curve and the base curve with the Volatility Adjustment published by EIOPA."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dff3ae4b",
   "metadata": {},
   "source": [
    "### Country"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2981def2",
   "metadata": {},
   "source": [
    "This parameter determines the home economy of the company. The POC prototype supports only one economy. In the future, multiple economies can be implemented.\n",
    "\n",
    "$$ country $$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "75b00e6a",
   "metadata": {},
   "source": [
    "### Modelling date"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f632cacc",
   "metadata": {},
   "source": [
    " The modelling date is the start or time 0 of the model. The market values, curves and other parameters are assumed to be calculated as-at this timestamp. The modelling date is denoted as $$MD \\dots $$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e0c1121b",
   "metadata": {},
   "source": [
    "## Data preparation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c6923885",
   "metadata": {},
   "source": [
    "The POC prototype only supports the EIOPA risk free curve. The setting file of the run are the base country and the type of the EIOPA curve that is to be used.\n",
    "\n",
    "The following files are imported \n",
    " - Parameters.csv; Parameters related to the run \n",
    " - EIOPA_param_file.csv; Assumed yield curve at modelling date and relevant maturities\n",
    " - EIOPA_curves_file.csv; Parameters related to the EIOPA time 0 calibration\n",
    "\n",
    "\n",
    "From the input files, the following information is retrieved:\n",
    " - Vector of maturities for the EIOPA yield curve\n",
    " - Vector of yields for the liquid EIOPA maturities\n",
    " - Last liquid point\n",
    " - Convergence parameter\n",
    " - Ultimate forward rate\n",
    " - Alpha parameter\n",
    " - CRA parameter\n",
    " - Tau parameter"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b10dd288",
   "metadata": {},
   "source": [
    "## Economic environment setup"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8813fba7",
   "metadata": {},
   "source": [
    "The economic environment in which the model will run is being simulated in the this step, the risk-free curve is imported and a Smith&Wilson algorithm is used to calculate a calibration vector. This vector provides a continuous term-structure function that is needed when dealing with real dates. \n",
    "\n",
    "At a high level, the steps are the following:\n",
    "- Import the complete yield curve at time 0 (At descrete points)\n",
    "- Calculate 1-year forward rates\n",
    "- Use forward rates to calculate projected yield curves (At descrete points)\n",
    "- Use a bisection algorithm to calibrate the parameter $\\alpha$ at each projection step\n",
    "- Save the calibration vector $b$ for each projection step\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7a891748",
   "metadata": {},
   "source": [
    "A vector of modelling steps is calculated and saved for future use:\n",
    "\n",
    "$$\n",
    "modellingsteps = \\{MD, MD_1, \\dots, MD_T\\}\n",
    "$$\n",
    "\n",
    "Where:\n",
    "\n",
    "$$\n",
    "MD_1 = MD + 1 year\n",
    "$$\n",
    "$$\n",
    "MD_2 = MD + 2 years\n",
    "$$\n",
    "$$\n",
    "\\dots\n",
    "$$\n",
    "$$\n",
    "MD_N = MD + T years\n",
    "$$\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "774ffb34",
   "metadata": {},
   "source": [
    "### Calculation of the 1 year forward rate\n",
    "\n",
    "As the modelling date moves forward in time, the yield curve must be recalculated at every step. To facilitate this, the 1 year forward curve is calculated.\n",
    "\n",
    "The forward rates are calculated as:\n",
    "\n",
    "$$\n",
    "fw(i) = \\frac{(1+y_i)^i}{(1+y_{i-1})^{i-1}}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a151317",
   "metadata": {},
   "source": [
    "Where:\n",
    "\n",
    " - $i$ is the year (Ex. 1,2,3, $\\dots$)\n",
    " - $y_i$ is the yield for the year $i$\n",
    " - $fw_{EIOPA,i}$ is the 1-year forward rate between years $i-1$ and $i$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fabfbde5",
   "metadata": {},
   "source": [
    "### Forward yield curve\n",
    "\n",
    "Each forward yield curve can be calculated by using the 1-year forward rates from the suitable moment onwards. The spot yield curve is calculated for each projection period. For the projection period $j$, the yield curve can be calculated as:\n",
    "\n",
    "$$\n",
    "y^j_{i-j} = \\prod_{k=j}^i\\big(1+fw_{EIOPA}(k)\\big)^{-(k-j)}\n",
    "$$\n",
    "\n",
    "Where:\n",
    " - $j$ is the modelling period at which the model is performing the calculations (The projection year starting at time $MD_i$)\n",
    " - $i-j$ is the time period within the modelling period\n",
    " - $y^j_{k}$ is the yield $k$ years after the modelling period $j$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "874d638b",
   "metadata": {},
   "source": [
    "#### Calibrate Smith-Wilson on each yield curve\n",
    "\n",
    "Each forward yield curve is used to calibrate the SW algorithm. This calibration can then be used to generate yield corves of arbitrary maturities. \n",
    "\n",
    "Both at time 0 and in following projection years, the same calibration algorithm is performed. The algorithm looks to minimize the difference between the xxx and the ultimate forward rate as recommanded by EIOPA:\n",
    "\n",
    "\n",
    "$$\n",
    "T = \\max(U+40,60)\n",
    "$$\n",
    "\n",
    "$$\n",
    "g(\\alpha) = |f(T) - \\omega| = \\frac{\\alpha}{|1-\\kappa e^{\\alpha T}|}\n",
    "$$\n",
    "\n",
    "The calibration consists of using a bisection algorithm to minimize the difference between the ultimate forward rate $\\omega$.\n",
    "\n",
    "The calibration is:\n",
    "\n",
    "$$\n",
    "\\min \\alpha \n",
    "$$\n",
    "\n",
    "subject to constraints:\n",
    "\n",
    "$$\n",
    "\\alpha \\geq \\alpha_{min}\n",
    "$$\n",
    "and\n",
    "\n",
    "$$\n",
    "g(\\alpha) \\leq \\tau\n",
    "$$\n",
    "\n",
    " And $\\kappa$ is defined as:\n",
    "\n",
    " $$\n",
    "\\kappa = \\frac{1 + \\alpha u^T Qb}{sinh(\\alpha u^T)Qb}\n",
    " $$ \n",
    "\n",
    " $$\n",
    "Q = d I C\n",
    " $$\n",
    "\n",
    "$$\n",
    "d = e^{-\\omega u}\n",
    "$$\n",
    "\n",
    "\n",
    "Where:\n",
    " - $\\alpha$ is the free parameter to be calibrated\n",
    " - $\\alpha_{min}$ is the lower bound of the alowable values\n",
    " - $U$ is the last liquid point\n",
    " - $g(\\alpha)$ is the extrapolated\n",
    " - $C$ is a matrix of cash flows\n",
    "\n",
    "The output of this calibration is a vector of calibrated alphas \n",
    "$$alpha = \\{ \\alpha_0, \\alpha_1, \\dots, \\alpha_N  \\}$$\n",
    "\n",
    "and the calibration vectors\n",
    "$$b = \\{ b_0, b_1, \\dots, b_N  \\}$$\n",
    "\n",
    "\n",
    "Note that to use a consistent calibration throughout the OSEM model, the parameter alpha is calibrated again using the bisection method even for the yield curve at \"time 0\" even though the already calibrated alpha is available in the EIOPA input files.\n",
    "\n",
    "Note that other SW parameters such as the ultimate forward rate and precision are assumed to remain the same for each calibration.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1cc1c605",
   "metadata": {},
   "source": [
    "#### Saving the projected curves\n",
    "\n",
    "The advantage of the calibration and projection using the Smith&Wilson algorithm is three-fold:\n",
    "\n",
    "1) The S&W algorithm provides a continuous function therefore a yield for any date can be calculated\n",
    "\n",
    "2) To initialize the continuous term-structure, only a handful of parameters is needed.\n",
    "\n",
    "3) It is a well understood algorithm frequently used in practice.\n",
    "\n",
    "Note that the parameters needed for obtaining a vector of yields for any maturity are only:\n",
    " - The parameter $\\alpha$\n",
    " - The vector $b$\n",
    " - List of maturities used to calibrate the vector $b$ and $\\alpha$\n",
    " - Other stationary SW parameters such as ufr, $\\tau$ etc.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fc457c62",
   "metadata": {},
   "source": [
    "## Asset input and calibration"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1d92d950",
   "metadata": {},
   "source": [
    "### Government bond input and calibration"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "69747fd4",
   "metadata": {},
   "source": [
    "ToDo"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6ad6f41f",
   "metadata": {},
   "source": [
    "### Corporate bond input and calibration"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c856086",
   "metadata": {},
   "source": [
    "One of the types of assets that OSEM supports is corporate debt in the form of corporate bonds. Bonds, described in the input files, are calibrated to each specific run:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2e655912",
   "metadata": {},
   "source": [
    " - $MD \\dots $ modelling date\n",
    " - $I \\dots $ issue date\n",
    " - $M \\dots $ maturity date\n",
    " - $N \\dots $ notional amount\n",
    " - $c \\dots $ coupon yield\n",
    " - $MV \\dots $ market value at modelling date\n",
    " - $BV \\dots $ book value at modelling date\n",
    "  "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7c6814b9",
   "metadata": {},
   "source": [
    "### 1) Dates\n",
    "\n",
    "The basic building block is a cash flow. The first step in the bond input process is to calculate dates at which the bond is expected to produce a cash flow.\n",
    "\n",
    "The dates for all assets are separated into two sets:\n",
    " 1) Cash flow(s) when the principal amount is returned\n",
    " 2) Cash flows from coupon payments\n",
    "\n",
    "We will denote the dates associated with the returned principal (Only one in the POC) from a hypothetical bond as:\n",
    "\n",
    "$$ t_M^d = M $$\n",
    "\n",
    "The dates associated with coupon payments will be denoted as:\n",
    "\n",
    "$$  I< t^d_1 < t^d_2 < \\dots < t^d_l \\leq M $$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "94d4a8c4",
   "metadata": {},
   "source": [
    "### 2) Date fractions with respect to the modelling date\n",
    "\n",
    "The first step in refactoring for fixed income assets such as corporate bonds consist of calculating the cash flow dates that occur after the modelling date since the past cash flows are not relevant to the OSEM model. For each cash flow date, a time fraction is calculated with regards to the modelling date in years (A fraction of 1 equals exactly 1 year from the modelling date). This facilitates discounting in later stages.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3223556b",
   "metadata": {},
   "source": [
    "The calculation of the date fractions is as follows."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "42f19044",
   "metadata": {},
   "source": [
    "First the final repayment of the notional amount is calculated.\n",
    "The date is refactored if the asset has not matured before the modelling date.\n",
    "\n",
    "$$ t_{M} = \\frac{t_{M} - MD} {365.25}   $$\n",
    "\n",
    "The date fraction is saved and can be viewed in the following object property:\n",
    "\n",
    "$$ datesnotional =  \\{ t_{M}\\}$$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "28308462",
   "metadata": {},
   "source": [
    "In the next step, the dates associated with the coupon payments are refactored:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16e3f966",
   "metadata": {},
   "source": [
    "$$ t_1 = \\frac{t_j - MD}{365.25}$$\n",
    "\n",
    "$$ t_2 = \\frac{t_{j+1} - MD}{365.25} $$\n",
    "\n",
    "$$\\dots$$\n",
    "\n",
    "$$t_k = \\frac{t_{j+k} - MD}{365.25} $$\n",
    "\n",
    "\n",
    "Where:\n",
    " $$ j = \\min_i(t_i^d \\geq MD) $$ "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4b7afdfc",
   "metadata": {},
   "source": [
    "The date fractions are saved and can be viewed in the following object property:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a1ac8f9",
   "metadata": {},
   "source": [
    "$$ datescf =  \\{ t_1, t_2, \\dots t_{j+k} \\} $$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a5cc93bd",
   "metadata": {},
   "source": [
    "### 3) Cashflow simulation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "726920af",
   "metadata": {},
   "source": [
    "This section simulates the size of the cash flows in the local currency. For bonds there are two types of cash flows. The coupons and the notional payout."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b9281a39",
   "metadata": {},
   "source": [
    "##### Notional cash flow\n",
    "\n",
    "The notional amount returned at the maturity of the bond is saved in the object property:\n",
    "\n",
    "$$ cf_M = N$$\n",
    "\n",
    "And is saved as:\n",
    "\n",
    "$ notcf = \\{ cf_M \\} $"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "52749dbc",
   "metadata": {},
   "source": [
    "##### Coupon cash flow\n",
    "\n",
    "$ divcf = \\{ cf_1, \\dots, cf_k \\} $\n",
    "\n",
    "Where:\n",
    "\n",
    "$ cf_i = N*c  $"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "48f01646",
   "metadata": {},
   "source": [
    "### 4) Calibration"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8d0eee35",
   "metadata": {},
   "source": [
    "The calibration is the process of finding the correct discount rate for each bond. The correct discount rate at which the discounted price of the bond is equal to the market value of the bond observed at the modelling date.\n",
    "\n",
    "Note that if the run is set to Risk Neutral, the sector specific spread is equal to 0 for all bonds.\n",
    "\n",
    "The discount rate is calibrated using a constant factor called z-spread that increases-decreases the risk free discount rate such that:\n",
    "\n",
    "$$\n",
    "MV = \\frac{cf_1}{(1+ y(t_1)+ s + z)^{t_1}} + \\dots+\\frac{cf_k}{(1+ y(t_k)+ s + z)^{t_k}} +\\frac{cf_M}{(1+ y(t_k)+ s + z)^{t_k}} \n",
    "$$\n",
    "\n",
    "Where\n",
    " - $N \\dots $ is the notional value of the bond\n",
    " - $ cf_i\\dots $ is the i-th coupon\n",
    " - $ cf_M \\dots $ is the final cash flow associated with the return of the principal\n",
    " - $ y(t_i) \\dots $ is the annual yield for a period between the modelling date and time $t_i$\n",
    " - $ s \\dots  $ is the sector specific spread\n",
    " - $ z \\dots $ is the z-Spread of the individual bond  "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ea88c6bc",
   "metadata": {},
   "source": [
    " ## Equity input and calibration"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fe0d4a97",
   "metadata": {},
   "source": [
    "OSEM supports the asset class of equities. Different kinds of shares in the company. The shares are modelled as instruments that offer a constant cash flow in the form of a dividend based on the market value at the time of payment and a constant growth as the company matures. At the end of the modelling period, a terminal value is calculated. The terminal value represents the discounted value of all future cash flows outside of the modelling period."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6c3315f4",
   "metadata": {},
   "source": [
    "Each equity asset has the following fields:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f0194666",
   "metadata": {},
   "source": [
    " - $MD \\dots $ is the modelling date \n",
    " - $I \\dots $ issue date\n",
    " - $END \\dots $ end of the modelling period\n",
    " - $c \\dots $ dividend yield\n",
    " - $MV \\dots $ market value at modelling date\n",
    " - $BV \\dots $ book value at modelling date\n",
    " - $r \\dots $ is the terminal annualized interest rate"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6da26663",
   "metadata": {},
   "source": [
    "### 1) Dates"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "489f75da",
   "metadata": {},
   "source": [
    "The first step is to calculate the dates at which the equity asset generates a cash flow since its issue. This can be either a dividend or a terminal value sale."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3732bd0e",
   "metadata": {},
   "source": [
    "#### Terminal value date\n",
    "\n",
    "$$ t_{M} = END $$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d4d1a27",
   "metadata": {},
   "source": [
    "#### Dividend cash flow dates"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5f1369f1",
   "metadata": {},
   "source": [
    "$$  I < t_1^d < \\dots < t_l^d \\leq END $$\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "28703bcd",
   "metadata": {},
   "source": [
    "### 2)  Date fractions with respect to the modelling date"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "df3fce99",
   "metadata": {},
   "source": [
    "Like refactoring for fixed income assets, this step consists of calculating the dates at whihc cash flows occur after the modelling date since the past cash flows are not considered in the model. For each cash flow date, a time fraction is calculated with regards to the modelling date in years. This facilitates discounting in later stages."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ce4d0006",
   "metadata": {},
   "source": [
    "Terminal date is equal to the last day of the modelling window is calculated if the equity is issued after the modelling date but not after the last day of the modelling window.\n",
    "\n",
    "$$ t_{M} = \\frac{t_{M} - MD} {365.25} $$\n",
    "\n",
    "The date fraction is saved and can be viewed in the following object property:\n",
    "\n",
    "$$ datesterminal =  \\{ t_{M}\\}$$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3c95175e",
   "metadata": {},
   "source": [
    "The calculation of the date fraction for dividend payments is:\n",
    "\n",
    "$$ t_1 =\\frac{t^d_j - MD}{365.25} $$ \n",
    "\n",
    "$$ t_2 = \\frac{t^d_{j+1} - MD}{365.25} $$\n",
    "\n",
    "$$\\dots$$\n",
    "\n",
    "$$t_k = \\frac{t^d_{j+k} - MD}{365.25} $$\n",
    "\n",
    "Where:\n",
    "\n",
    "$$ j = \\min_i(t^d_i \\geq MD) $$\n",
    "\n",
    "Note that as OSLM starts supporting more daycount conventions, the date fraction calculation will be enhanced.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f8851914",
   "metadata": {},
   "source": [
    "The date fractions are saved and can be viewed in the following object property:\n",
    "\n",
    "$$ datescf =  \\{ t_1, t_2, \\dots t_{k} \\}$$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c8d7ca4e",
   "metadata": {},
   "source": [
    "### 3) Calibration"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d82cd078",
   "metadata": {},
   "source": [
    "The calibration of an equity asset uses a Gordon growth model to calculate the implied future growth rate, would imply the observed market value at the modelling date. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9e04f7ac",
   "metadata": {},
   "source": [
    "The calibration consists of finding a growth rate g such that:\n",
    "\n",
    "$$\n",
    "MV = \\frac{MV*(1+g)^{t_1}*c }{(1+y(t_1))^{t_1}}+\\frac{MV*(1+g)^{t_2} *c}{(1+y(t_2))^{t_2}}+\\dots + \\frac{MV*(1+g)^{t_k} *c}{(1+y(t_k))^{t_k}} + \\frac{1}{(1+y(t_M))^{t_M}} \\frac{MV*(1+g)^{t_M}*c}{r-g}\n",
    "$$\n",
    "\n",
    "$$\n",
    "1 = \\frac{(1+g)^{t_1} *c}{(1+y(t_1))^{t_1}}+\\frac{(1+g)^{t_2} *c}{(1+y(t_2))^{t_2}}+\\dots + \\frac{(1+g)^{t_k} *c}{(1+y(t_k))^{t_k}} + \\frac{(1+g)^{t_M}}{(1+y(t_M))^{t_M}} \\frac{c}{r-g}\n",
    "$$\n",
    "\n",
    "$$\n",
    "\\frac{1}{c} = \\frac{(1+g)^{t_1}}{(1+y(t_1))^{t_1}}+\\frac{(1+g)^{t_2}}{(1+y(t_2))^{t_2}}+\\dots + \\frac{(1+g)^{t_k}}{(1+y(t_k))^{t_k}} + \\frac{1}{(1+y(t_M))^{t_M}} \\frac{(1+g)^{t_M}}{r-g}\n",
    "$$\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8734781e",
   "metadata": {},
   "source": [
    "### 4) Cashflows"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bf23d02b",
   "metadata": {},
   "source": [
    "After obtaining the growth rate, the growth of the value of the share and by consequence the size of each dividend can be projected (As well as the terminal value). The calculation of the market value is done using the date fractions calculated in step 1, the calculated yields for each period and the growth rate. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a84702a5",
   "metadata": {},
   "source": [
    "The terminal value of the equity is calculated as\n",
    "\n",
    "$cf_M = \\frac{MV (1+g)^{t_M}}{r-g}$\n",
    "\n",
    "And saved as\n",
    "\n",
    "$ notcf = \\{ cf_M \\} $"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dfe6a429",
   "metadata": {},
   "source": [
    "For each period where a dividend is supposed to be paid, the market value is calculated as:\n",
    "\n",
    "$MV_{t_i} = MV (1+g)^{t_i}$\n",
    "\n",
    "Based on the market value at that period, the cash flow related to the dividend is calculated as:\n",
    "\n",
    "$cf_i = MV_{t_i}* c$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "47ddd63b",
   "metadata": {},
   "source": [
    "\n",
    "$  divcf =  \\{ cf_1, \\dots, cf_k \\} $"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ccdae229",
   "metadata": {},
   "source": [
    "## Property input and calibration"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b7f7da42",
   "metadata": {},
   "source": [
    "OSEM supports the asset class of properties. They represent properties wholly or partly owned by the company. The property's value is assumed to grow with a fixed growth rate. The property also gives the owner a dividend in the form of rent payments. Property shares are modelled as instruments that offer a constant cash flow in the form of a dividend (rent income) based on the property value at the time of payment. The property also has intrinsic value that increases over time at a constant growth. At the end of the modelling period, a selling value is calculated. The selling value represents the hypothetical sale of the property at the end of the modelling period."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36d6e580",
   "metadata": {},
   "source": [
    "For the POC, property asset class is modelled according to the same methodology as Equity."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee6dc59d",
   "metadata": {},
   "source": [
    "## Cash input"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2d0055ef",
   "metadata": {},
   "source": [
    "Cash is an asset class that is supported by the OSEM model. It also serves as a liquidity management field, serving as an intermediate between different trading steps in the projection module. Only a single entry for cash is kept within the model."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "efab4191",
   "metadata": {},
   "source": [
    "$$  cash_{MD} = CASH $$\n",
    "\n",
    "Where:\n",
    "\n",
    " - $CASH$ is the input cash value loaded from the input files"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0e074fa9",
   "metadata": {},
   "source": [
    "## Saving of asset positions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7fff124c",
   "metadata": {},
   "source": [
    "After the existing portfolio was processed, the intermediate results are saved in the Intermediate folder. This is done to allow the model to be more modular.\n",
    "The preparation steps consists of creating a master table with every date that contins a cashflow and the rows contain every single asset. Part of the table contains descriptive columns such as the asset type, market value, NACE code, ID etc."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd75dffb",
   "metadata": {},
   "source": [
    "# Generation of future investment assets"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3d91c977",
   "metadata": {},
   "source": [
    "Companies are expected to generate excess cash from operation, capital return or investment in the future. That cash is normally invested into the investments available at that time. Most of the assets that will be in the investment universe at that time do not exist yet at the Modelling Date and are therefore not present in the portfolio.\n",
    "\n",
    "To keep the model realistic, OSEM needs a way to create future assets."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be2753a4",
   "metadata": {},
   "source": [
    "This section describes the methodology to generate the following asset classes:\n",
    "\n",
    " - Government bonds\n",
    " - Corporate bonds\n",
    " - Equity shares\n",
    " - Property shares"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e0748640",
   "metadata": {},
   "source": [
    "### Generation of future government bonds"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c4a0362",
   "metadata": {},
   "source": [
    "1) DATES\n",
    "1.1) Terminal dates\n",
    "$$ t_M^d = MD + MAT $$\n",
    "\n",
    "1.2) Coupon dates\n",
    "$$ MD< t_1^d < \\dots <t^d_k \\leq MD + MAT $$\n",
    "\n",
    "2) DATEFRAC w.r.t modelling date\n",
    "\n",
    "SAME AS NORMAL BOND\n",
    "\n",
    "3) CALIBRATION\n",
    "\n",
    "min c s.t.\n",
    "\n",
    "$$ 1 = \\frac{c}{(1+y(t_1))^{t_1}}+\\dots+\\frac{c}{(1+y(t_k))^{t_k}} + \\frac{1}{(1+y(t_M))^{t_M}} $$\n",
    "\n",
    "4) CASHFLOWS\n",
    "\n",
    "SAME AS NORMAL BOND"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c463de41",
   "metadata": {},
   "source": [
    "### Generation of future corporate bonds"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0fe7ee93",
   "metadata": {},
   "source": [
    "Corporate bonds are generated at every period for a set of key maturities obtained from the input file Maturity_Generated. To avoid the explosion of new assets, the model only generates new bonds from sectors obtained from the input file. The sector is defined by its NACE code from the file NACE_Generated located in the Input folder. The POC prototype only supports a risk neutral run therefore every sector would have the same profile. Therefore, sector list is ignored. The input files also contain frequency $f$."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "95ef7981",
   "metadata": {},
   "source": [
    "In each modelling period $MD_i $, the key maturity of $j$ years and a sector $k$, the following bond is generated:\n",
    "\n",
    "Frequency of coupon dates is \n",
    "$$ f$$\n",
    "Maturity date is:\n",
    "\n",
    "$$  M = MD_i+j $$\n",
    "\n",
    "Issue date is:\n",
    "$$  I = MD_i $$\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "520a9557",
   "metadata": {},
   "source": [
    "1) DATES\n",
    "1.1) Terminal dates\n",
    "$$ t_M^d = MD + MAT $$\n",
    "\n",
    "1.2) Coupon dates\n",
    "$$ MD< t_1^d < \\dots <t^d_k \\leq MD + MAT $$\n",
    "\n",
    "2) DATEFRAC w.r.t modelling date\n",
    "\n",
    "SAME AS NORMAL BOND\n",
    "\n",
    "3) CALIBRATION\n",
    "\n",
    "min c s.t.\n",
    "\n",
    "$$ 1 = \\frac{c}{(1+y(t_1))^{t_1}}+\\dots+\\frac{c}{(1+y(t_k))^{t_k}} + \\frac{1}{(1+y(t_M))^{t_M}} $$\n",
    "\n",
    "4) CASHFLOWS\n",
    "\n",
    "SAME AS NORMAL BOND"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b8e599a6",
   "metadata": {},
   "source": [
    "#### Calibration of future corporate bonds"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a04e392",
   "metadata": {},
   "source": [
    "For simplicity, the dividend yield of newly created bonds is calibrated so that when priced using the risk free curve, the market value is equal to the notional amount. For a risk neutral run, each sector would have the same properties."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "60c95d09",
   "metadata": {},
   "source": [
    "### 1) Dates\n",
    "\n",
    "The first step in the new bond generation process is to calculate dates at which the bond is expected to produce a cash flow.\n",
    "\n",
    "We will denote these dates as:\n",
    "\n",
    "$$  I< t^d_1 < \\dots < t^d_n \\leq M $$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aead91df",
   "metadata": {},
   "source": [
    "### 2) Refactoring\n",
    "\n",
    "Refactoring for fixed income assets consists of calculating the cash flow dates with relation to the modelling date. For each cash flow date, a time fraction is calculated with regards to the modelling date in years."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6657430b",
   "metadata": {},
   "source": [
    "$$ t_1 = \\frac{t_1^d - MD_i}{365.25}$$\n",
    "\n",
    "$$ t_2 = \\frac{t_2^d - MD_i}{365.25} $$\n",
    "\n",
    "$$\\dots$$\n",
    "\n",
    "$$t_n = \\frac{t_{j+k}^d - MD_i}{365.25} $$\n",
    "\n",
    "Note that the bond was generated such that all coupon cash flows are after the modelling step."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d867d0c",
   "metadata": {},
   "source": [
    "The date fractions are saved and can be viewed in the following object property:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e9d18ed7",
   "metadata": {},
   "source": [
    "$$ datescf =  \\{ t_1, t_2, \\dots, t_{j+k} \\} $$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d6686f8d",
   "metadata": {},
   "source": [
    "Terminal date is also refactored if the asset has not matured before the modelling date.\n",
    "\n",
    "$$ t_{M} = \\frac{t_{M}^d - MD} {365.25}   $$\n",
    "\n",
    "The date fraction is saved and can be viewed in the following object property:\n",
    "\n",
    "$$ datesnotional =  \\{ t_{M}\\}$$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "505737df",
   "metadata": {},
   "source": [
    "#### Calibration of the yield\n",
    "\n",
    "This step uses a bisection algorithm to calculate the dividend yield such that the bond prices at par."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "adae40d1",
   "metadata": {},
   "source": [
    "$$\n",
    "MV = \\frac{N*c}{(1+ y(t_1))^{t_1}} + \\dots+\\frac{N*c}{(1+ y(t_k))^{t_k}} +\\frac{N}{(1+ y_k)^{t_k^f}} \n",
    "$$\n",
    "\n",
    "The objective of this optimisation is to calculate a dividend yield such that the notional amount is equal to the market value therefore $MV = N$\n",
    "\n",
    "$$\n",
    "N = \\frac{N*c}{(1+ y(t_1))^{t_1}} + \\dots+\\frac{N*c}{(1+ y(t_k))^{t_k}} +\\frac{N}{(1+ y(t_k))^{t_k}} \n",
    "$$\n",
    "\n",
    "$$\n",
    "1 = \\frac{c}{(1+ y(t_1))^{t_1}} + \\dots+\\frac{c}{(1+ y(t_k))^{t_k}} +\\frac{1}{(1+ y(t_M))^{t_M}} \n",
    "$$\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d67b96a8",
   "metadata": {},
   "source": [
    "#### Calculation of cash flows\n",
    "\n",
    "The notional amount returned at the maturity of the bond is saved in the object property:\n",
    "\n",
    "$$  cf_M = N $$\n",
    "$$ notcf = \\{ cf_M \\} $$\n",
    "\n",
    "Once the dividend yield $c$ is calculated, the cash flows can be calculated.\n",
    "\n",
    "$$ divcf = \\{ cf_1, \\dots, cf_k \\} $$\n",
    "\n",
    "Where:\n",
    "\n",
    "$$ cf_i = N*c  $$\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "251bc825",
   "metadata": {},
   "source": [
    "### Generation of future equity shares"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "35d81c4f",
   "metadata": {},
   "source": [
    "The equity asset class does not mature like fixed income instruments. In the first modelling period, a single equity is generated for each sector and calibrated. The company then trades in and out of these equities as modelling time progresses. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4dc1a532",
   "metadata": {},
   "source": [
    "Note that if needed, additional equity assets can be generated. For example, if different dividend frequencies are needed."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a516c5e",
   "metadata": {},
   "source": [
    "When generating a new set of equity shares, the following data is read from the input files:\n",
    "\n",
    " - Modelling date MD\n",
    " - List of NACE sectors which can be considered representative enough of the future investment universe\n",
    " - Frequency of dividend payments for each instrument $f$\n",
    " - Length of the modelling period\n",
    " - The dividend yield of each equity share"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ebabee4a",
   "metadata": {},
   "source": [
    "The equity share is initialized using the year of the modelling date MD and the day/month set such to align with the desired payout behaviour. The end of the modelling period is set by adding the modelling date MD the length of the modelling period.\n",
    "\n",
    " 1) In an analogy to the treatment of existing equity shares, the dividend cash-flows and the terminal value date are calculated.\n",
    " 2) All cashflow dates are refactored with comparison to the modelling date\n",
    " 3) The market value is set equal to 1.\n",
    " 4) The book value is set to be equal to 1.\n",
    " 5) In the POC prototype, the growth rate is calibrated in a way that makes the discounted cashflows of its dividend payments and the terminal value equal to the market value of 1.\n",
    " 6) Using the calculated growth rate, the cash-flows are simulated using the same formulas as the existing equity shares."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a8fac614",
   "metadata": {},
   "source": [
    "\n",
    "1) DATES\n",
    "1.1) Terminal date\n",
    "$$ t_M^d = END  $$\n",
    "\n",
    "1.2) Dividend dates\n",
    "$$ MD< t_1^d < \\dots <t^d_k \\leq END $$\n",
    "\n",
    "2) DATEFRAC w.r.t modelling date\n",
    "\n",
    "SAME AS NORMAL EQUITY\n",
    "\n",
    "3) CALIBRATION\n",
    "\n",
    "min g s.t.\n",
    "\n",
    "$$ \\frac{1}{c} = \\frac{(1+g)^{t1}}{(1+y(t_1))^{t_1}}+\\dots+\\frac{(1+g)^{tk}}{(1+y(t_k))^{t_k}} + \\frac{1}{(1+y(t_M))^{t_M}} \\frac{(1+g)^{tM}}{r-g} $$\n",
    "\n",
    "4) CASHFLOWS\n",
    "\n",
    "SAME AS NORMAL EQUITY"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9113dbcd",
   "metadata": {},
   "source": [
    "### Generation of future property bonds"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c7c99ee2",
   "metadata": {},
   "source": [
    "Future property shares are generated, calibrated, and saved in the same way as equity shares.\n",
    "\n",
    "ToDo"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "121d05b5",
   "metadata": {},
   "source": [
    "### Saving of future asset positions\n",
    "\n",
    "The future assets are saved in a master matrix similar to existing assets. Fixed income assets have to be generated each turn so they are kept in a separate master matrix compared to the other asset classes."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f9404038",
   "metadata": {},
   "source": [
    "## Liability preparation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d64b33f0",
   "metadata": {},
   "source": [
    "The liability section simulates different products and commitments that a company might have in their portfolio presently and in the future. There are two settings to treat the passive side of the company's balance sheet. \n",
    "\n",
    " 1) The company can upload a cash flow profile that determines the projected outflows at each modelling period\n",
    " 2) The company can do a full simulation of different kinds of products"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b7af3cb9",
   "metadata": {},
   "source": [
    "The POC prototype will only support the option 2 and a liability cash flow profile will be uploaded. The cash flow profile consists of a vector of expenses at the end of each modelling period. This negative cash position will be considered at every step of trading."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92dfc3ab",
   "metadata": {},
   "source": [
    "### Term life"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d16c095",
   "metadata": {},
   "source": [
    "ToDo"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "344988ca",
   "metadata": {},
   "source": [
    "### Health"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c447a68c",
   "metadata": {},
   "source": [
    "ToDo"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9cb247e3",
   "metadata": {},
   "source": [
    "### P&C"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a4e768b3",
   "metadata": {},
   "source": [
    "ToDo"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1a6bc029",
   "metadata": {},
   "source": [
    "### Saving of liablity positions\n",
    "\n",
    "A master matrix is created containing the outflows and descriptive fields for every type of liability with a similar structure to the assets."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "05cec5da",
   "metadata": {},
   "source": [
    "### Upload of externaly calculated liabilities\n",
    "\n",
    "A simplified approach of liability modelling, supported by OSEM is to provide a vector of outflows for each modelling period. Each outflow is denominated in the modelling currency. In this mode, there is only one cash flow per a modelling period. This assumes that all outflows are settled in a single day right before one modelling period is about to end and a new one is about to start.\n",
    "\n",
    "For example, if the previous modelling period is 31/12/2012 and the new one is at 31/12/2023, then the assumption is that all outflows have to be paid at 31/12/2022. The liability cash flows will be denoted as:\n",
    "$$\n",
    "cf^{liab} = \\{ cf_1, cf_2, \\dots, cf_N \\}\n",
    "$$\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8dcf639c",
   "metadata": {},
   "source": [
    "## Generation of future liabilities\n",
    "\n",
    "ToDo"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f46b00a7",
   "metadata": {},
   "source": [
    "# Projection"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "de8fce36",
   "metadata": {},
   "source": [
    "The projection module simulates the inner workings of a company at the end of a fiscal year given its mandate and financial conditions. The steps consist of:\n",
    "\n",
    " 1) Calculate the cash accumulated between the current modelling period and the next one\n",
    " \n",
    " 2) Refactor the cashflows and dates from the assets to start from the new modelling period\n",
    " \n",
    " 3) Price the assets to account for the new market conditions\n",
    " \n",
    " 4) Refactor the cashflows and dates from the liabilities to start from the new modelling period\n",
    "\n",
    " 5) Declare reserves in the new modelling period\n",
    " \n",
    " 6) Calculate the return of the portfolio between the two modelling periods\n",
    "\n",
    " 7) Calculate the net position of the company\n",
    "\n",
    " 8) Generate new assets\n",
    " \n",
    " 9) Sell to cover the balance or buy new instruments\n",
    " \n",
    " 10) Calculate the income statement, solvency ratio and other views of interest\n",
    "\n",
    " 11) Close the period and save results"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7634e141",
   "metadata": {},
   "source": [
    "## 0) Preparation for the movement into the next modelling period at time 0"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ce9b7b80",
   "metadata": {},
   "source": [
    "After the preparation of the model, assets and liabilities generated and curves projected, the objects are read into memory for the first time. The market value of the entire portfolio is calculated."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "abeae671",
   "metadata": {},
   "source": [
    "##  1) Calculate the cash accumulated between the current modelling period and the next one"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e0b8c084",
   "metadata": {},
   "source": [
    "The asset and liability position at the end of the previous period is read into memory. The cash position ath the end of the previous period is read into memory.\n",
    "\n",
    "Calculate the cash flow generated between the end of the previous modelling period and the end of the new modelling period by summing the cash flow matrix that falls between the modelling dates.\n",
    "\n",
    "$$\n",
    "CASH_{i+1}^0 = CASH_{i+1}^X + \\sum_j \\sum_k \\sum_t cf^A_{ijk} I_{t_{ijk}< (M_{i+1}-M_i)}\n",
    "$$\n",
    "\n",
    "$$\n",
    "- \\sum_j \\sum_k \\sum_t cf^L_{ijk} I_{t_{ijk}< (M_{i+1}-M_i)}\n",
    "$$\n",
    "\n",
    "Calculate the incease in the value of the portfolio by applying the growth rates and the correct time fraction."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "999b4fc1",
   "metadata": {},
   "source": [
    "##  2) Refactor the cashflows and dates from the assets to start from the new modelling period\n",
    " \n",
    " The date fraction is moved by the length of the step forward in the modelling period for both final cash flows and coupon/dividend cash flows. Assets that mature are removed from the list.\n",
    "\n",
    "Final cash flow date fractions:\n",
    " $$ DF_{i+1}^{0,A,N} = DF_{i}^{1,A,N} - (M_{i+1}-M_i)  $$\n",
    "\n",
    " $$ DF_{i+1}^{1,A,N} = DF_{i+1}^{0,A,N} I_{t_{ijk}\\leq 0} $$\n",
    " \n",
    " Where the indicator function removes the row of the expired asset in the matrix.\n",
    "\n",
    "Coupon date fractions:\n",
    "\n",
    " $$ DF_{i+1}^{0,A,C} = DF_{i}^{1,A,C} - (M_{i+1}-M_i)  $$\n",
    "\n",
    " $$ DF_{i+1}^{1,A,C} = DF_{i+1}^{0,A,C} I_{t_{ijk}\\leq 0} $$\n",
    " \n",
    " Where the indicator function removes the row of the expired asset in the matrix.\n",
    "\n",
    "Cash flow matrix for both final and coupon cash flows:\n",
    "\n",
    " $$ CF_{i+1}^{A,N} = CF_{i}^{A,N} I_{t_{ijk}\\leq 0} $$\n",
    "\n",
    " $$ CF_{i+1}^{A,C} = CF_{i+1}^{A,C} I_{t_{ijk}\\leq 0} $$\n",
    "\n",
    "Where the indicator function removes the row of the expired asset in the matrix.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a63e5435",
   "metadata": {},
   "source": [
    "Note that this step calculates the value and timing of the asset portfolio at the end of the current modelling period. This can be used to price every single asset in the new economic reality implied by the new modelling date.\n",
    "\n",
    "Note that the matricies can change size as assets that have matured are removed from the list."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "93b847d1",
   "metadata": {},
   "source": [
    "## 3) Price the assets to account for the new market conditions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf68e2fb",
   "metadata": {},
   "source": [
    "Calculate the market value of each asset in the new modelling date. This is done using the pricing function of each asset type using the refactored cash flow and timing matrices as well as the new yield curve:\n",
    "\n",
    "$$  MV_{i+1,j,k} = PRICE(DF_{i+1}^{A,N,1},DF_{i+1}^{A,C,1},CF_{i+1}^{A,N},CF_{i+1}^{A,C}, y) $$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21fdcfcf",
   "metadata": {},
   "source": [
    "##  4) Refactor the cashflows and dates from the liabilities to start from the new modelling period\n",
    "\n",
    "Liability cash flows go through a similar process as the assets where the cash flows and timings are adjusted for the new modelling period\n",
    "\n",
    "\n",
    "$$ DF_{i+1}^{L,N,0} = DF_{i}^{L,N,1} - (M_{i+1}-M_i)  $$\n",
    "\n",
    "$$ DF_{i+1}^{L,N,1} = DF_{i+1}^{L,N,0} I_{t_{ijk}\\leq 0} $$\n",
    "\n",
    "$$ CF_{i+1}^{L,N} = CF_{i}^{L,N} I_{t_{ijk}\\leq 0} $$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bd74a4bf",
   "metadata": {},
   "source": [
    "## 5) Declare reserves in the new modelling period\n",
    "\n",
    "$$ RV_{i+1,j,k} = RESERVE(DF_{i+1}^{L,N,1}, CF_{i+1}^{L,N}, y, *)  $$\n",
    "\n",
    "This is done using the reserving functions for each liability modelling point using the refactored cash flow and timing matrices, demographic date, the new yield curve etc.\n",
    "\n",
    "also, the reserve requirement of the entire portfolio can be calculated as:\n",
    "\n",
    "$$ RV_{i+1} = \\sum_{PTF} \\omega_{i+1,j,k}RV_{i+1,j,k}  $$\n",
    "\n",
    "An alternative approach is to carry forward the reserve at time 0:\n",
    "\n",
    "$$ RV_{i+1,j,k} = RV_{i,j,k} * (1+ y(MD_{i+1}- MD_i))^{MD_{i+1}- MD_i} + cf_{ijk}^{IN} - cf_{ijk}^{OUT}    $$\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c799eeb5",
   "metadata": {},
   "source": [
    "##  6) Calculate the return of the portfolio between the two modelling periods\n",
    "\n",
    "$$ R_{i+1,j,k} = \\frac{MV_{i+1,j,k} - MV_{i,j,k}}{MV_{i,j,k}}  $$\n",
    "\n",
    "the return of the entire portfolio is:\n",
    "\n",
    "$$ R_{i+1} = \\sum_{PTF} \\omega_{i+1,j,k}R_{i+1,j,k}  $$\n",
    "\n",
    "also, save the market value of the entire portfolio, used to compare the asset balance sheet with the liability side:\n",
    "\n",
    "$$ MV_{i+1} = \\sum_{PTF} \\omega_{i+1,j,k}MV_{i+1,j,k}  $$\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "381b9f99",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "fe6e854b",
   "metadata": {},
   "source": [
    "## 7) Calculate the net position of the company\n",
    "\n",
    "Calculate the net balance between cash returns from investments and the obligations from the passive part of the balance sheet. This will trigger either the selling of assets to cover this period's liquidity need or the investment of excessive cash flows. By selecting the option XXX, the algorithm can also keep a liquid position equal to a fixed percentage of market value. This parameter can be found in XXX."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "580c6923",
   "metadata": {},
   "source": [
    "## 8) Generate new assets\n",
    "\n",
    "Generate new assets that were issued at the new time period."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "80b63f63",
   "metadata": {},
   "source": [
    "##  9) Sell to cover the balance or buy new instruments"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "38c550d9",
   "metadata": {},
   "source": [
    "If selling needed:\n",
    " - Apply the selling of assets. Using one of the strategies shown in XXX\n",
    " - Prioritize selling of existing assets\n",
    " - Check if the new asset allocation respects the target asset allocation\n",
    " - Sell/buy again if needed.\n",
    "\n",
    "If buying necessary:\n",
    " - Check if can be kept in cash\n",
    " - Apply buying in assets as per the strategies shown in XXX\n",
    " - Check if asset allocation respected\n",
    " - Sell/buy again\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b9b11fb6",
   "metadata": {},
   "source": [
    "##  10) Calculate the income statement, solvency ratio and other views of interest"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a6eb4d6",
   "metadata": {},
   "source": [
    "ToDo"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19645130",
   "metadata": {},
   "source": [
    " ### 11) Close the period and save results"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b114ce52",
   "metadata": {},
   "source": [
    "Prepare and save the final asset allocation"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}