Decoders
==========================

Decoders are search strategies for traversing the search space which is spanned by the predictors.
Decoders are specified using the ``--decoder`` argument.

Remember to set the ``--early_stopping`` option correctly depending on your predictor constellation. Decoders often improve
search efficiency when ``early_stopping=True`` (default) under the assumption that predictor scores are non-positive. Set
``early_stopping=False`` if your predictors can yield positive scores (e.g.\ the ``ngramc`` predictor).

Main decoders
----------------------

For a more detailed description of the decoders, search for the name of the decoder in the :ref:`decoder-modules-label` section.

* **greedy**: Greedy decoding (similar to beam=1) 
* **beam**: Beam search like in Bahdanau et al, 2015 .
* **combibeam**: Beam search which applies ``--combination_scheme`` at each time step.
* **dfs**: Depth-first search. This should be used for exact decoding or the complete enumeration of the search space. 
  but it cannot be used if the search space is too large (like for unrestricted NMT) as it performs exhaustive search. 
* **astar**: A* search. The heuristic function is configured using the ``--heuristics`` option. 

Experimental decoders
------------------------

Experimental decoders are less frequently used search strategies for special cases.

* **sepbeam**: Associates predictors with hypos in beam search and applies only one predictor instead of all for hypo expansion.
* **syncbeam**: Beam search which compares after consuming a special synchronization symbol instead of after each iteration.
* **fstbeam**: Beam search which compares hypotheses when they share the same state ID in an FST instead of after each iteration.
* **syntaxbeam**: Beam search which ensures diversity amongst terminal symbol histories.
* **mbrbeam**: Diversity encouraging beam search which maximizes the expected BLEU.
* **multisegbeam**: Beam search with multiple segmentations. 
* **lenbeam**: Beam search varaint that generates EOS extensions at each time step.
* **restarting**: Like DFS but with better admissible pruning behavior. 
* **simpledfs**: Very fast DFS implementation for complete enumeration with a single predictor.
* **simplelendfs**: Variant of simpledfs with length constraints.
* **bucket**: Works best for bag problems. Maintains buckets for each hypo length and extends a hypo in a bucket by one before selecting the next bucket.
* **flip**: This decoder works only for bag problems. It traverses the search space by switching two words in the hypothesis. Do not use bow predictor.
* **predlimitbeam**: Beam search variant with explicit limits on the culmulative predictor scores at each node expansion.
* **bigramgreedy**: Works best for bag problems. Collects bigram statistics and constructs hypos to score by greedily selecting high scoring bigrams. Do not use bow predictor with this search strategy.

.. _decoder-modules-label:

Decoder modules
-------------------

Module contents
****************************************

.. automodule:: cam.sgnmt.decoding
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:


cam.sgnmt.decoding.astar module
****************************************

.. automodule:: cam.sgnmt.decoding.astar
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.beam module
****************************************

.. automodule:: cam.sgnmt.decoding.beam
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.bigramgreedy module
****************************************

.. automodule:: cam.sgnmt.decoding.bigramgreedy
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.bucket module
****************************************

.. automodule:: cam.sgnmt.decoding.bucket
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.combibeam module
****************************************

.. automodule:: cam.sgnmt.decoding.combibeam
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.core module
****************************************

.. automodule:: cam.sgnmt.decoding.core
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.dfs module
****************************************

.. automodule:: cam.sgnmt.decoding.dfs
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.fstbeam module
****************************************

.. automodule:: cam.sgnmt.decoding.fstbeam
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.flip module
****************************************

.. automodule:: cam.sgnmt.decoding.flip
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.greedy module
****************************************

.. automodule:: cam.sgnmt.decoding.greedy
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.heuristics module
****************************************

.. automodule:: cam.sgnmt.decoding.heuristics
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.lenbeam module
****************************************

.. automodule:: cam.sgnmt.decoding.lenbeam
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.mbrbeam module
****************************************

.. automodule:: cam.sgnmt.decoding.mbrbeam
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.multisegbeam module
****************************************

.. automodule:: cam.sgnmt.decoding.multisegbeam
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.predlimitbeam module
****************************************

.. automodule:: cam.sgnmt.decoding.predlimitbeam
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.restarting module
****************************************

.. automodule:: cam.sgnmt.decoding.restarting
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.sepbeam module
****************************************

.. automodule:: cam.sgnmt.decoding.sepbeam
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.syncbeam module
****************************************

.. automodule:: cam.sgnmt.decoding.syncbeam
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex:

cam.sgnmt.decoding.syntaxbeam module
****************************************

.. automodule:: cam.sgnmt.decoding.syntaxbeam
    :members:
    :undoc-members:
    :show-inheritance:
    :noindex: