1 #ifndef STAN_MATH_PRIM_FUN_UNIT_VECTOR_CONSTRAIN_HPP
2 #define STAN_MATH_PRIM_FUN_UNIT_VECTOR_CONSTRAIN_HPP
3 
4 #include <stan/math/prim/err.hpp>
5 #include <stan/math/prim/fun/Eigen.hpp>
6 #include <stan/math/prim/fun/dot_self.hpp>
7 #include <stan/math/prim/fun/sqrt.hpp>
8 #include <cmath>
9 
10 namespace stan {
11 namespace math {
12 
13 /**
14  * Return the unit length vector corresponding to the free vector y.
15  *
16  * See <a
17  * href="https://en.wikipedia.org/wiki/N-sphere#Generating_random_points">the
18  * Wikipedia page on generating random points on an N-sphere</a>.
19  *
20  * @tparam T type inheriting from `EigenBase` that does not have an fvar
21  *  scalar type.
22  * @param y vector of K unrestricted variables
23  * @return Unit length vector of dimension K
24  */
25 template <typename T, require_eigen_col_vector_t<T>* = nullptr,
26           require_not_vt_autodiff<T>* = nullptr>
unit_vector_constrain(const T & y)27 inline plain_type_t<T> unit_vector_constrain(const T& y) {
28   using std::sqrt;
29   check_nonzero_size("unit_vector_constrain", "y", y);
30   auto&& y_ref = to_ref(y);
31   value_type_t<T> SN = dot_self(y_ref);
32   check_positive_finite("unit_vector_constrain", "norm", SN);
33   return y_ref.array() / sqrt(SN);
34 }
35 
36 /**
37  * Return the unit length vector corresponding to the free vector y.
38  * See https://en.wikipedia.org/wiki/N-sphere#Generating_random_points
39  *
40  * @tparam T1 type inheriting from `EigenBase` that does not have an fvar
41  *  scalar type.
42  *
43  * @param y vector of K unrestricted variables
44  * @return Unit length vector of dimension K
45  * @param lp Log probability reference to increment.
46  */
47 template <typename T1, typename T2, require_eigen_col_vector_t<T1>* = nullptr,
48           require_all_not_vt_autodiff<T1, T2>* = nullptr>
unit_vector_constrain(const T1 & y,T2 & lp)49 inline plain_type_t<T1> unit_vector_constrain(const T1& y, T2& lp) {
50   using std::sqrt;
51   check_nonzero_size("unit_vector_constrain", "y", y);
52   auto&& y_ref = to_ref(y);
53   value_type_t<T1> SN = dot_self(y_ref);
54   check_positive_finite("unit_vector_constrain", "norm", SN);
55   lp -= 0.5 * SN;
56   return y_ref.array() / sqrt(SN);
57 }
58 
59 /**
60  * Return the unit length vector corresponding to the free vector y. If the
61  * `Jacobian` parameter is `true`, the log density accumulator is incremented
62  * with the log absolute Jacobian determinant of the transform.  All of the
63  * transforms are specified with their Jacobians in the *Stan Reference Manual*
64  * chapter Constraint Transforms.
65  *
66  * @tparam Jacobian if `true`, increment log density accumulator with log
67  * absolute Jacobian determinant of constraining transform
68  * @tparam T A type inheriting from `Eigen::DenseBase` or a `var_value` with
69  *  inner type inheriting from `Eigen::DenseBase` with compile time dynamic rows
70  *  and 1 column
71  * @param y vector of K unrestricted variables
72  * @param[in, out] lp log density accumulator
73  * @return Unit length vector of dimension K
74  */
75 template <bool Jacobian, typename T, require_not_std_vector_t<T>* = nullptr>
unit_vector_constrain(const T & y,return_type_t<T> & lp)76 inline auto unit_vector_constrain(const T& y, return_type_t<T>& lp) {
77   if (Jacobian) {
78     return unit_vector_constrain(y, lp);
79   } else {
80     return unit_vector_constrain(y);
81   }
82 }
83 
84 /**
85  * Return the unit length vector corresponding to the free vector y. If the
86  * `Jacobian` parameter is `true`, the log density accumulator is incremented
87  * with the log absolute Jacobian determinant of the transform.  All of the
88  * transforms are specified with their Jacobians in the *Stan Reference Manual*
89  * chapter Constraint Transforms.
90  *
91  * @tparam Jacobian if `true`, increment log density accumulator with log
92  * absolute Jacobian determinant of constraining transform
93  * @tparam T A standard vector with inner type inheriting from
94  * `Eigen::DenseBase` or a `var_value` with inner type inheriting from
95  * `Eigen::DenseBase` with compile time dynamic rows and 1 column
96  * @param y vector of K unrestricted variables
97  * @param[in, out] lp log density accumulator
98  * @return Unit length vector of dimension K
99  */
100 template <bool Jacobian, typename T, require_std_vector_t<T>* = nullptr>
unit_vector_constrain(const T & y,return_type_t<T> & lp)101 inline auto unit_vector_constrain(const T& y, return_type_t<T>& lp) {
102   return apply_vector_unary<T>::apply(
103       y, [&lp](auto&& v) { return unit_vector_constrain<Jacobian>(v, lp); });
104 }
105 
106 }  // namespace math
107 }  // namespace stan
108 
109 #endif
110