Deprecate metric argument and property, rename to inv_metric

[WardBrian]

Submission Checklist

• Run unit tests
• Declare copyright holder and open-source license: see below

Summary

Closes #803

This renames the metric property of CmdStanMCMC to inv_metric, with the old property still available but raising a warning.

Secondly, it updates how the initial inverse metric is provided. The pre-existing metric argument is split into two, metric which still exists to specify only the metric type (e.g. "diag_e"), and a new inv_metric which specifies the value. This handling is written from-scratch using some of the helpers that already existed for e.g. init files. Besides the existing types, it can also now accept numpy arrays, meaning it is valid to write

model.sample(..., inv_metric=old_fit.inv_metric)

I am not completely confident that the error handling is as robust as previous, it's probably possible to come up with a bad argument that wouldn't be caught until actually running cmdstan, rather than trapped as a nicer error in the Python level.

Copyright and Licensing

Please list the copyright holder for the work you are submitting (this will be you or your assignee, such as a university or company):

Simons Foundation

By submitting this pull request, the copyright holder is agreeing to license the submitted work under the following licenses:

• Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)

[WardBrian]

@mitzimorris I'd appreciate a review if you are able!

[mitzimorris]

If I understand correctly: the metric is specified by the inverse mass matrix which is either unit, dense, or diagonal, therefore the only property name we change is "metric" to "inv_metric" which holds, directly or indirectly, a matrix or list of matrices?

Therefore we should say "inverse mass matrix" in the doc comments and messages when talking about the matrix and its contents.

Otherwise this looks good and I like the encapsulated functions for dealing with metric files.

[mitzimorris]

type of the inverse mass matrix?

[WardBrian]

Corrected!

[bob-carpenter]

The mass matrix and metric are the same matrix. For a multivariate normal, the best value is the covariance, as that preconditions the multivariate normal back to unit covariance. See page 31 of Betancourt's conceptual intro to HMC.

For years, I'd had a bunch of this turned around in my head and in our doc and on the board as in the Stan meeting. Sorry!

[mitzimorris]

LGTM!