adding PerfForesightConsumerTypeFast

[alanlujan91]

Please ensure your pull request adheres to the following guidelines:

• 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.

Would like suggestions on the boxes not checked.

This PR creates ConsIndShockFastModel which for now only contains PerfForesightFastConsumerType, a numba implementation of PerfForesightConsumerType.

I have also added basic __eq__ for comparison of models and solutions as in #612.

ConsIndShockFastModel

The goal of this PR is to create a mirror to ConsIndShockModel.py, but that implements faster solutions using numba just-in-time compiling and optimization.

PerfForesightSolution

The first step is to create a solution object called PerfForesightSolution that contains only python primitives and numba arrays. This object takes the place of ConsumerSolution, which creates additional HARK objects and can lead to unnecessary time overhead in the solution iteration. The distance_criteria for this solution is ["cNrm", "mNrm"], which is identical to the distance_criteria for ConsumerSolution but more straight forward. This ConsumerSolution replacement is faster because instead of having to create HARK objects such as cFunc, vFunc, etc. as LinearInterpolators for every solution iteration, the solution method or algorithm only really needs the primitives that compose these objects. Below I will describe in more detail how this object is used in the solver.

ConsPerfForesightFastSolver

The next step is to create a solver that replaces ConsPerfForesightSolver, aptly called ConsPerfForesightFastSolver. The object uses a numba-optimized helper function called solveConsPerfForesightNumba. In this implementation, the outputs of this helper method are packaged into a PerfForesightSolution object instead of a ConsumerSolution object. As I mentioned, this avoids the needless creation of other HARK objects in the iteration, leaving the creation of a proper HARK solution to the end of the iteration. An additional feature that has been removed from the solution iteration is the searching of steady-state normalized market resources with addSSmNrm(). As the iteration does not depend on this result as an intermediate input, this can be safely moved to the end of the solution method, or rather to postSolve().

PerfForesightFastConsumerType

Finally, I create an agent that can use the above solution method called PerfForesightFastConsumerType. Since now the solution iteration uses PerfForesightSolution, I first override solution_terminal_ = PerfForesightSolution(). Then, on __init__, I override solveOnePeriod to ConsPerfForesightFastSolver. Since I am overriding the solution_terminal_, I might still need a ConsumerSolution terminal in the case of a non-infinite problem. So, I override the method updateSolutionTerminal() to save an internal ConsumerSolution version of the solution_terminal. The final step is to implement a postSolve() method to wrap every PerfForesightSolution parameter into a HARK object and to run addSSmNrmNumba() only on the final solution. As I had mentioned, there is no need to create these objects at every iteration step of the solution, and it is thus more efficient to leave them to postSolve(). Now, ideally, the output of solve() is the same between the standard HARK approach and the fast approach, a list of ConsumerSolution objects with cFunc, vFunc, etc. as HARK LinearInterpolators.

Checking for Equality

[MridulS]

Would like suggestions on the boxes not checked.

For the changelog one, let's wait till we make a 0.10.7 release first, then you can add this to the changelog for 0.10.8. You would need to edit this file https://github.com/econ-ark/HARK/blob/master/Documentation/CHANGELOG.md

For the documentation one, as you have added new functionality and files you also need to add this to the documentation folder so that the documentation site (https://hark.readthedocs.io/en/latest/) is able to scrap the new model class.
Go to Documentation/reference/ConsumptionSaving and create a new file ConsIndShockFastModel.rst with the content

ConsIndShockFastModel
----------------------------

.. automodule:: HARK.ConsumptionSaving.ConsIndShockFastModel
   :members:
   :undoc-members:
   :show-inheritance:

Sphinx will do rest of the work to scrap through the class docstrings and generate a documentation page for it.

[llorracc]

My preference for naming is to add extra things to the beginning or the end of the name of an existing object; so, PerfForesightConsumerTypeFast

[alanlujan91]

I've removed everything relating to __eq__ to move it to its own PR later on. @MridulS I think this is ready to review and merge as only adding PerfForesightConsumerTypeFast