chains object design & permutation

[Bob Carpenter]

I pushed a version of mcmc::chains last night, but
given our discussion today, I'm going to need to do
some work on it before Jiqiang can use it for R or
before Daniel can add in the posterior analysis methods.

I realized this meeting that the fundamental difference
between how Andrew and I are viewing these objects is
that Andrew's looking top-down at some high-level functionality
running in the usual case, and I'm looking bottom-up at
trying to build modular components that can be independently
documented and tested and behave well on edge cases.
Of course, we want Stan to satisfy both masters -- it should
have the right top-down functionality and be modular.

Let's look at permuting outputs for scalar parameters.
I think we need three methods on the chains object:

void
get_warmup_samples(size_t param,
size_t chain,
vector<double>& vals);

void
get_kept_samples(size_t param,
size_t chain,
vector<double>& vals);

void
get_kept_samples(size_t param,
vector<double>& vals);

The first example gets warmup values (not samples) per chain
w/o scrambling.

The second gets the post-warmup samples for a chain w/o scrambling.

The third gets all the samples cross-chain with implicit
scrambling. This will need to check if there's already an
applicable permutation of the right length and generate
one if not. Then it needs to apply it.

But given we're permuting cross-chains into a shared chains,
applying the permutation's a bit hairy on the indexing side
if we want to avoid copies.

We probably also want versions of the above for multivariate
parameters that'll write all their values into a suitable
multi-dimensional array.

I was thinking for the middle case we'd just return
a constant reference to the actual chain, but that's not
going to work with things broken into warmup and kept.

This is with absolute indexing of parameters. If we want
to do it by parameter name and index (e.g., entry (1,3) in matrix
"Sigma"), then we'll use the symbol table method first to derive
the index and then call one of the above.

size_t
get_param_index(const string& name,
const vector<size_t>& indexes);

The indexing's all implemented already, but not the various
getters for warmup/non-warmup samples.

I'll work on that next.

- Bob