Add remittances to OG-Core

CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.13.0] - 2024-09-17 12:00:00
+
+### Added
+
+- Updates all of the documentation.
+    - Adds remittances to all instances of the household budget constraint
+    - Rewrites bequests and transfers components of household budget constraint in terms of individual variables in all instances
+    - Adds a household transfers section to `households.md` with subsections on bequests, remittances, government transfers, and universal basic income
+    - Changes all instances of $p_t Y_t$ to $Y_t
+    - Updates the steady-state equilibrium algorithm description in `equilibrium.md`
+    - Added updates to the government pensions descriptions in `government.md` and added `pensions` to all instances of the household budget constraint.
+    - Updates the docstrings in `tax.py` for the wealth tax ETR and MTR functions. The code is right. I just thought there was a clearer specification of the equations in LaTeX.
+- Adds remittances to the OG-Core code
+    - Adds aggregate remittances function `get_RM()` to `aggregates.py`
+    - Adds household remittances function `get_rm()` to `household.py`
+    - Adds four new remittance parameters: `alpha_RM_1`, `g_RM`, `alpha_RM_T`, `eta_RM`
+    - We model aggregate remittances as a percent of GDP in the first period, then growing at a specified rate that can deviate from the country growth rate until the cutoff rule period, after which the remittance growth rate trends back to the population growth rate. We also model remittances in reforms as being a percentage of baseline GDP. In this way, if remittance parameters are not changed in the reform, remittances remain at their baseline levels. The only way they change is if their parameter values are changed.
+    - Adds 3 tests using the `test_get_RM()` function in `test_aggregates.py`
+    - Adds 4 tests using the `test_get_rm()` function in `test_household.py`
+    - Changes the `initial_guess_r_SS` in two tests in `test_SS.py` because they were not solving with their current values
+- Increases `RC_SS` steady-state resource constraint tolerance from 1e-9 to 1e-8 because two `test_run_SS()` tests were failing in `test_SS.py` with resource constraints errors just bigger than 1e-9 (-2.29575914e-09 for [Baseline, small open] and -2.29575914e-09 for [Reform, small open]).
+- Increases `RC_TPI` transition path resource constraint tolerance from 1e-5 to 1e-4 in because one `test_run_TPI_full_run()` test was failing in `test_TPI.py` with a resource constraint error just bigger than 1e-5 (1.4459913381864586e-05 for `[Baseline, M=3 non-zero Kg]`).
+    - However, there is another "local only" test that is failing in `test_run_TPI()` in `test_TPI.py` that has a much bigger resource constraint error. The specification is `[Baseline, small open]` with a maximum absolute resource constraint error of 0.07786113397046332. This error is big enough that it needs to be addressed.
+- Updated two directory path references that were out of date in `test_run_example.py`.
+- Updated expected value tuples and dictionaries in `test_txfunc.py`.
+
 ## [0.12.0] - 2024-08-20 12:00:00
 
 ### Added

docs/book/content/api/aggregates.rst

@@ -9,5 +9,5 @@ ogcore.aggregates
 ------------------------------------------
 
 .. automodule:: ogcore.aggregates
-  :members: get_L, get_I, get_B, get_BQ, get_C, revenue, get_r_p,
+  :members: get_L, get_I, get_B, get_BQ, get_RM, get_C, revenue, get_r_p,
     resource_constraint, get_K_splits, get_ptilde

docs/book/content/api/household.rst

@@ -9,6 +9,6 @@ ogcore.household
 ------------------------------------------
 
 .. automodule:: ogcore.household
-  :members: marg_ut_cons, marg_ut_labor, get_bq, get_tr, get_cons, get_ci,
-    FOC_savings, FOC_labor, get_y, constraint_checker_SS,
+  :members: marg_ut_cons, marg_ut_labor, get_bq, get_tr, get_rm, get_cons,
+    get_ci, FOC_savings, FOC_labor, get_y, constraint_checker_SS,
     constraint_checker_TPI

docs/book/content/contributing/contributor_guide.md

@@ -1,3 +1,4 @@
+
 (Chap_ContribGuide)=
 # Contributor Guide
 

