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