// doc/graph_recipe_train.dox
  
  
  // Copyright 2009-2011 Microsoft Corporation
  
  // 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.
  
  namespace kaldi {
  
  /**
  
   \page graph_recipe_train Decoding-graph creation recipe (training time)
  
   Our graph creation recipe during training time is simpler than during test time,
   mainly because we do not need the disambiguation symbols.  We will assume
   that you have already read the \ref graph_recipe_train "test-time
   version" of this recipe.
  
   In training time we use the same HCLG formalism as in test time, except that
   G consists of just a linear acceptor corresponding to the training transcript
   (of course, this setup is easy to extend to cases where there is uncertainty
   in the transcripts).
  
   \section graph_recipe_command Command-line programs involved in decoding-graph creation
  
  Here we explain what happens at the script level in a typical training script;
  below we will dig into what happens inside the programs.  Suppose we have built
  a tree and model.  The following command creates an archive (c.f. \ref
  io_sec_tables) that contains the graph HCLG corresponding to each of the
  training transcripts.
  \verbatim
  compile-train-graphs $dir/tree $dir/1.mdl data/L.fst ark:data/train.tra \
     ark:$dir/graphs.fsts
  \endverbatim
  The input file train.tra is a file containing integer versions of the training
  transcripts, e.g. a typical line might look like:
  \verbatim
  011c0201 110906 96419 79214 110906 52026 55810 82385 79214 51250 106907 111943 99519 79220
  \endverbatim
  (the first token is the utterance id).  The output of this program is the archive
  graphs.fsts; it contains an FST (in binary form) for each utterance id in train.tra.
  The FSTs in this archive correspond to HCLG, except
  that there are no transition probabilities (by default, compile-train-graphs
  has --self-loop-scale=0 and --transition-scale=0).  This is because these graphs
  will be used for multiple stages of training and the transition probabilities will
  change, so we add them in later.  But the FSTs on the archive will have probabilities
  that arise from silence probabilities (these probabilities are encoded into L.fst),
  and if we were using pronunciation probabilities these would be present too.
  
  A command that reads these archives and
  decodes the training data, producing state-level alignments
  (c.f. \ref hmm_alignment) is as follows; we will briefly review this command, although
  our main focus on this page is the graph creation itself.
  \verbatim
  gmm-align-compiled \
    --transition-scale=1.0 --acoustic-scale=0.1 --self-loop-scale=0.1 \
    --beam=8 --retry-beam=40 \
     $dir/$x.mdl ark:$dir/graphs.fsts \
     "ark:add-deltas --print-args=false scp:data/train.scp ark:- |" \
     ark:$dir/cur.ali
  \endverbatim
  The first three argument are probability scales (c.f. \ref hmm_scale).  The
  transition-scale and self-loop-scale options are there because this program adds
  the transition probabilities to the graph before decoding (c.f. 
  \ref hmm_graph_add_transition_probs).  The next options are the beams; we use an
  initial beam, and then if alignment fails to reach the end state we use another
  beam.  Since we apply a scale of 0.1 the acoustics, we would have to multiply
  these beams by 10 to get figures comparable to acoustic likelihoods.  The program
  requires the model; \$x.mdl would expand to 1.mdl or 2.mdl, according to the
  iteration.  It reads the graphs from the archive (graphs.fsts).  The argument in
  quotes is evaluated as a pipe (minus the "ark:" and "|"), and is interpreted as
  an archive indexed by utterance id, containing features.  The output goes to
  cur.ali, and if written in text form it would look like the .tra file described
  above, although the integers now correspond not to word-ids but transition-ids
  (c.f. \ref transition_model_identifiers).
  
  We note that these two stages (graph creation and decoding) can be done
  by a single command-line program, gmm-align, which compiles the graphs as they
  are needed.  Because graph creation takes a fairly significant amount of time, 
  any time the graphs will be needed more than once we write them to disk.
  
  
  \section graph_recipe_internal Internals of graph creation
  
   The graph creation done in training time, whether from the program
   compile-train-graphs or from gmm-align, is done by the same code:
   the class TrainingGraphCompiler.  Its behaviour when compiling graphs
   one by one is as follows:
  
   In initialization:
     - Add the subsequential loop (c.f. \ref graph_c) to the lexicon L.fst, make sure it is 
      sorted on its output label, and store it.
  
   When compiling a transcript, it does the following:
     - Make a linear acceptor corresponding to the word sequence (G)
     - Compose it (using TableCompose) with the lexicon to get an FST (LG) with
       phones on the input and words on the output; this FST contains
       pronunciation alternatives and optional silence.
     - Create a new context FST "C" that will be expanded on demand.
     - Compose C with LG to get CLG; the composition uses a special Matcher
       that expands C on demand.
     - Call the function GetHTransducer to get the transducer H (this covers
       just the context-dependent phones that were seen).
     - Compose H with CLG to get HCLG (this will have transition-ids on the
       input and words on the output, but no self-loops)
     - Determinize HCLG with the function DeterminizeStarInLog; this
       casts to the log semiring (to preserve stochasticity) before determinizing
       with epsilon removal.
     - Minimize HCLG with MinimizeEncoded (this does transducer minimization without
       weight-pushing, to preserve stochasticity).
     - Add self-loops.
  
   The TrainingGraphCompiler class has a function CompileGraphs() that will combine
   a number of graphs in a batch.  This is used in the tool compile-train-graphs
   to speed up the graph compilation.  The main reason it helps to do it in a batch
   is that when we create the H transducer, we only have to process each seen
   context-window once, even if it was used in many of the instances of CLG.
  
   The reason that we can determinize without first adding disambiguation symbols
   is that HCLG in this case is functional (since any accepted input-label sequence is 
   transuced to the same string) and acyclic; any acyclic FST has the twins property,
   and any functional FST with the twins property is determinizable.
  
  
  */
  
  
  }