Container construction utilities

[bob-carpenter]

Summary:

Provide functions to construct commonly used containers.

Description:

Here are suggested signatures:

// [1/K, ..., 1/K]'
vector uniform_simplex(int K);

// [1, ..., 1]'
vector ones_vector(int K);

// [0, ..., 0]'
vector zeros_vector(int K);

// [c, ..., c]'
vector constant_vector(double c);

// diag_matrix(ones_vector(K))
matrix identity_matrix(int K);

// [low, ..., high]' with equal spacing between values in ...
vector set_spaced_vector(real low, real high, int K);

// [0, ..., 1, ..., 0]'  with 1 in k-th position (indexing from 1)
vector one_hot_vector(int k, int K);

These all need to validate sizes are non-negative and validate other bounds like the index being in ragne for one_hot_vector.

We could also have versions for _row_vector and _array, and _int_array.

This lines up with what's available in Eigen [we already have rep_vector for their constant vectors and specific RNGs].

Additional Information:

These only require double-based implementations in C++, because in Stan there are only integer arguments, so there can't be any derivatives. For example, this function will have to be added to stan/math/prim/mat/fun/uniform_simplex.hpp and then included in the header for prim/mat.hpp.

Eigen::VectorXd uniform_simplex(long K) {
  // validate that K is positive
  // return K-vector filled with 1.0 / K (the 1.0 avoids int division)

The implementation of uniform_simplex can call const_vector.

Current Version:

v2.17.0

[mcol]

Having added the vector version, I'm now going to add the rest. I won't be adding an int_array version of uniform_simplex and set_spaced, as I don't think they make sense (the latter should be called sequence or similar, if it doesn't exist already).

I have a question: do we need row vector and array versions of uniform_simplex? If so, @bob-carpenter do you have a suggestion as for naming?

[bob-carpenter]

I have a question: do we need row vector and array versions of uniform_simplex?

No. Transposition gives a row vector and we don't need arrays---simplexes are holistic vectors, not something we want to deal with elementwise.