Merge pull request #832 from stan-dev/fix-log-mix

Fix log_mix signature

.gitattributes

@@ -0,0 +1 @@
+src/functions-reference/functions_index.qmd linguist-generated=true

src/functions-reference/real-valued_basic_functions.qmd

@@ -1601,7 +1601,7 @@ The logarithm of one minus the natural exponentiation of x
 Return the natural logarithm of the difference of the natural
 exponentiation of x and the natural exponentiation of y. \begin{equation*}
 \mathrm{log\_diff\_exp}(x,y) = \begin{cases} \log(\exp(x)-\exp(y)) &
-\text{if } +\infty > x \ge y \\[6pt] 
+\text{if } +\infty > x \ge y \\[6pt]
 \textrm{NaN} & \text{otherwise} \end{cases}
 \end{equation*}
 
@@ -1628,11 +1628,26 @@ proportion theta, defined by \begin{eqnarray*}
 \lambda_1, \ \log(1 - \theta) + \lambda_2\right). \end{eqnarray*}
 {{< since 2.6 >}}
 
-<!-- R; log_mix; (T1 theta, T2 lp1, T3 lp2); -->
-\index{{\tt \bfseries log\_mix }!{\tt (T1 theta, T2 lp1, T3 lp2): real}|hyperpage}
+<!-- R; log_mix; (T1 thetas, T2 lps); -->
+\index{{\tt \bfseries log\_mix }!{\tt (T1 thetas, T2 lps): real}|hyperpage}
+
+`R` **`log_mix`**`(T1 thetas, T2 lps)`<br>\newline
+
+Calculates the log mixture density given `thetas`,
+mixing proportions which should be between 0 and 1 and sum to 1,
+and `lps`, log densities.
+These two containers must have the same length.
+
+\begin{eqnarray*}
+\mathrm{log\_mix}(\theta, \lambda)
+& = & \log \!\left( \sum_{n=1}^N \theta_n * \exp(\lambda_n) \right) \\[3pt]
+& = & \mathrm{log\_sum\_exp}\!\left(\log(\theta) + \lambda\right).
+\end{eqnarray*}
+
+This is a generalization of the above signature of three arguments to
+more than two densities.
+For example, `log_mix(lambda, lp1, lp2) == log_mix({lambda, 1 - lambda}, {lp1, lp2})`.
 
-`R` **`log_mix`**`(T1 theta, T2 lp1, T3 lp2)`<br>\newline
-Vectorized implementation of the `log_mix` function
 {{< since 2.26 >}}
 
 <!-- R; log_sum_exp; (T1 x, T2 y); -->