Interpolators with "Decay" extrapolation

[Mv77]

This PR introduces enhanced tools to implement functions (represented by interpolators) that asymptotically approach another function for points that fall outside of their grid.

HARK has some tools for this purpose, specifically in interpolation.LinearInterp, which has the option to provide a linear limiting function to which extrapolated values should approach. This PR improves upon those tools in various ways.

• It implements a class DecayInterp that receives an interpolator and a limiting function and returns an object that behaves as HARK's other interpolators but approaches the limiting function when queried about off-grid values. This achieves two generalizations with respect to interpolation.LinearInterp:

  • It works with n-dimensional (not only 1-dimensional) functions. Also, it works with the faster econforge interpolators.
  • The limiting function can be any function, not just a linear function.

• It has different methods for calculating the rate at which extrapolated values approach the limiting function.

• Tests for new functionality/models or Tests to reproduce the bug-fix in code.
• Updated documentation of features that add new functionality.
• Update CHANGELOG.md with major/minor changes.

---

• Remove all the debug lines (prints and plots).

[Mv77]

Here is a test that shows how DecayInterp compares to the current LinearInterp options
https://github.com/Mv77/HARK/blob/259fc6c510a1718e036ff40efae0575bc15ac546/HARK/tests/test_econforgeinterp.py#L388-L402

@llorracc I believe I've succeeded in implementing a decay method (I've called it "decay_hark") that works in multiple dimensions but collapses to the current implementation in 1D. This test compares the two and they produce the same output.

What I still have to wrap my head around is:

• Whether what is currently in there achieves what you wanted, that is, preserving the rate at which the interpolator approaches the limit.
• How to reinterpret the above in multiple dimensions in a way that is tractable.

[llorracc]

Great -- thanks for this. Is the comparison to linearInterp in Decay.ipynb functional already?

[Mv77]

Not yet, I was using that notebook to just store some math scribbles on what I intended to do. I will add examples and comparisons soon!

[Mv77]

Great -- thanks for this. Is the comparison to linearInterp in Decay.ipynb functional already?

@llorracc I have quickly moved some plots and tests to the notebook and added minimal comments in case you want to check out/play with the interpolators.

The comparison with base hark is in there.

I must go out now, but will continue polishing this when the Calvo fairy permits.

[codecov-commenter]

Codecov Report

Base: 73.58% // Head: 73.73% // Increases project coverage by +0.15% 🎉

Coverage data is based on head (8bf4358) compared to base (69c5f9c).
Patch coverage: 87.75% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1165      +/-   ##
==========================================
+ Coverage   73.58%   73.73%   +0.15%     
==========================================
  Files          72       72              
  Lines       11465    11561      +96     
==========================================
+ Hits         8436     8524      +88     
- Misses       3029     3037       +8     

Impacted Files	Coverage Δ
HARK/interpolation.py	43.34% <50.00%> (+0.04%)	⬆️
HARK/econforgeinterp.py	90.47% <88.00%> (+7.61%)	⬆️
HARK/tests/test_econforgeinterp.py	100.00% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[Mv77]

I think this is ready for review. I have not implemented gradients yet, but I think that is a complex-enough and not-urgent-enough issue that it could be in its future own PR, and I don't want it to block this one.

I made a notebook with formal descriptions of each decay method, examples, and comparisons with base-HARK.