The calc_expectations interface

[sbenthall]

Notes from CDC about the current calc_expectation functionality.

# # 20210619: CDC: This method for taking expectations is designed for efficiency but is
# # not at all intuitive for the user because it works only with functions that take as

# handcrafted specialized functions that know that their positional first argument must be
# a matrix whose structure matches the structure of the discrete income distribution provided
# as the first argument. For example, if the 2D distribution is of transitory and permanent
# shocks, the function must take as an input a matrix which is assumed to have a structure
# that exactly mirrors the internal structure of the arrangement of broadcasted transitory
# and permanent shocks inside the dstn object, and knows(for example) that the value of the permanent shock can be how to extract

# hard to understand because it requires the user to
# # provide an array of values of its inputs but then assumes it already knows what those
# # inputs are. This makes little sense. If it is going to assume it knows what the inputs

# "calc_expectation" is not a good name for something that
# requires an array as an argument, returns an array, and
# expects a peculiarly shaped distribution object as its first
# argument.
# TODO: 20210618: we REALLY need to improve our tools for calculating
# expectations, both to make them better documented and more flexible.


calc_expectation_of_array = calc_expectation

[sbenthall]

The main thing I'd add to this discussion is that I believe the intention of the original design is that the expectation calculation function can be vectorized over inputs. Maybe there's a more direct way to go about doing that.