docs/book/content/theory/financial.md

@@ -2,59 +2,62 @@
 (Chap_FinInt)=
 # Financial Intermediary
 
-Domestic household wealth $W^d_{t}=B_{t}$ and foreign ownership of domestic assets $W^f_{t}$, both in terms of the numeraire good, are invested in a financial intermediary. This intermediary purchases a portfolio of government bonds and private capital in accordance with the domestic and foreign investor demand for these assets and then returns a single portfolio rate of return to all investors.
+  Domestic household wealth $W^d_{t}=B_{t}$ and foreign ownership of domestic assets $W^f_{t}$, both in terms of the numeraire good, are invested in a financial intermediary. This intermediary purchases a portfolio of government bonds and private capital in accordance with the domestic and foreign investor demand for these assets and then returns a single portfolio rate of return to all investors.
 
-Foreign demand for government bonds is specified in section {ref}`SecMarkClrMktClr_G` of the {ref}`Chap_MarkClr` chapter:
+  Foreign demand for government bonds is specified in section {ref}`SecMarkClrMktClr_G` of the {ref}`Chap_MarkClr` chapter:
 
   ```{math}
   :label: EqMarkClr_zetaD2
     D^{f}_{t+1} = D^{f}_{t} + \zeta_{D, t}(D_{t+1} - D_{t}) \quad\forall t
   ```
 
-This leaves domestic investors to buy up the residual amount of government debt:
+  This leaves domestic investors to buy up the residual amount of government debt:
 
   ```{math}
   :label: EqMarkClr_DomesticDebt
     D^{d}_{t} = D_{t} - D^{f}_{t} \quad\forall t
   ```
 
-We assume that debt dominates the capital markets, such that domestic investor demand for capital, $K^{d}_{t}$ is given as:
+  We assume that debt dominates the capital markets, such that domestic investor demand for capital, $K^{d}_{t}$ is given as:
 
   ```{math}
   :label: eq_domestic_cap_demand
     K^{d}_{t} = B_{t} - D^{d}_{t} \quad\forall t
   ```
 
-Foreign demand for capital is given in {ref}`SecMarkClrMktClr_K`, where $K^{f}_{t}$ is an exogenous fraction of excess capital demand at the world interest rate:
+  Foreign demand for capital is given in {ref}`SecMarkClrMktClr_K`, where $K^{f}_{t}$ is an exogenous fraction of excess capital demand at the world interest rate:
 
   ```{math}
   :label: eq_foreign_cap_demand
     K^{f}_t = \zeta_{K, t}ED^{K,r^*}_t \quad\forall t
   ```
 
-The total amount invested in the financial intermediary is thus:
+  The total amount invested in the financial intermediary is thus:
 
-```{math}
-W_{t} & = W^d_{t} + W^f_{t} \\
-    & = D^d_t + K^d_t  + D^f_t + K^f_t \\
-    & = D_t + K_t
-```
+  ```{math}
+  W_{t} & = W^d_{t} + W^f_{t} \\
+      & = D^d_t + K^d_t  + D^f_t + K^f_t \\
+      & = D_t + K_t
+  ```
 
-Interest rates on private capital through the financial intermediary and on government bonds differ. The return on the portfolio of assets held in the financial intermediary is the weighted average of these two rates of return. As derived in {eq}`EqFirms_rKt` of Section {ref}`EqFirmsPosProfits`, the presence of public infrastructure in the production function means that the returns to private factors of production ($r_t$ and $w_t$) exhibit decreasing returns to scale.[^MoorePecoraro] It is assumed that competition ensures a zero profit condition among firms and the returns to public infrastructure through the returns of firms are captured by the financial intermediary and returned to share holders. The return on capital is therefore the sum of the (after-tax) returns to private and public capital.
+  Interest rates on private capital through the financial intermediary and on government bonds differ. The return on the portfolio of assets held in the financial intermediary is the weighted average of these two rates of return. As derived in {eq}`EqFirms_rKt` of Section {ref}`EqFirmsPosProfits`, the presence of public infrastructure in the production function means that the returns to private factors of production ($r_t$ and $w_t$) exhibit decreasing returns to scale.[^MoorePecoraro] It is assumed that competition ensures a zero profit condition among firms and the returns to public infrastructure through the returns of firms are captured by the financial intermediary and returned to share holders. The return on capital is therefore the sum of the (after-tax) returns to private and public capital.
+
+  ```{math}
+  :label: eq_rK
+    r_{K,t}  = r_{t} + \frac{\sum_{m=1}^M(1 - \tau^{corp}_{m,t})p_{m,t}MPK_{g,m,t}K_{g,m,t}}{\sum_{m=1}^M K_{m,t}} \quad\forall t
+  ```
 
-```{math}
-:label: eq_rK
-  r_{K,t}  = r_{t} + \frac{\sum_{m=1}^M(1 - \tau^{corp}_{m,t})p_{m,t}MPK_{g,m,t}K_{g,m,t}}{\sum_{m=1}^M K_{m,t}} \quad\forall t
-```
+  The return on the portfolio of assets held by the financial intermediary is thus a weighted average of the return to government debt $r_{gov,t}$ from {eq}`EqUnbalGBC_rate_wedge` and the adjusted return on private capital $r_{K,t}$ from {eq}`eq_rK`.
 
-The return on the portfolio of assets held by the financial intermediary is thus a weighted average of the return to government debt $r_{gov,t}$ from {eq}`EqUnbalGBC_rate_wedge` and the adjusted return on private capital $r_{K,t}$ from {eq}`eq_rK`.
+  ```{math}
+  :label: eq_portfolio_return
+    r_{p,t} = \frac{r_{gov,t}D_{t} + r_{K,t}K_{t}}{D_{t} + K_{t}} \quad\forall t \quad\text{where}\quad K_t \equiv \sum_{m=1}^M K_{m,t}
+  ```
 
-```{math}
-:label: eq_portfolio_return
-  r_{p,t} = \frac{r_{gov,t}D_{t} + r_{K,t}K_{t}}{D_{t} + K_{t}} \quad\forall t \quad\text{where}\quad K_t \equiv \sum_{m=1}^M K_{m,t}
-```
 
 (SecFinfootnotes)=
 ## Footnotes
 
+  This section contains the footnotes for this chapter.
+
   [^MoorePecoraro]: See also {cite}`MoorePecoraro:2021` for a similar treatment of government infrastructure investment, positive profits, and returns to the owners of capital.

docs/book/content/theory/firms.md

@@ -119,6 +119,8 @@ Industry $M$ in the model is unique in two respects.  First, we will define indu
 (SecFirmsfootnotes)=
 ## Footnotes
 
+  This section contains the footnotes for this chapter.
+
   [^Kg0_case]: It is important to note a special case of the Cobb-Douglas ($\varepsilon_m=1$) production function that we have to manually restrict. The inputs of production of private capital $K_{m,t}$ and labor $L_{m,t}$ are endogenous and have characteristics of the model that naturally bound them away from zero. But public capital $K_{g,m,t}$, although it is a function of endogenous variables in {eq}`EqUnbalGBC_Igt` and {eq}`EqUnbalGBC_Igmt`, can be exogenously set to zero as a policy parameter choice by setting $\alpha_{I,t}=0$ or $\alpha_{I,m,t}=0$. In the Cobb-Douglas case of the production function $\varepsilon_m=1$ {eq}`EqFirmsCDprodfun`, $K_{g,m,t}=0$ would zero out production and break the model. In the case when $\varepsilon_m=1$ and $K_{g,m,t}=0$, we set $\gamma_{g,m}=0$, thereby restricting the production function to only depend on private capital $K_{m,t}$ and labor $L_{m,t}$. This necessary restriction limits us from performing experiments in the model of the effect of changing $K_{g,m,t}=0$ to $K_{g,m,t}>0$ or vice versa in the $\varepsilon_m=1$ case.
 
   [^delta_M]: Because we are assuming that only the output of the $M$th industry can be used for investment, government spending, or government debt, and because that industry's output is the numeraire, the only depreciation rate that matters or can be nonzero is that of the $M$th industry $\delta_{M,t}$.