implement benchmARK

[alanlujan91]

Simple profiler for HARK models. See #982.

Example usage:

from HARK.utilities import benchmark
from HARK.ConsumptionSaving.ConsPortfolioModel import PortfolioConsumerType
agent = PortfolioConsumerType(cycles = 0)
benchmark(agent)

Output:

Mon Apr 11 19:58:07 2022    restats
         2447109 function calls (2232506 primitive calls) in 4.810 seconds
   Ordered by: internal time
   List reduced from 213 to 10 due to restriction <10>
   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
    12308    1.111    0.000    1.111    0.000 utilities.py:221(CRRAutilityP)
    15510    0.771    0.000    0.771    0.000 {method 'searchsorted' of 'numpy.ndarray' objects}
    10080    0.539    0.000    1.075    0.000 interpolation.py:798(_evalOrDer)
     2715    0.502    0.000    0.786    0.000 interpolation.py:1377(_evaluate)
184035/45795    0.300    0.000    4.380    0.000 {built-in method numpy.core._multiarray_umath.implement_array_function}
      724    0.223    0.000    3.645    0.005 shape_base.py:267(apply_along_axis)
    20272    0.138    0.000    0.138    0.000 ConsPortfolioModel.py:603(m_nrm_next)
    19186    0.109    0.000    0.281    0.000 function_base.py:5143(insert)
      181    0.074    0.000    0.244    0.001 ConsPortfolioModel.py:731(optimize_share)
66564/1091    0.060    0.000    0.147    0.000 copy.py:128(deepcopy)

[alanlujan91]

Profiling tool for HARK models. Calling benchmark on agents calls the solver for
the agents and provides time to solve as well as the top max_print function calls
in terms of sort_by. Optionally allows for saving a text copy of the profile
as well as returning the Stats object for further inspection.

Parameters
----------
agent_type: AgentType
        A HARK AgentType with a solve() method.
sort_by: string
        A string to sort the stats by.
max_print: int
        Number of lines to print
filename: string
        Optional filename to save output.
return_output: bool
        Boolean to determine whether Stats object should be returned.

Returns
-------
stats: Stats (optional)
      Profiling object with call statistics.

[alanlujan91]

Note: In Table statistics, interpolation.py is not EconForge's library but HARK's internal file HARK.interpolation.py.

[sbenthall]

As this is passed directly to pstats.Stats, it would make sense to have a link in the docstring to the relevant python documentation. As is, you really have to look at the code to understand how to use the parameters

[sbenthall]

This is great! Well done!

The only comment is that since it basically wraps pstats, which is a bit tricky as a package, it would be best if the docstring linked over to the pstats docs:
https://docs.python.org/3/library/profile.html#module-pstats

[codecov-commenter]

Codecov Report

Merging #1131 (134c097) into master (e701558) will decrease coverage by 0.04%.
The diff coverage is 23.52%.

@@            Coverage Diff             @@
##           master    #1131      +/-   ##
==========================================
- Coverage   73.96%   73.92%   -0.05%     
==========================================
  Files          70       70              
  Lines       10761    10771      +10     
==========================================
+ Hits         7959     7962       +3     
- Misses       2802     2809       +7     

Impacted Files	Coverage Δ
HARK/utilities.py	31.59% <23.52%> (-0.06%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e701558...134c097. Read the comment docs.