name: StackSearch
synopsis:

>     g++ [flags ...] file ... -l /isip/tools/lib/$ISIP_BINARY/lib_search.a

>     #include <StackSearch.h>

>     StackSearch();
>     StackSearch(const StackSearch& copy_search);
>     boolean setNumLevels(long num_levels);
>     SearchLevel& getSearchLevel(long level)
>     boolean decode(FrontEnd& fe, long num_frames = ALL_FRAMES);
>     boolean getHypotheses(String& output_hyp, long level_a, float& total_score,
>                           long& num_frames, DoubleLinkedList& trace_path);

quick start:

>     // configure FrontEnd
>     //
>     FrontEnd fe;

>     Sof front_end_sof;
>     front_end_sof.open(L"front_end.sof");
>     fe.read(front_end_sof, front_end_sof.first(fe.name()));
>     front_end_sof.close();

>     // configure StackSearch
>     //
>     StackSearch search_engine;
>     long num_levels = 3;
>     search_engine.setNumLevels(num_levels);

>     // read models
>     //
>     Sof model_sof;
>     model_sof.open(L"models.sof");

>     for (long curr_level = 0; curr_level < num_levels; curr_level++) {
>       SearchLevel& level = search_engine.getSearchLevel(curr_level);
>       level.load(model_sof);
>     }
>     model_sof.close();

>     // process the sentence
>     //
>     Filename speech_file(L"speech_file.raw");
>     fe.open(speech_file);
>     search_engine.decode(fe);
>     fe.close();

>     // get the best hypothesis
>     //
>     String best_hypothesis;
>     float score = 0;
>     long num_frames = 0;
>     search_engine.getHypotheses(best_hypothesis, score, num_frames);

description:
StackSearch class implements a hierarchical, asynchronous, stack search engine.
The basic premise behind this is as follows:

- The search space is hierarchical in that each level has nodes and each node is either:
  - composed of a sub-graph + probability evaluation
  - composed of probability evaluation.
- At each level you will be able to do the following:
  - beam prune
  - instance prune
  - generate context-dependent scoring models on the fly including cross-symbol models
  - specify whether search information is to be maintained - otherwise we can prune away redundant information. For instance, once a word is completed, it is no longer necessary to maintain the sub-word units that correspond to that word.
  - turn on/off sub-level evaluation
- Each graph position will be capable of the following:
  - generate a probability of being in that graph position given the input stream. For acoustic models, this will involve direct evaluation of the data stream. For levels like language models, this will not involve manipulation of the data stream at all. Any level can access the data stream as it will be passed from the highest level all the way down to the lowest via pointer reference.
  - store the overlapping paths in the sub-graph as a "lexical" tree.
  - use N-symbol models related to the possible entries on that level
- We will revolve around the concept of a "trace" where the trace moves through the graph and keeps track of the paths/scores through the search space

dependencies:

- FrontEnd
- VectorFloat
- Hypothesis
- Trace
- SearchLevel
- SearchNode

public constants:

- define the class name:

      static const String CLASS_NAME = L"StackSearch";

- define i/o related constants:

      static const String StackSearch::DEF_PARAM = L"stack_search";

      static const String StackSearch::PARAM_DECODING_MODE = L"decoding_mode";

      static const String StackSearch::PARAM_SCORE_NORMALIZATION = L"score_normalization";

      static const String StackSearch::PARAM_STACK_LEVEL = L"stack_level";

      static const String StackSearch::PARAM_MAX_MIN_FILENAME = L"max_min_file";

      static const String StackSearch::PARAM_SIL_DUR_PENALTY = L"sil_dur_penalty";

- other important constants:

      enum EVALUATION_MODE { FRAME_EVAL = 0, SEGMENT_EVAL, DEF_EVALUATION_MODE = FRAME_EVAL };

      enum DECODING_MODE { GLOBAL_STACK = 0, MULTI_STACK, VITERBI, DEF_DECODING_MODE = GLOBAL_STACK };

      enum SCORE_NORMALIZATION { NONE = 0, DURATION, NUM_OF_PHONES, DEF_SCORE_NORMALIZATION = NONE };

      static const NameMap EVALUATION_MODE_MAP;

      static const NameMap DECODING_MODE_MAP;

      static const NameMap SCORE_NORMALIZATION_MAP;

      static const long START_FRAME = -1;

      static const long ALL_FRAMES = -1;

- default values and arguments:

      static const long MAX_NUM_LEVELS = 3;

      static const long MAX_NUM_FRAMES = 1000;

      static const long DEF_N_BEST = 1;

      static const long DEF_STACK_LEVEL = 0;

      static const long DEF_GLOB_STACK_CAPACITY = 100000;

      static const float DEF_SIL_DUR_PENALTY = 0;

      static const long ALL_LEVELS = -1;

error codes:

- error code indicating a general error:

      static const long ERR = 90800;

      static const long ERR = 90801;

protected data:

- declare type shortcut

      typedef GraphVertex GVSnode;

- declare evaluation and decoding methods

      EVALUATION_MODE evaluation_mode_d;

      DECODING_MODE decoding_mode_d;

- declare score normalization methods

      SCORE_NORMALIZATION score_normalization_d;

      boolean user_requested_no_score_normalization_d;

- declare feature vectors:

      VectorFloat features_d;

- declare svm features

      Vector<Vector<VectorFloat>> svm_features_d;

- declare number of frames:

      Long num_frames_d;

- declare number of best word hypotheses to find:

      Long n_best_d;

- level where to put the stack

      Long stack_level_d;

- declare current frame in the search

      Long current_frame_d;

- declare the search levels, sub-graphs are maintained at each SearchLevel:

      HierarchicalDigraph* h_digraph_d;

