Update manual with new log_mix functionality about docs HOT 5 CLOSED

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.

from docs.

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.

from docs.

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.

from docs.

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:

• stan-dev/math#664 (comment)
• stan-dev/math#751 (comment)

from docs.

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

from docs.