Robot Simulator of the Robotics Group for Self-Organization of Control: inspectable.h Source File

# inspectable.h

Go to the documentation of this file.

    00001 /***************************************************************************
    00002  *   Copyright (C) 2005-2011 LpzRobots development team                    *
    00003  *    Georg Martius  <georg dot martius at web dot de>                     *
    00004  *    Frank Guettler <guettler at informatik dot uni-leipzig dot de        *
    00005  *    Frank Hesse    <frank at nld dot ds dot mpg dot de>                  *
    00006  *    Ralf Der       <ralfder at mis dot mpg dot de>                       *
    00007  *                                                                         *
    00008  *   This program is free software; you can redistribute it and/or modify  *
    00009  *   it under the terms of the GNU General Public License as published by  *
    00010  *   the Free Software Foundation; either version 2 of the License, or     *
    00011  *   (at your option) any later version.                                   *
    00012  *                                                                         *
    00013  *   This program is distributed in the hope that it will be useful,       *
    00014  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
    00015  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
    00016  *   GNU General Public License for more details.                          *
    00017  *                                                                         *
    00018  *   You should have received a copy of the GNU General Public License     *
    00019  *   along with this program; if not, write to the                         *
    00020  *   Free Software Foundation, Inc.,                                       *
    00021  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
    00022  *                                                                         *
    00023  ***************************************************************************/
    00024 #ifndef __INSPECTABLE_H
    00025 #define __INSPECTABLE_H
    00026
    00027
    00028 #include <list>
    00029 #include <map>
    00030 #include <utility>
    00031 #include <string>
    00032 #include "stl_adds.h"
    00033
    00034 #include <iostream>
    00035
    00036 namespace matrix {
    00037   class Matrix;
    00038 }
    00039
    00040 /**
    00041  * Interface for inspectable objects.
    00042  * That means that one can read out some internal parameters indentified by string keys
    00043  *
    00044  * TODO: support for lead through of params (e.g. getInternalParams())
    00045  * for all children inspectables. For this use a instance-wide switch (useChildren)
    00046  * as a member variable to enable this feature when desired.
    00047 */
    00048 class Inspectable {
    00049 public:
    00050
    00051   // TYPEDEFS BEGIN
    00052
    00053   typedef std::string iparamkey;
    00054   typedef double iparamval;
    00055   typedef std::pair<iparamkey,iparamval const*> iparampair;
    00056
    00057   // the bool says whether  only 4x4AndDiag is used
    00058   typedef std::pair<iparamkey,std::pair< const matrix::Matrix*, bool > > imatrixpair;
    00059   typedef std::list<iparamkey> iparamkeylist;
    00060   typedef std::list<std::string> infoLinesList;
    00061   typedef std::list<iparamval> iparamvallist;
    00062   typedef std::list<iparamval const *> iparamvalptrlist;
    00063   typedef std::list<iparampair> iparampairlist;
    00064   typedef std::list<imatrixpair> imatrixpairlist;
    00065
    00066   // the network stucture export will be discontinued soon
    00067   typedef struct ILayer{
    00068     ILayer(const std::string& vectorname, const std::string& biasname,
    00069            int dimension, int rank, const std::string& layername)
    00070       : vectorname(vectorname), biasname(biasname),
    00071          dimension(dimension), rank(rank), layername(layername) {}
    00072     std::string vectorname;  //< prefix of the internal parameter vector e.g. "v"
    00073     std::string biasname;    ///< prefix of the internal parameter vector used as bias for the neurons e.g. "h"
    00074     int dimension;      ///< length of the vector (number of units)
    00075     int rank;           ///< rank of the layer (0 are input layers)
    00076     std::string layername;   ///< name of the layer as displayed by the visualiser
    00077   }ILayer;
    00078
    00079   typedef struct IConnection{
    00080     IConnection(const std::string& matrixname, const std::string& vector1, const std::string& vector2)
    00081       : matrixname(matrixname), vector1(vector1), vector2(vector2) {}
    00082     std::string matrixname; ///< matrix name is the prefix of the internal parameter matrix e.g. "A"
    00083     std::string vector1;    ///< vectorname of input layer
    00084     std::string vector2;    ///< vectorname of output layer
    00085   }IConnection;
    00086
    00087   typedef std::list<ILayer> ilayerlist;
    00088   typedef std::list<IConnection> iconnectionlist;
    00089
    00090   /// nice predicate function for finding a Layer with its vectorname
    00091   struct matchName : public std::unary_function<ILayer, bool> {
    00092     matchName(std::string name) : name(name) {}
    00093     std::string name;
    00094     bool operator()(ILayer l) { return l.vectorname == name; }
    00095   };
    00096
    00097   typedef std::list<const Inspectable*> inspectableList;
    00098
    00099
    00100
    00101   /// TYPEDEFS END
    00102
    00103
    00104   Inspectable(const iparamkey& name = "");
    00105
    00106
    00107   virtual ~Inspectable();
    00108
    00109
    00110   /** The list of the names of all internal parameters given by getInternalParams().
    00111       The naming convention is "v[i]" for vectors
    00112        and "A[i][j]" for matrices, where i, j start at 0.
    00113       @return: list of keys
    00114    */
    00115   virtual iparamkeylist getInternalParamNames() const;
    00116
    00117
    00118 /** @return: list of values
    00119    */
    00120   virtual iparamvallist getInternalParams() const;
    00121
    00122   // should be protected, but it does not work
    00123   /**
    00124    * be careful: matrices will be ignored
    00125    * @return list of values (pointer)
    00126    */
    00127   virtual iparamvalptrlist getInternalParamsPtr() const;
    00128
    00129   /** Specifies which parameter vector forms a structural layer (in terms of a neural network)
    00130       The ordering is important. The first entry is the input layer and so on.
    00131       @return: list of layer names with dimension
    00132
    00133    */
    00134   virtual ilayerlist getStructuralLayers() const;
    00135
    00136
    00137   /** Specifies which parameter matrix forms a connection between layers (in terms of a neural network)
    00138       The orderning is not important.
    00139       @return: list of layer names with dimension
    00140    */
    00141   virtual iconnectionlist getStructuralConnections() const;
    00142
    00143
    00144   /**
    00145    * This is the new style for adding inspectable values. Just call this
    00146    * function for each parameter and you are done.
    00147    * registers a single value
    00148    * @param key the name of the inspectable, shown e.g. in guilogger (no spaces allowed)
    00149    * @param val the address of the value to inspect
    00150    * @param descr description string to be exported (using infolines)
    00151    */
    00152   virtual void addInspectableValue(const iparamkey& key, iparamval const * val,
    00153                                    const std::string& descr = std::string());
    00154
    00155
    00156   /**
    00157    * This is the new style for adding inspectable values. Just call this
    00158    * function for each parameter and you are done.
    00159    * Inspects elements of the given matrix or vector (automatic detection)
    00160    * For Matrixes Either all or only the values given by
    00161    * store4x4AndDiagonalFieldNames(Matrix& m,string& matrixName);
    00162    * are used.
    00163    * @param key the name of the matrix, shown e.g. in guilogger (no spaces allowed)
    00164    * @param m the address of the matrix to inspect
    00165    * @param only4x4AndDiag of true only 4x4 matrix plus the diagonal is used
    00166    * @param descr description string to be exported
    00167    *              (for the entire matrix with key_) (using infolines)
    00168    * @note that you can change the structure of the matrix while
    00169    * being inspected, but no after the getInternalParameterNames is called!
    00170    */
    00171   virtual void addInspectableMatrix(const iparamkey& key, const matrix::Matrix* m,
    00172                                     bool only4x4AndDiag=true,
    00173                                     const std::string& descr = std::string());
    00174
    00175   /**
    00176    * adds a description for the given parameter using info-lines
    00177    * The line will start (appart from the #I) with a D for description
    00178    * followed by the key end then followed by the string.
    00179    * @param key parameter name (no spaces allowed)
    00180    * @param descr descriptive string (no newlines allowed)
    00181    */
    00182   virtual void addInspectableDescription(const iparamkey& key, const std::string& descr);
    00183
    00184
    00185   /**
    00186    * Adds an info line to this inspectable instance. All infolines are plotted
    00187    * by the PlotOptionEngine and therefore appear e.g. in the logfile.
    00188    * They are leaded by a #I. If you have your own identifiers, just begin with
    00189    * your one (e.g. N for number of
    00190    * NOTE: You must not add e.g. carriage return, all this is handled by the
    00191    * PlotOptionsEngine itself.
    00192    * If you like to add multiple lines, call this function a lot more or
    00193    * use instead addInfoLines.
    00194    * @param infoLine the line (as string) to be added
    00195    */
    00196   virtual void addInfoLine(std::string infoLine);
    00197
    00198   /**
    00199    * Adds a bunch of infolines with addInfoLine to this inspectable instance.
    00200    * Every infoline is separated by an carriage return automatically, done
    00201    * by the PlotOptionsEngine.
    00202    * @param infoLineList the infoLines to be added as a string list.
    00203    */
    00204   virtual void addInfoLines(std::list<std::string> infoLineList);
    00205
    00206   /**
    00207    * Removes all infolines from this inspectable instance.
    00208    * This is useful if you have new infoLines and would like to restart
    00209    * the PlotOptionEngine.
    00210    */
    00211   virtual void removeInfoLines();
    00212
    00213   /**
    00214    * Returns all infolines added to this inspectable instance.
    00215    * This function is called by the PlotOptionEngine.
    00216    * @return all added infolines.
    00217    */
    00218   virtual const infoLinesList& getInfoLines() const;
    00219
    00220   /**
    00221    * Adds an inspectable as a child object.
    00222    * @param insp the instance to add
    00223    */
    00224   virtual void addInspectable(Inspectable* insp);
    00225
    00226   /**
    00227    * Removes an inspectable as a child object.
    00228    * @param insp the instance to remove
    00229    */
    00230   virtual void removeInspectable(Inspectable* insp);
    00231
    00232
    00233   /// set the name of the inspectable
    00234   virtual void setNameOfInspectable(const iparamkey& name);
    00235
    00236   /// return the name of the inspectable, getName() would conflict with Configurable::getName() too often
    00237   virtual const iparamkey getNameOfInspectable() const;
    00238
    00239   /**
    00240    * Returns the list containing all inspectable children.
    00241    */
    00242   virtual const inspectableList& getInspectables() const;
    00243
    00244   /* added when needed
    00245   virtual void removeInspectable(const Inspectable* insp);
    00246
    00247   virtual void removeAllInspectables();
    00248   */
    00249
    00250 protected:
    00251   iparamkey name;
    00252
    00253   iparampairlist mapOfValues;
    00254   imatrixpairlist mapOfMatrices;
    00255
    00256   infoLinesList infoLineStringList;
    00257
    00258 private:
    00259   inspectableList listOfInspectableChildren;
    00260   bool printParentName;
    00261   Inspectable* parent;
    00262
    00263
    00264 };
    00265
    00266 #endif