Add remittances to OG-Core

[rickecon]

This adds remittances to OG-Core and does some heavy updates to the documentation. This PR:

• 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 on of the tests in test_run_TPI.py::test_run_TPI_full_run[Baseline, small open] was failing due to `RuntimeError: Steady state aggregate resource constraint not satisfied. The maximum absolute resource constraint error was 2.29575914e-09.
• 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]).
• Updated three directory path references that were out of date in test_run_example.py.
• Updated expected value tuples and dictionaries in test_txfunc.py.

cc: @jdebacker

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 83.82353% with 11 lines in your changes missing coverage. Please review.

Project coverage is 70.14%. Comparing base (92f7594) to head (30d7977).
Report is 94 commits behind head on master.

Files with missing lines	Patch %	Lines
ogcore/TPI.py	47.61%	11 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #971      +/-   ##
==========================================
+ Coverage   69.98%   70.14%   +0.16%     
==========================================
  Files          20       20              
  Lines        4977     5038      +61     
==========================================
+ Hits         3483     3534      +51     
- Misses       1494     1504      +10     

Flag	Coverage Δ
unittests	70.14% <83.82%> (+0.16%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
ogcore/SS.py	72.48% <100.00%> (+0.50%)	⬆️
ogcore/__init__.py	100.00% <100.00%> (ø)
ogcore/aggregates.py	100.00% <100.00%> (ø)
ogcore/constants.py	100.00% <ø> (ø)
ogcore/household.py	87.87% <100.00%> (+0.60%)	⬆️
ogcore/parameter_plots.py	78.34% <100.00%> (+0.05%)	⬆️
ogcore/parameters.py	83.12% <100.00%> (+0.21%)	⬆️
ogcore/tax.py	100.00% <ø> (ø)
ogcore/TPI.py	36.45% <47.61%> (+0.62%)	⬆️

... and 1 file with indirect coverage changes

[rickecon]

@jdebacker. I think this PR is now ready for review and to be merged if accepted. In addition to running the run_ogcore_example.py script successfully as documented above, I ran all the tests--both GH Actions and local. The results are below. All the tests pass except for the 9 detailed below. And my recommendation is that we solve those remaining 9 errors in separate PRs. In summary:

• There is 1 test in test_TPI.py that is failing (test_run_TPI_full_run[Baseline, small open]). The TPI equilibrium converges, but the resource constraint error is too big (0.07786113397046332). This case probably needs to be looked at. I recommend we do this in another PR.
• The 8 local tests in test_demographics.py fail, but the 8 GH Actions tests pass. All 8 failing tests fail with this error (OSError: pytest: reading from stdin while output is captured! Consider using -s.) and the output is all stalled asking for Please enter your UN API token (press return if you do not have one):. This is clearly an issue with the UN API token functionality and needs to be fixed. I recommend we do this in another PR.

(ogcore-dev) richardevans@Richards-MacBook-Pro-2 OG-Core % git status
On branch remit
nothing to commit, working tree clean
(ogcore-dev) richardevans@Richards-MacBook-Pro-2 OG-Core % pytest
============================= test session starts ==============================
platform darwin -- Python 3.12.5, pytest-8.3.2, pluggy-1.5.0
rootdir: /Users/richardevans/Docs/Economics/OSE/OG-Core
configfile: pytest.ini
testpaths: ./tests
plugins: cov-5.0.0, anyio-4.4.0, xdist-3.6.1
collected 580 items                                                            

tests/test_SS.py ...................................                     [  6%]
tests/test_TPI.py ...........F...............                            [ 10%]
tests/test_aggregates.py ........................................        [ 17%]
tests/test_basic.py ....                                                 [ 18%]
tests/test_demographics.py F...FFFF..F...FF                              [ 21%]
tests/test_elliptical_u_est.py .......                                   [ 22%]
tests/test_execute.py .                                                  [ 22%]
tests/test_firm.py ..................................................... [ 31%]
................                                                         [ 34%]
tests/test_fiscal.py ...................                                 [ 37%]
tests/test_household.py ................................................ [ 45%]
..                                                                       [ 46%]
tests/test_output_plots.py ............................................. [ 53%]
..                                                                       [ 54%]
tests/test_output_tables.py ..............                               [ 56%]
tests/test_parameter_plots.py ........................................   [ 63%]
tests/test_parameter_tables.py .......                                   [ 64%]
tests/test_parameters.py ..............                                  [ 67%]
tests/test_pensions.py ...............................                   [ 72%]
tests/test_run_example.py ..                                             [ 72%]
tests/test_run_ogcore.py .                                               [ 73%]
tests/test_tax.py .................................                      [ 78%]
tests/test_txfunc.py ...............................                     [ 84%]
tests/test_user_inputs.py .........                                      [ 85%]
tests/test_utils.py .................................................... [ 94%]
...............................                                          [100%]
=========================== short test summary info ============================
FAILED tests/test_TPI.py::test_run_TPI_full_run[Baseline, small open] - assert False
FAILED tests/test_demographics.py::test_get_pop_objs_read_UN_data - OSError: pytest: reading from stdin while output is captured!  Consider usi...
FAILED tests/test_demographics.py::test_imm_smooth - OSError: pytest: reading from stdin while output is captured!  Consider usi...
FAILED tests/test_demographics.py::test_get_fert - OSError: pytest: reading from stdin while output is captured!  Consider usi...
FAILED tests/test_demographics.py::test_get_mort - OSError: pytest: reading from stdin while output is captured!  Consider usi...
FAILED tests/test_demographics.py::test_infant_mort - OSError: pytest: reading from stdin while output is captured!  Consider usi...
FAILED tests/test_demographics.py::test_custom_series - OSError: pytest: reading from stdin while output is captured!  Consider usi...
FAILED tests/test_demographics.py::test_infer_pop_nones - OSError: pytest: reading from stdin while output is captured!  Consider usi...
FAILED tests/test_demographics.py::test_data_download - OSError: pytest: reading from stdin while output is captured!  Consider usi...
FAILED tests/test_run_example.py::test_run_ogcore_example - FileNotFoundError: [Errno 2] No such file or directory: '/Users/richardevan...
FAILED tests/test_run_example.py::test_run_ogcore_example_output - FileNotFoundError: [Errno 2] No such file or directory: '/Users/richardevan...
FAILED tests/test_txfunc.py::test_txfunc_est[DEP] - assert False
FAILED tests/test_txfunc.py::test_txfunc_est[GS] - assert False
FAILED tests/test_txfunc.py::test_tax_func_loop - assert False
FAILED tests/test_txfunc.py::test_tax_func_estimate - assert False
======== 9 failed, 571 passed, 16801 warnings in 44933.83s (12:28:53) =========

[rickecon]

@jdebacker. I made the following updates:

• Updated all instances of the resource constraint function aggregates.get_resource_constraint() in the model.
• Updated instances of the resource constraint to include "- RM_t" in the docstring for aggregate.get_resource_constraint(), in the unstationarized resource constraint equation and corresponding text in the market_clearing.md chapter, and in the stationarized resource constraint equation in the stationarized.md chapter.
• Added my un_api_token.txt file to my OG-Core main directory. Now all the demographics.py local tests pass. I did have to update the test_infant_mort() test expected value from 0.00477758 to 0.00496921.

[rickecon]

@jdebacker. Now all the tests are passing, both GH Actions and local (see output below). This PR should now be ready to go.

(ogcore-dev) richardevans@Richards-MacBook-Pro-2 OG-Core % pytest
============================= test session starts ==============================
platform darwin -- Python 3.12.5, pytest-8.3.2, pluggy-1.5.0
rootdir: /Users/richardevans/Docs/Economics/OSE/OG-Core
configfile: pytest.ini
testpaths: ./tests
plugins: cov-5.0.0, anyio-4.4.0, xdist-3.6.1
collected 580 items

tests/test_SS.py ...................................                     [  6%]
tests/test_TPI.py ...........................                            [ 10%]
tests/test_aggregates.py ........................................        [ 17%]
tests/test_basic.py ....                                                 [ 18%]
tests/test_demographics.py ................                              [ 21%]
tests/test_elliptical_u_est.py .......                                   [ 22%]
tests/test_execute.py .                                                  [ 22%]
tests/test_firm.py ..................................................... [ 31%]
................                                                         [ 34%]
tests/test_fiscal.py ...................                                 [ 37%]
tests/test_household.py ................................................ [ 45%]
..                                                                       [ 46%]
tests/test_output_plots.py ............................................. [ 53%]
..                                                                       [ 54%]
tests/test_output_tables.py ..............                               [ 56%]
tests/test_parameter_plots.py ........................................   [ 63%]
tests/test_parameter_tables.py .......                                   [ 64%]
tests/test_parameters.py ..............                                  [ 67%]
tests/test_pensions.py ...............................                   [ 72%]
tests/test_run_example.py ..                                             [ 72%]
tests/test_run_ogcore.py .                                               [ 73%]
tests/test_tax.py .................................                      [ 78%]
tests/test_txfunc.py ...............................                     [ 84%]
tests/test_user_inputs.py .........                                      [ 85%]
tests/test_utils.py .................................................... [ 94%]
...............................                                          [100%]
============= 580 passed, 16801 warnings in 45150.36s (12:32:30) ==============

[rickecon]

@jdebacker. I think this PR is ready now. All tests have passed, and I responded to all of your comments/requests.

[jdebacker]

@rickecon Thank you for all the work on this PR. Amazing updates to the docs and the remittances are doing to be critical for certain country calibrations. Nice job on this!