1 #ifndef STAN_MATH_PRIM_FUN_FALLING_FACTORIAL_HPP
2 #define STAN_MATH_PRIM_FUN_FALLING_FACTORIAL_HPP
3
4 #include <stan/math/prim/meta.hpp>
5 #include <stan/math/prim/err.hpp>
6 #include <stan/math/prim/fun/boost_policy.hpp>
7 #include <stan/math/prim/functor/apply_scalar_binary.hpp>
8 #include <boost/math/special_functions/factorials.hpp>
9
10 namespace stan {
11 namespace math {
12
13 /**
14 * Return the falling factorial function evaluated
15 * at the inputs.
16 * Will throw for NaN x and for negative n
17 *
18 * @tparam T Type of x argument.
19 * @param x Argument.
20 * @param n Argument
21 * @return Result of falling factorial function.
22 * @throw std::domain_error if x is NaN
23 * @throw std::domain_error if n is negative
24 *
25 \f[
26 \mbox{falling\_factorial}(x, n) =
27 \begin{cases}
28 \textrm{error} & \mbox{if } x \leq 0\\
29 (x)_n & \mbox{if } x > 0 \textrm{ and } -\infty \leq n \leq \infty \\[6pt]
30 \textrm{NaN} & \mbox{if } x = \textrm{NaN or } n = \textrm{NaN}
31 \end{cases}
32 \f]
33
34 \f[
35 \frac{\partial\, \mbox{falling\_factorial}(x, n)}{\partial x} =
36 \begin{cases}
37 \textrm{error} & \mbox{if } x \leq 0\\
38 \frac{\partial\, (x)_n}{\partial x} & \mbox{if } x > 0 \textrm{ and }
39 -\infty \leq n \leq \infty \\[6pt] \textrm{NaN} & \mbox{if } x = \textrm{NaN or
40 } n = \textrm{NaN} \end{cases} \f]
41
42 \f[
43 \frac{\partial\, \mbox{falling\_factorial}(x, n)}{\partial n} =
44 \begin{cases}
45 \textrm{error} & \mbox{if } x \leq 0\\
46 \frac{\partial\, (x)_n}{\partial n} & \mbox{if } x > 0 \textrm{ and }
47 -\infty \leq n \leq \infty \\[6pt] \textrm{NaN} & \mbox{if } x = \textrm{NaN or
48 } n = \textrm{NaN} \end{cases} \f]
49
50 \f[
51 (x)_n=\frac{\Gamma(x+1)}{\Gamma(x-n+1)}
52 \f]
53
54 \f[
55 \frac{\partial \, (x)_n}{\partial x} = (x)_n\Psi(x+1)
56 \f]
57
58 \f[
59 \frac{\partial \, (x)_n}{\partial n} = -(x)_n\Psi(n+1)
60 \f]
61 *
62 */
63 template <typename T, require_arithmetic_t<T>* = nullptr>
falling_factorial(const T & x,int n)64 inline return_type_t<T> falling_factorial(const T& x, int n) {
65 constexpr const char* function = "falling_factorial";
66 check_not_nan(function, "first argument", x);
67 check_nonnegative(function, "second argument", n);
68 return boost::math::falling_factorial(x, n, boost_policy_t<>());
69 }
70
71 /**
72 * Enables the vectorised application of the falling factorial function, when
73 * the first and/or second arguments are containers.
74 *
75 * @tparam T1 type of first input
76 * @tparam T2 type of second input
77 * @param a First input
78 * @param b Second input
79 * @return Falling factorial function applied to the two inputs.
80 */
81 template <typename T1, typename T2, require_any_container_t<T1, T2>* = nullptr,
82 require_all_not_var_matrix_t<T1, T2>* = nullptr>
falling_factorial(const T1 & a,const T2 & b)83 inline auto falling_factorial(const T1& a, const T2& b) {
84 return apply_scalar_binary(a, b, [&](const auto& c, const auto& d) {
85 return falling_factorial(c, d);
86 });
87 }
88
89 } // namespace math
90 } // namespace stan
91
92 #endif
93