1// This file is part of Eigen, a lightweight C++ template library
2// for linear algebra.
3//
4// Copyright (C) 2008 Gael Guennebaud <gael.guennebaud@inria.fr>
5//
6// This Source Code Form is subject to the terms of the Mozilla
7// Public License v. 2.0. If a copy of the MPL was not distributed
8// with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
9
10#ifndef EIGEN_RANDOM_H
11#define EIGEN_RANDOM_H
12
13namespace Eigen {
14
15namespace internal {
16
17template<typename Scalar> struct scalar_random_op {
18 EIGEN_EMPTY_STRUCT_CTOR(scalar_random_op)
19 inline const Scalar operator() () const { return random<Scalar>(); }
20};
21
22template<typename Scalar>
23struct functor_traits<scalar_random_op<Scalar> >
24{ enum { Cost = 5 * NumTraits<Scalar>::MulCost, PacketAccess = false, IsRepeatable = false }; };
25
26} // end namespace internal
27
28/** \returns a random matrix expression
29 *
30 * Numbers are uniformly spread through their whole definition range for integer types,
31 * and in the [-1:1] range for floating point scalar types.
32 *
33 * The parameters \a rows and \a cols are the number of rows and of columns of
34 * the returned matrix. Must be compatible with this MatrixBase type.
35 *
36 * \not_reentrant
37 *
38 * This variant is meant to be used for dynamic-size matrix types. For fixed-size types,
39 * it is redundant to pass \a rows and \a cols as arguments, so Random() should be used
40 * instead.
41 *
42 *
43 * Example: \include MatrixBase_random_int_int.cpp
44 * Output: \verbinclude MatrixBase_random_int_int.out
45 *
46 * This expression has the "evaluate before nesting" flag so that it will be evaluated into
47 * a temporary matrix whenever it is nested in a larger expression. This prevents unexpected
48 * behavior with expressions involving random matrices.
49 *
50 * See DenseBase::NullaryExpr(Index, const CustomNullaryOp&) for an example using C++11 random generators.
51 *
52 * \sa DenseBase::setRandom(), DenseBase::Random(Index), DenseBase::Random()
53 */
54template<typename Derived>
55inline const typename DenseBase<Derived>::RandomReturnType
56DenseBase<Derived>::Random(Index rows, Index cols)
57{
58 return NullaryExpr(rows, cols, internal::scalar_random_op<Scalar>());
59}
60
61/** \returns a random vector expression
62 *
63 * Numbers are uniformly spread through their whole definition range for integer types,
64 * and in the [-1:1] range for floating point scalar types.
65 *
66 * The parameter \a size is the size of the returned vector.
67 * Must be compatible with this MatrixBase type.
68 *
69 * \only_for_vectors
70 * \not_reentrant
71 *
72 * This variant is meant to be used for dynamic-size vector types. For fixed-size types,
73 * it is redundant to pass \a size as argument, so Random() should be used
74 * instead.
75 *
76 * Example: \include MatrixBase_random_int.cpp
77 * Output: \verbinclude MatrixBase_random_int.out
78 *
79 * This expression has the "evaluate before nesting" flag so that it will be evaluated into
80 * a temporary vector whenever it is nested in a larger expression. This prevents unexpected
81 * behavior with expressions involving random matrices.
82 *
83 * \sa DenseBase::setRandom(), DenseBase::Random(Index,Index), DenseBase::Random()
84 */
85template<typename Derived>
86inline const typename DenseBase<Derived>::RandomReturnType
87DenseBase<Derived>::Random(Index size)
88{
89 return NullaryExpr(size, internal::scalar_random_op<Scalar>());
90}
91
92/** \returns a fixed-size random matrix or vector expression
93 *
94 * Numbers are uniformly spread through their whole definition range for integer types,
95 * and in the [-1:1] range for floating point scalar types.
96 *
97 * This variant is only for fixed-size MatrixBase types. For dynamic-size types, you
98 * need to use the variants taking size arguments.
99 *
100 * Example: \include MatrixBase_random.cpp
101 * Output: \verbinclude MatrixBase_random.out
102 *
103 * This expression has the "evaluate before nesting" flag so that it will be evaluated into
104 * a temporary matrix whenever it is nested in a larger expression. This prevents unexpected
105 * behavior with expressions involving random matrices.
106 *
107 * \not_reentrant
108 *
109 * \sa DenseBase::setRandom(), DenseBase::Random(Index,Index), DenseBase::Random(Index)
110 */
111template<typename Derived>
112inline const typename DenseBase<Derived>::RandomReturnType
113DenseBase<Derived>::Random()
114{
115 return NullaryExpr(RowsAtCompileTime, ColsAtCompileTime, internal::scalar_random_op<Scalar>());
116}
117
118/** Sets all coefficients in this expression to random values.
119 *
120 * Numbers are uniformly spread through their whole definition range for integer types,
121 * and in the [-1:1] range for floating point scalar types.
122 *
123 * \not_reentrant
124 *
125 * Example: \include MatrixBase_setRandom.cpp
126 * Output: \verbinclude MatrixBase_setRandom.out
127 *
128 * \sa class CwiseNullaryOp, setRandom(Index), setRandom(Index,Index)
129 */
130template<typename Derived>
131inline Derived& DenseBase<Derived>::setRandom()
132{
133 return *this = Random(rows(), cols());
134}
135
136/** Resizes to the given \a newSize, and sets all coefficients in this expression to random values.
137 *
138 * Numbers are uniformly spread through their whole definition range for integer types,
139 * and in the [-1:1] range for floating point scalar types.
140 *
141 * \only_for_vectors
142 * \not_reentrant
143 *
144 * Example: \include Matrix_setRandom_int.cpp
145 * Output: \verbinclude Matrix_setRandom_int.out
146 *
147 * \sa DenseBase::setRandom(), setRandom(Index,Index), class CwiseNullaryOp, DenseBase::Random()
148 */
149template<typename Derived>
150EIGEN_STRONG_INLINE Derived&
151PlainObjectBase<Derived>::setRandom(Index newSize)
152{
153 resize(newSize);
154 return setRandom();
155}
156
157/** Resizes to the given size, and sets all coefficients in this expression to random values.
158 *
159 * Numbers are uniformly spread through their whole definition range for integer types,
160 * and in the [-1:1] range for floating point scalar types.
161 *
162 * \not_reentrant
163 *
164 * \param rows the new number of rows
165 * \param cols the new number of columns
166 *
167 * Example: \include Matrix_setRandom_int_int.cpp
168 * Output: \verbinclude Matrix_setRandom_int_int.out
169 *
170 * \sa DenseBase::setRandom(), setRandom(Index), class CwiseNullaryOp, DenseBase::Random()
171 */
172template<typename Derived>
173EIGEN_STRONG_INLINE Derived&
174PlainObjectBase<Derived>::setRandom(Index rows, Index cols)
175{
176 resize(rows, cols);
177 return setRandom();
178}
179
180} // end namespace Eigen
181
182#endif // EIGEN_RANDOM_H
183