cavity_message.h

#ifndef __message_h__
#define __message_h__

#include <algorithm>
#include <numeric>
#include <random>
#include <fstream>
#include <sstream>
#include <iterator>
#include <vector>
#include <string>

#include <magnetization.h>
#include <errors.h>
#include <params.hpp>

#ifdef DEBUG

  #include <cassert>

#endif

#include <utils.h>


/**
* @class Cavity_Message
* @brief Abstract type used to store weights and messages of rFBP algorithm.
*
* @details The initial messages can be loaded from file and the resulting ones
* can be saved to file using the appropriated member functions.
*
* @tparam Mag magnetization chosen for training
*
*/
template < class Mag >
class Cavity_Message
{

public:

  // public member variables

  long int        M;          ///< Input sample size
  long int        N;          ///< Input layers size
  long int        K;          ///< Number of hidden layers
  long int        seed;       ///< Random seed
  MagVec3 < Mag > weights;    ///< uw in the paper nomeclature
  MagVec2 < Mag > m_star_j;   ///< ux in the paper nomeclature
  MagVec2 < Mag > m_j_star;   ///< mw in the paper nomeclature
  MagVec2 < Mag > m_in;       ///< mτ1 in the paper nomeclature
  MagVec2 < Mag > m_no;       ///< Uτ1 in the paper nomeclature
  MagVec2 < Mag > m_ni;       ///< uτ1 in the paper nomeclature
  MagVec < Mag >  m_on;       ///< mτ2 in the paper nomeclature

  // Constructors

  /**
  * @brief Default constructor.
  *
  */
  Cavity_Message ();

  /**
  * @brief Load messages from file.
  *
  * @details The input file must have a very precise format.
  * - For the binary format we require a file with the following instructions:
  *
  *   * N (long int)
  *   * M (long int)
  *   * K (long int)
  *   * m_star_j (K * N, double)
  *   * m_j_star (K * N, double)
  *   * m_in (M * K, double)
  *   * weights (M * K * N, double)
  *   * m_no (M * K, double)
  *   * m_on (M, double)
  *   * m_ni (M * K, double)
  *
  *   All the double values are converted into the respective Mag format.
  *
  * - For the ascii version the required file must have the following format:
  *
  *   \code{.csv}
  *
  *   fmt: plain
  *   N,M,K: `N` `M` `K`
  *
  *   \endcode
  *
  *   where `N` represents the numerical value of the N parameter.
  *   This header file is followed by ravel version of the required arrays
  *   (m_star_j, m_j_star, m_in, weights, m_no, m_on, m_ni) one per each line, divided
  *   by white spaces (or `\t`).
  *
  * @note A valid file can be generated by the function `save_messages`.
  *
  * @param filename Input filename
  * @param bin switch between binary/ascii files (default = false)
  *
  */
  Cavity_Message (const std :: string & filename, const bool & bin);

  /**
  * @brief Generate random messages.
  *
  * @details The cavity_messages' arrays are generated according a uniform distribution.
  * The [0, 1] range is converted using the formula
  *
  * \code{.cpp}
  * x * (2. * dist() - 1.)
  * \endcode
  *
  * where `dist` represents the uniform random generator.
  * All the values are converted to Mag types.
  *
  * @param m number of samples
  * @param n number of probes
  * @param k number of hidden layers
  * @param x initial value
  * @param start random seed
  *
  */
  Cavity_Message (const long int & m, const long int & n, const long int & k, const double & x, const int & start);

  // Copy Operator and Copy Constructor

  /**
  * @brief Copy constructor.
  *
  * @details The copy constructor provides a deep copy of the object, i.e. all the
  * arrays are copied and not moved.
  *
  * @param m Cavity_Message object
  *
  */
  Cavity_Message (const Cavity_Message < Mag > & m);

  /**
  * @brief Copy operator.
  *
  * @details The operator performs a deep copy of the object and if there are buffers
  * already allocated, the operatore deletes them and then re-allocates an appropriated
  * portion of memory.
  *
  * @param m Cavity_Message object
  *
  */
  Cavity_Message < Mag > & operator = (const Cavity_Message < Mag > & m);

  // Destructor

  /**
  * @brief Destructor.
  *
  * @details Completely delete the object and release the memory of the arrays.
  *
  */
  ~Cavity_Message ();

  // Methods

  /**
  * @brief Return weights matrix.
  *
  * @details The weights are converted from double to long int, using the sign of each
  * element, i.e.
  *
  * \code{.cpp}
  * 1L - 2L * signbit(x)
  *\endcode
  *
  * This function can be used as getter member for the weight matrix used to predict
  * new patterns.
  *
  * @note The weight matrix used in the prediction is the `m_j_star` array!
  *
  */
  long int ** get_weights ();

  /**
  * @brief Save weight matrix to file.
  *
  * @details Save the weight matrix to file and the related training parameters.
  * This function provides a valid file for the function `read_weights` in ascii format.
  * Only the weight matrix, i.e. `m_j_star`, is saved, since it is the only informative
  * array for the prediction of new patterns.
  * The training parameters are saved as header in the file.
  *
  * @param filename output filename
  * @param parameters Params object
  *
  * @return The binirized format of the weight matrix, ready for the prediction.
  *
  */
  void save_weights (const std :: string & filename, Params < Mag > & parameters);

  /**
  * @brief Save weight matrix to file.
  *
  * @details Save **only** the weight matrix to file.
  * This function provides a valid file for the function `read_weights` in binary format.
  * Only the weight matrix, i.e. `m_j_star`, is saved, since it is the only informative
  * array for the prediction of new patterns.
  * The weight values are saved as double values and thus before use them to predict new values,
  * it is necessary to apply the "get_weights" function.
  *
  * @param filename output filename
  *
  */
  void save_weights (const std :: string & filename);

  /**
  * @brief Load weight matrix from file.
  *
  * @details This function read the weight matrix from a binary or ascii file.
  * Its usage is in relation to the `save_weights` member function.
  *
  * @param filename input filename
  * @param bin switch between binary/ascii fmt
  *
  */
  void read_weights (const std :: string & filename, const bool & bin);

  /**
  * @brief Save all the messages to file.
  *
  * @details This function dump the complete object to file with also
  * the parameters used for the training section, according
  * to the format required by the constructor.
  *
  * @param filename output filename
  * @param parameters Params object
  *
  */
  void save_messages (const std :: string & filename, Params < Mag > & parameters);

  /**
  * @brief Save all the messages to a **binary** file.
  *
  * @details This function dump the complete object to **binary** file, according
  * to the format required by the constructor.
  *
  * @param filename output filename
  *
  */
  void save_messages (const std :: string & filename);

};

#endif // __message_h__