// nnet3/nnet-example.h
  
  // Copyright 2012-2015  Johns Hopkins University (author: Daniel Povey)
  //                2014  Vimal Manohar
  
  // See ../../COPYING for clarification regarding multiple authors
  //
  // Licensed under the Apache License, Version 2.0 (the "License");
  // you may not use this file except in compliance with the License.
  // You may obtain a copy of the License at
  //
  //  http://www.apache.org/licenses/LICENSE-2.0
  //
  // THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  // KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED
  // WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,
  // MERCHANTABLITY OR NON-INFRINGEMENT.
  // See the Apache 2 License for the specific language governing permissions and
  // limitations under the License.
  
  #ifndef KALDI_NNET3_NNET_EXAMPLE_H_
  #define KALDI_NNET3_NNET_EXAMPLE_H_
  
  #include "nnet3/nnet-nnet.h"
  #include "hmm/posterior.h"
  #include "util/table-types.h"
  #include "hmm/posterior.h"
  
  namespace kaldi {
  namespace nnet3 {
  
  
  struct NnetIo {
    /// the name of the input in the neural net; in simple setups it
    /// will just be "input".
    std::string name;
  
    /// "indexes" is a vector the same length as features.NumRows(), explaining
    /// the meaning of each row of the "features" matrix.  Note: the "n" values
    /// in the indexes will always be zero in individual examples, but in general
    /// nonzero after we aggregate the examples into the minibatch level.
    std::vector<Index> indexes;
  
    /// The features or labels.  GeneralMatrix may contain either a CompressedMatrix,
    /// a Matrix, or SparseMatrix (a SparseMatrix would be the natural format for posteriors).
    GeneralMatrix features;
  
    /// This constructor creates NnetIo with name "name", indexes with n=0, x=0,
    /// and t values ranging from t_begin to 
    /// (t_begin + t_stride * feats.NumRows() - 1) with a stride t_stride, and
    /// the provided features.  t_begin should be the frame that feats.Row(0)
    /// represents.
    NnetIo(const std::string &name,
           int32 t_begin, const MatrixBase<BaseFloat> &feats,
           int32 t_stride = 1);
  
    /// This constructor creates NnetIo with name "name", indexes with n=0, x=0,
    /// and t values ranging from t_begin to 
    /// (t_begin + t_stride * feats.NumRows() - 1) with a stride t_stride, and
    /// the provided features.  t_begin should be the frame that the first row
    /// of 'feats' represents.
    NnetIo(const std::string &name,
           int32 t_begin, const GeneralMatrix &feats,
           int32 t_stride = 1);
  
    /// This constructor sets "name" to the provided string, sets "indexes" with
    /// n=0, x=0, and t from t_begin to (t_begin + t_stride * labels.size() - 1)
    /// with a stride t_stride, and the labels
    /// as provided.  t_begin should be the frame to which labels[0] corresponds.
    NnetIo(const std::string &name,
           int32 dim,
           int32 t_begin,
           const Posterior &labels,
           int32 t_stride = 1);
  
    void Swap(NnetIo *other);
  
    NnetIo() { }
  
    // Use default copy constructor and assignment operators.
    void Write(std::ostream &os, bool binary) const;
  
    void Read(std::istream &is, bool binary);
  
    // this comparison is not very efficient, especially for sparse supervision.
    // It's only used in testing code.
    bool operator == (const NnetIo &other) const;
  };
  
  
  /// This hashing object hashes just the structural aspects of the NnetIo object
  /// (name, indexes, feature dimension) without looking at the value of features.
  /// It will be used in combining egs into batches of all similar structure.
  struct NnetIoStructureHasher {
    size_t operator () (const NnetIo &a) const noexcept;
  };
  /// This comparison object compares just the structural aspects of the NnetIo
  /// object (name, indexes, feature dimension) without looking at the value of
  /// features.  It will be used in combining egs into batches of all similar
  /// structure.
  struct NnetIoStructureCompare {
    bool operator () (const NnetIo &a,
                      const NnetIo &b) const;
  };
  
  
  
  /// NnetExample is the input data and corresponding label (or labels) for one or
  /// more frames of input, used for standard cross-entropy training of neural
  /// nets (and possibly for other objective functions).
  struct NnetExample {
  
    /// "io" contains the input and output.  In principle there can be multiple
    /// types of both input and output, with different names.  The order is
    /// irrelevant.
    std::vector<NnetIo> io;
  
    void Write(std::ostream &os, bool binary) const;
    void Read(std::istream &is, bool binary);
  
    NnetExample() { }
  
    NnetExample(const NnetExample &other): io(other.io) { }
  
    void Swap(NnetExample *other) { io.swap(other->io); }
  
    /// Compresses any (input) features that are not sparse.
    void Compress();
  
    /// Caution: this operator == is not very efficient.  It's only used in
    /// testing code.
    bool operator == (const NnetExample &other) const { return io == other.io; }
  };
  
  
  /// This hashing object hashes just the structural aspects of the NnetExample
  /// without looking at the value of the features.  It will be used in combining
  /// egs into batches of all similar structure.  Note: the hash value is
  /// sensitive to the order in which the NnetIo elements (input and outputs)
  /// appear, even though the merging is capable of dealing with
  /// differently-ordered inputs and outputs (e.g.  "input" appearing before
  /// vs. after "ivector" or "output").  We don't think anyone would ever have to
  /// deal with differently-ordered, but otherwise identical, egs in practice so
  /// we don't bother making the hashing function independent of this order.
  struct NnetExampleStructureHasher {
    size_t operator () (const NnetExample &eg) const noexcept;
    // We also provide a version of this that works from pointers.
    size_t operator () (const NnetExample *eg) const noexcept {
      return (*this)(*eg);
    }
  };
  
  
  /// This comparator object compares just the structural aspects of the
  /// NnetExample without looking at the value of the features.  Like
  /// NnetExampleStructureHasher, it is sensitive to the order in which the
  /// differently-named NnetIo elements appear.  This hashing object will be used
  /// in combining egs into batches of all similar structure.
  struct NnetExampleStructureCompare {
    bool operator () (const NnetExample &a,
                      const NnetExample &b) const;
    // We also provide a version of this that works from pointers.
    bool operator () (const NnetExample *a,
                      const NnetExample *b) const { return (*this)(*a, *b); }
  
  };
  
  
  
  typedef TableWriter<KaldiObjectHolder<NnetExample > > NnetExampleWriter;
  typedef SequentialTableReader<KaldiObjectHolder<NnetExample > > SequentialNnetExampleReader;
  typedef RandomAccessTableReader<KaldiObjectHolder<NnetExample > > RandomAccessNnetExampleReader;
  
  } // namespace nnet3
  } // namespace kaldi
  
  #endif // KALDI_NNET3_NNET_EXAMPLE_H_