- declare vector that contains the location (index) of the context mapping:

      Vector<Long> context_mapping_d;

- declare maximal trace scores at each frame for all levels

      MatrixFloat max_frame_scores_d;

- maximal trace scores for stacks

      VectorFloat max_stack_scores_d;

- declare statistical model scores

      MatrixFloat stat_model_scores_d;

- declare vector that maps states to model indices

      Vector<Long> stat_model_mapping_d;

- declare lists to keep track of traces during the search:

      Vector<DoubleLinkedList<Trace> > trace_lists_d;

- declare a list of valid end hypothesis:

      PriorityQueue<Trace> valid_hyps_d;

      DoubleLinkedList<Trace> term_hyps_d;

- declare vector of hypothesis stacks (each stack contains word level hypothesess of one frame)

      Vector<HashTable<Trace, Stack<Hypothesis> > > stacks_d;

      PriorityQueue<Hypothesis> global_stack_d;

      float best_valid_score_d;

      Float sil_dur_penalty_d;

      VectorLong num_eval_d;

      VectorLong num_avoided_eval_d;

      VectorLong num_traces_gen_d;

      VectorLong num_traces_vit_prun_d;

      VectorLong num_traces_beam_prun_d;

      Filename max_min_filename_d;

      HistoryPool history_pool_d;

      ContextPool context_pool_d;

- declare the memory manager:

      static MemoryManager mgr_d;

- declare the debug level:

      static Integral::DEBUG debug_level_d;

required public methods:

- static methods:

      static const String& name();

      static boolean diagnose(Integral::DEBUG debug_level);

- debug methods:

      boolean debug(const unichar* message) const;

      static boolean setDebug(Integral::DEBUG debug_level;

- destructor/constructor(s):

      ~StackSearch();

      StackSearch();

      StackSearch(const StackSearch& arg);

- assign methods:

      boolean assign(const StackSearch& arg);

- i/o methods:

      long sofSize() const;

      boolean read(Sof& sof, long tag, const String& name = CLASS_NAME);

      boolean write(Sof& sof, long tag, const String& name = CLASS_NAME) const;

      boolean readData(Sof& sof, const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false);

      boolean writeData(Sof& sof, const String& pname = DEF_PARAM) const;

- equality methods:

      boolean eq(const StackSearch& arg) const;

- memory management methods:

      static void* operator new(size_t size);

      static void* operator new[](size_t size);

      static void operator delete(void* ptr);

      static void operator delete[](void* ptr);

      static boolean setGrowSize(long grow_size);

      boolean clear(Integral::CMODE ctype = Integral::DEF_CMODE);

class-specific public methods:

- declare search mode/level methods:

      boolean setNumLevels(long num_levels);

      long getNumLevels() const;

      SearchLevel& getSearchLevel(long level);

      Vector<SearchLevel>& getSearchLevels();

      HierarchicalDigraph& getHDigraph();

      boolean setHDigraph(HierarchicalDigraph& h_digraph);

- declare decoding methods:

      boolean initSizes(long total_num_frames);

      boolean initializeLinearDecoder();

      boolean decode(Vector<FrontEnd>& vector_fe, long num_frames = ALL_FRAMES);

      boolean decode(Vector& features, long num_frames = ALL_FRAMES);

- declare search hypotheses methods:

      boolean getHypotheses(String& output_hyp, long level, double& total_score, long& num_frames, DoubleLinkedList<Trace>& trace_path, String* word_hyp = NULL);

      )boolean setStackLevel(long level);

      )long getStackLevel();

      )SCORE_NORMALIZATION getScoreNormalization();

      )boolean setScoreNormalization(SCORE_NORMALIZATION arg);

      )boolean setSilDurPenalty(float arg);

      )float getSilDurPenalty();

private methods:

- search initialization methods

      boolean clearTraceStorage();

      boolean clearSearchNodesTraceLists();

      boolean clearValidHypsTrace();

      boolean clearTermHypsTrace();

- search traversal methods:

      boolean traverseTraceLevels();

      boolean pathsRemainTrace();

- trace propagation methods

      boolean propagateTraces(DoubleLinkedList* pickup_list = NULL, long pickup_level=-1);

      boolean propagateTracesDown(long level_num_a, DoubleLinkedList* pickup_list = NULL, long pickup_level = -1);

      boolean propagateTracesUp(long level_num_a, DoubleLinkedList* pickup_list = NULL, long pickup_level = -1);

      boolean evaluateTraceModels(DoubleLinkedList* pickup_list = NULL, long pickup_level = -1);

- trace bookkeeping methods

      long getActiveTraces(long search_level = ALL_LEVELS);

- debugging methods

      boolean printNewPath(Trace* new_trace, Trace* old_trace);

      boolean printDeletedPath(Trace* new_trace, Trace* old_trace);

- pruning method

      boolean beamPruneTrace(long level_num);

- context related methods

      boolean generateRightContexts(DoubleLinkedList& context_list, Context* initial_context, long depth);

      boolean generateInitialTraces();

- method extending hypothesis by one word

      boolean extend(DoubleLinkedList& hlist, long start_frame);

- methods manipulating trace lists

      boolean getTraces(DoubleLinkedList& trace_list, long level);

      boolean setTraces(DoubleLinkedList& trace_list, long level);

- core decoding method

      boolean decode();

- method to change current frame

      boolean setFrame(long frame);

      boolean determineEvaluationMode();

      boolean normalizeFeatures();

      boolean transformSkipModels();

      boolean addSkipArcs(GraphVertex* vertex_a, const long level_ind_a);

examples:

- none

notes:

- none