Add discrete uniform rng for stan#2457

[syclik]

Summary:

Add a discrete uniform rng for stan-dev/stan#2457.

Additional Information:

Can use boost.

Current Version:

v2.17.0

[bob-carpenter]

What's the behavior and signature? Mainly, how are the possible outcomes specified? I can imagine

• discrete_uniform_rng(N) : generate uniform on 1:N

• discrete_uniform_rng(L, U): generate uniform on (L, U)

• discrete_uniform({a, b, c}) : uniform on {a, b, c}

  • integer only a, b, c
  • real allowed

[syclik]

when I discussed with @lcomm, the behavior and signature was closest to the second option:

discrete_uniform_rng(L, U): generate uniform on [L, U] inclusive of the bounds

I think this seems reasonable:

generated quantities {
  int n = discrete_uniform_rng(1, 10);
}

would randomly generate a number from 1 to 10 inclusive. (I looked at R's purrr::rdunif and it's also inclusive.)

[lcomm]

Yes, as @syclik says, that's the behavior that seems most natural to me. We also discussed naming schemes and discrete_uniform makes more sense than uniform_discrete since the other distributions have set a precedent of [distribution]_[link] (like bernoulli_logit). The discrete uniform is its own distribution and not a variant of the continuous version.

[bob-carpenter]

How about: discrete_range_lpmf(y | lb, ub) It matches our Distribution_Parameterization naming convention. Definitely inclusive on bounds to match constraints in declarations. Definitely don't want to confuse with the uniform lpdf. categorical is also bad in that we've taken categorical to be just over 1:K as currently defined.

[mcol]

I have a working version of discrete_range_rng currently declared as:

template <typename T_lower, typename T_upper, class RNG>
inline typename VectorBuilder<true, int, T_lower, T_upper>::type
discrete_range_rng(const T_lower& lower, const T_upper& upper, RNG& rng)

Should we restrict it so that lower and upper are integers or integer arrays? If so, am I right in thinking that that's done by exposing only the int signatures, so the above is fine? If we don't restrict to ints, what would discrete_range_rng(1.2, 8.4) return?