Update manual with new log_mix functionality

[andrjohns]

Summary:

New log_mix functions allow for use with vectors and arrays (as opposed to the current version which is a ternary scalar function), need to update the manual to reflect this (both in terms of function signatures and examples).

Description:

I'm writing up changes to the manual to add the new signatures for log_mix (as in stan-dev/stan#2532).

• The function is currently listed under 'Composed Functions' with the signature (real theta, real lp1, real lp2) (page 455), should I add the new signatures here or should I make a new entry in 'Matrix Operations'?
• Given the amount of new valid signatures (15), should I add all of them or only part?
• There are several examples in the manual using log_sum_exp for mixtures with more than two components, should I rewrite these to use log_mix or leave that for a separate pull?

Current Version:

v2.17.1

[bob-carpenter]

Updates to the manual should go with the PR that adds the new functions. We need to be checking that in code review in stan-dev/stan.

If the new functions have already been merged, then we'll have to do this through a separate PR. If they haven't been merged, then the manual updates shold be part of the PR for adding the function.

[spinkney]

Can we get log_mix updated? I didn't even know that this was updated until a few days ago!

There's possibly some confusion (at least on my end) about how the manual specifies the erroneous attempt to vectorize mixtures with this "vectorized" implementation that I would like cleared up.

[bob-carpenter]

I'm not even sure what the signature is here. I'm tagging @WardBrian who's been cleaning up all of our doc and should be able to figure out from the OCaml code what exactly is supported in the way of signatures.

I've used shorthand to describe complicated signatures, like reals to denote scalars or 1D containers.

And yes, rewriting examples in the doc that use log_sum_exp using log_mix would be great.

[andrjohns]

Sorry, this was one that I should have done a long time ago. If it's helpful, an example of the usage is in the example models repo here: https://github.com/stan-dev/example-models/blob/master/basic_estimators/normal_mixture_k.stan

Also, some discussion of the usage/syntax are in these comment threads from the original PRs:

• Vectorised log_mix with gradients math#664 (comment)
• log_mix - Multivariate Containers math#751 (comment)

[WardBrian]

The supported signatures in stanc3 are:

log_mix(real, real, real) => real
log_mix(vector, vector) => real
log_mix(vector, row_vector) => real
log_mix(vector, array[] real) => real
log_mix(vector, array[] vector) => real
log_mix(vector, array[] row_vector) => real
log_mix(row_vector, vector) => real
log_mix(row_vector, row_vector) => real
log_mix(row_vector, array[] real) => real
log_mix(row_vector, array[] vector) => real
log_mix(row_vector, array[] row_vector) => real
log_mix(array[] real, vector) => real
log_mix(array[] real, row_vector) => real
log_mix(array[] real, array[] real) => real
log_mix(array[] real, array[] vector) => real
log_mix(array[] real, array[] row_vector) => real

I think the standard we use is to list the original function and then use the R/T syntax to list vectorized options, see e.g. https://mc-stan.org/docs/2_28/functions-reference/betafun.html

Though functions like beta seem to be much more vectorized than log_mix is. Here are all it's valid signatures in stanc3:

https://gist.github.com/WardBrian/0498ea88312fed7de4a3eaa439e6ec2c