CMAC.h
Go to the documentation of this file.
1 /*!
2  *
3  *
4  * \brief -
5  *
6  * \author O. Krause
7  * \date 2010-01-01
8  *
9  *
10  * \par Copyright 1995-2017 Shark Development Team
11  *
12  * <BR><HR>
13  * This file is part of Shark.
14  * <http://shark-ml.org/>
15  *
16  * Shark is free software: you can redistribute it and/or modify
17  * it under the terms of the GNU Lesser General Public License as published
18  * by the Free Software Foundation, either version 3 of the License, or
19  * (at your option) any later version.
20  *
21  * Shark is distributed in the hope that it will be useful,
22  * but WITHOUT ANY WARRANTY; without even the implied warranty of
23  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
24  * GNU Lesser General Public License for more details.
25  *
26  * You should have received a copy of the GNU Lesser General Public License
27  * along with Shark. If not, see <http://www.gnu.org/licenses/>.
28  *
29  */
30 
31 #ifndef SHARK_ML_MODEL_CMAC_H
32 #define SHARK_ML_MODEL_CMAC_H
33 
34 #include <shark/Core/DLLSupport.h>
35 #include <shark/Models/AbstractModel.h>
36 #include <shark/Core/Random.h>
37 #include <vector>
38 
39 namespace shark{
40 
41 //!
42 //! \brief The CMACMap class represents a linear combination of piecewise constant functions
43 //!
44 //! when a point is fed into the CMAC, it is first mapped into a vector of binary features.
45 //! For this purpose the inputspace is divided into several tilings. Every tiling produces a bitstring where an element
46 //! is 1 if the point lies inside the tile, 0 otherwise. The concatenation of all tilings forms the feature vector which is then fed
47 //! into a linear function.
48 //! Usually the CMAC is only good for low dimensional input data since the size of the featurevector grows exponentially with the
49 //! number of dimensions.
50 //!
51 class CMACMap :public AbstractModel<RealVector,RealVector>{
52 protected:
53  ///offset of the position of every tiling
54  RealMatrix m_offset;
55 
56  ///coordinate offset for every dimension in the Array
57  std::vector<std::size_t> m_dimOffset;
58 
59  ///lower bound and tileWidth for every Dimension
60  RealMatrix m_tileBounds;
61 
62  ///number of tilings
63  std::size_t m_tilings;
64  std::size_t m_parametersPerTiling;
65 
66  Shape m_inputShape;
67  std::size_t m_inputSize;
68  Shape m_outputShape;
69 
70  ///The parameters of the model
71  RealVector m_parameters;
72 
73  ///calculates the index in the parameter vector for the activated feature in the tiling
74  SHARK_EXPORT_SYMBOL std::size_t getArrayIndexForTiling(std::size_t indexOfTiling,RealVector const& point)const;
75  ///returns an index in the parameter array for each activated feature
76  SHARK_EXPORT_SYMBOL std::vector<std::size_t> getIndizes(blas::matrix_row<const RealMatrix> const& point)const;
77 public:
78  ///\brief construct the CMAC
79  SHARK_EXPORT_SYMBOL CMACMap();
80 
81  /// \brief From INameable: return the class name.
82  std::string name() const
83  { return "CMACMap"; }
84 
85  ///\brief initializes the structure of the cmac. it uses the same lower and upper bound for every input dimension. default is [0,1]
86  ///
87  ///\param inputs Shape of the input dimensions
88  ///\param outputs Shape of the input dimensions
89  ///\param numberOfTilings number of Tilings to be created
90  ///\param numberOfTiles amount of tiles per dimension
91  ///\param lower lower bound of input values
92  ///\param upper upper bound of input values
93  ///\param randomTiles flag specifying whether distance between tiles is regular or randomized
94  SHARK_EXPORT_SYMBOL void setStructure(Shape const& inputs, Shape const& outputs, std::size_t numberOfTilings, std::size_t numberOfTiles, double lower = 0., double upper = 1.,bool randomTiles = false);
95 
96  ///\brief initializes the structure of the cmac
97  ///
98  ///\param inputs number of input dimensions
99  ///\param outputs number of output dimensions
100  ///\param numberOfTilings number of Tilings to be created
101  ///\param numberOfTiles amount of tiles per dimension
102  ///\param bounds lower and upper bounts for every input dimension. every row consists of (lower,upper)
103  ///\param randomTiles flag specifying whether distance between tiles is regular or randomized
104  SHARK_EXPORT_SYMBOL void setStructure(Shape const& inputs, Shape const& outputs, std::size_t numberOfTilings, std::size_t numberOfTiles, RealMatrix const& bounds,bool randomTiles = false);
105 
106  ///\brief Returns the expected shape of the input
107  Shape inputShape() const{
108  return m_inputShape;
109  }
110  ///\brief Returns the shape of the output
111  Shape outputShape() const{
112  return m_outputShape;
113  }
114 
115  virtual RealVector parameterVector()const{
116  return m_parameters;
117  }
118  virtual void setParameterVector(RealVector const& newParameters){
119  SIZE_CHECK(numberOfParameters() == newParameters.size());
120  m_parameters=newParameters;
121  }
122  virtual std::size_t numberOfParameters()const{
123  return m_parameters.size();
124  }
125 
126  boost::shared_ptr<State> createState()const{
127  return boost::shared_ptr<State>(new EmptyState());
128  }
129 
130  using AbstractModel<RealVector,RealVector>::eval;
131  SHARK_EXPORT_SYMBOL void eval(const RealMatrix& patterns,RealMatrix& outputs)const;
132  void eval(const RealMatrix& patterns,RealMatrix& outputs, State& state)const{
133  eval(patterns,outputs);
134  }
135  SHARK_EXPORT_SYMBOL void weightedParameterDerivative(
136  RealMatrix const& pattern,
137  BatchOutputType const& outputs,
138  RealMatrix const& coefficients,
139  State const& state,
140  RealVector& gradient)const;
141 
142  /// From ISerializable, reads a model from an archive
143  SHARK_EXPORT_SYMBOL void read( InArchive & archive );
144 
145  /// From ISerializable, writes a model to an archive
146  SHARK_EXPORT_SYMBOL void write( OutArchive & archive ) const;
147 };
148 
149 
150 }
151 #endif