src/Core/Random.h

0001 // This file is part of Eigen, a lightweight C++ template library
0002 // for linear algebra.
0003 //
0004 // Copyright (C) 2008 Gael Guennebaud <gael.guennebaud@inria.fr>
0005 //
0006 // This Source Code Form is subject to the terms of the Mozilla
0007 // Public License v. 2.0. If a copy of the MPL was not distributed
0008 // with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
0009
0010 #ifndef EIGEN_RANDOM_H
0011 #define EIGEN_RANDOM_H
0012
0013 namespace Eigen {
0014
0015 namespace internal {
0016
0017 template<typename Scalar> struct scalar_random_op {
0018   EIGEN_EMPTY_STRUCT_CTOR(scalar_random_op)
0019   inline const Scalar operator() () const { return random<Scalar>(); }
0020 };
0021
0022 template<typename Scalar>
0023 struct functor_traits<scalar_random_op<Scalar> >
0024 { enum { Cost = 5 * NumTraits<Scalar>::MulCost, PacketAccess = false, IsRepeatable = false }; };
0025
0026 } // end namespace internal
0027
0028 /** \returns a random matrix expression
0029   *
0030   * Numbers are uniformly spread through their whole definition range for integer types,
0031   * and in the [-1:1] range for floating point scalar types.
0032   *
0033   * The parameters \a rows and \a cols are the number of rows and of columns of
0034   * the returned matrix. Must be compatible with this MatrixBase type.
0035   *
0036   * \not_reentrant
0037   *
0038   * This variant is meant to be used for dynamic-size matrix types. For fixed-size types,
0039   * it is redundant to pass \a rows and \a cols as arguments, so Random() should be used
0040   * instead.
0041   *
0042   *
0043   * Example: \include MatrixBase_random_int_int.cpp
0044   * Output: \verbinclude MatrixBase_random_int_int.out
0045   *
0046   * This expression has the "evaluate before nesting" flag so that it will be evaluated into
0047   * a temporary matrix whenever it is nested in a larger expression. This prevents unexpected
0048   * behavior with expressions involving random matrices.
0049   *
0050   * See DenseBase::NullaryExpr(Index, const CustomNullaryOp&) for an example using C++11 random generators.
0051   *
0052   * \sa DenseBase::setRandom(), DenseBase::Random(Index), DenseBase::Random()
0053   */
0054 template<typename Derived>
0055 inline const typename DenseBase<Derived>::RandomReturnType
0056 DenseBase<Derived>::Random(Index rows, Index cols)
0057 {
0058   return NullaryExpr(rows, cols, internal::scalar_random_op<Scalar>());
0059 }
0060
0061 /** \returns a random vector expression
0062   *
0063   * Numbers are uniformly spread through their whole definition range for integer types,
0064   * and in the [-1:1] range for floating point scalar types.
0065   *
0066   * The parameter \a size is the size of the returned vector.
0067   * Must be compatible with this MatrixBase type.
0068   *
0069   * \only_for_vectors
0070   * \not_reentrant
0071   *
0072   * This variant is meant to be used for dynamic-size vector types. For fixed-size types,
0073   * it is redundant to pass \a size as argument, so Random() should be used
0074   * instead.
0075   *
0076   * Example: \include MatrixBase_random_int.cpp
0077   * Output: \verbinclude MatrixBase_random_int.out
0078   *
0079   * This expression has the "evaluate before nesting" flag so that it will be evaluated into
0080   * a temporary vector whenever it is nested in a larger expression. This prevents unexpected
0081   * behavior with expressions involving random matrices.
0082   *
0083   * \sa DenseBase::setRandom(), DenseBase::Random(Index,Index), DenseBase::Random()
0084   */
0085 template<typename Derived>
0086 inline const typename DenseBase<Derived>::RandomReturnType
0087 DenseBase<Derived>::Random(Index size)
0088 {
0089   return NullaryExpr(size, internal::scalar_random_op<Scalar>());
0090 }
0091
0092 /** \returns a fixed-size random matrix or vector expression
0093   *
0094   * Numbers are uniformly spread through their whole definition range for integer types,
0095   * and in the [-1:1] range for floating point scalar types.
0096   *
0097   * This variant is only for fixed-size MatrixBase types. For dynamic-size types, you
0098   * need to use the variants taking size arguments.
0099   *
0100   * Example: \include MatrixBase_random.cpp
0101   * Output: \verbinclude MatrixBase_random.out
0102   *
0103   * This expression has the "evaluate before nesting" flag so that it will be evaluated into
0104   * a temporary matrix whenever it is nested in a larger expression. This prevents unexpected
0105   * behavior with expressions involving random matrices.
0106   *
0107   * \not_reentrant
0108   *
0109   * \sa DenseBase::setRandom(), DenseBase::Random(Index,Index), DenseBase::Random(Index)
0110   */
0111 template<typename Derived>
0112 inline const typename DenseBase<Derived>::RandomReturnType
0113 DenseBase<Derived>::Random()
0114 {
0115   return NullaryExpr(RowsAtCompileTime, ColsAtCompileTime, internal::scalar_random_op<Scalar>());
0116 }
0117
0118 /** Sets all coefficients in this expression to random values.
0119   *
0120   * Numbers are uniformly spread through their whole definition range for integer types,
0121   * and in the [-1:1] range for floating point scalar types.
0122   *
0123   * \not_reentrant
0124   *
0125   * Example: \include MatrixBase_setRandom.cpp
0126   * Output: \verbinclude MatrixBase_setRandom.out
0127   *
0128   * \sa class CwiseNullaryOp, setRandom(Index), setRandom(Index,Index)
0129   */
0130 template<typename Derived>
0131 EIGEN_DEVICE_FUNC inline Derived& DenseBase<Derived>::setRandom()
0132 {
0133   return *this = Random(rows(), cols());
0134 }
0135
0136 /** Resizes to the given \a newSize, and sets all coefficients in this expression to random values.
0137   *
0138   * Numbers are uniformly spread through their whole definition range for integer types,
0139   * and in the [-1:1] range for floating point scalar types.
0140   *
0141   * \only_for_vectors
0142   * \not_reentrant
0143   *
0144   * Example: \include Matrix_setRandom_int.cpp
0145   * Output: \verbinclude Matrix_setRandom_int.out
0146   *
0147   * \sa DenseBase::setRandom(), setRandom(Index,Index), class CwiseNullaryOp, DenseBase::Random()
0148   */
0149 template<typename Derived>
0150 EIGEN_STRONG_INLINE Derived&
0151 PlainObjectBase<Derived>::setRandom(Index newSize)
0152 {
0153   resize(newSize);
0154   return setRandom();
0155 }
0156
0157 /** Resizes to the given size, and sets all coefficients in this expression to random values.
0158   *
0159   * Numbers are uniformly spread through their whole definition range for integer types,
0160   * and in the [-1:1] range for floating point scalar types.
0161   *
0162   * \not_reentrant
0163   *
0164   * \param rows the new number of rows
0165   * \param cols the new number of columns
0166   *
0167   * Example: \include Matrix_setRandom_int_int.cpp
0168   * Output: \verbinclude Matrix_setRandom_int_int.out
0169   *
0170   * \sa DenseBase::setRandom(), setRandom(Index), class CwiseNullaryOp, DenseBase::Random()
0171   */
0172 template<typename Derived>
0173 EIGEN_STRONG_INLINE Derived&
0174 PlainObjectBase<Derived>::setRandom(Index rows, Index cols)
0175 {
0176   resize(rows, cols);
0177   return setRandom();
0178 }
0179
0180 /** Resizes to the given size, changing only the number of columns, and sets all
0181   * coefficients in this expression to random values. For the parameter of type
0182   * NoChange_t, just pass the special value \c NoChange.
0183   *
0184   * Numbers are uniformly spread through their whole definition range for integer types,
0185   * and in the [-1:1] range for floating point scalar types.
0186   *
0187   * \not_reentrant
0188   *
0189   * \sa DenseBase::setRandom(), setRandom(Index), setRandom(Index, NoChange_t), class CwiseNullaryOp, DenseBase::Random()
0190   */
0191 template<typename Derived>
0192 EIGEN_STRONG_INLINE Derived&
0193 PlainObjectBase<Derived>::setRandom(NoChange_t, Index cols)
0194 {
0195   return setRandom(rows(), cols);
0196 }
0197
0198 /** Resizes to the given size, changing only the number of rows, and sets all
0199   * coefficients in this expression to random values. For the parameter of type
0200   * NoChange_t, just pass the special value \c NoChange.
0201   *
0202   * Numbers are uniformly spread through their whole definition range for integer types,
0203   * and in the [-1:1] range for floating point scalar types.
0204   *
0205   * \not_reentrant
0206   *
0207   * \sa DenseBase::setRandom(), setRandom(Index), setRandom(NoChange_t, Index), class CwiseNullaryOp, DenseBase::Random()
0208   */
0209 template<typename Derived>
0210 EIGEN_STRONG_INLINE Derived&
0211 PlainObjectBase<Derived>::setRandom(Index rows, NoChange_t)
0212 {
0213   return setRandom(rows, cols());
0214 }
0215
0216 } // end namespace Eigen
0217
0218 #endif // EIGEN_RANDOM_H