class_docstr: This module uses the "forward-backward" algorithm to compute
  the log-likelihood of its inputs assuming a conditional random field model.
  
  See, e.g. http://www.cs.columbia.edu/~mcollins/fb.pdf
  
  # Parameters
  
  num_tags : `int`, required
      The number of tags.
  constraints : `List[Tuple[int, int]]`, optional (default = `None`)
      An optional list of allowed transitions (from_tag_id, to_tag_id).
      These are applied to `viterbi_tags()` but do not affect `forward()`.
      These should be derived from `allowed_transitions` so that the
      start and end transitions are handled correctly for your tag type.
  include_start_end_transitions : `bool`, optional (default = `True`)
      Whether to include the start and end transition parameters.
class_docstr_tok: ["This","module","uses","the","``","forward-backward","''","algorithm","to","compute","the","log-likelihood","of","its","inputs","assuming","a","conditional","random","field","model",".","See",",","e.g",".","http",":","\/\/www.cs.columbia.edu\/~mcollins\/fb.pdf","#","Parameters","num_tags",":","`","int","`",",","required","The","number","of","tags",".","constraints",":","`","List","[","Tuple","[","int",",","int","]","]","`",",","optional","(","default","=","`","None","`",")","An","optional","list","of","allowed","transitions","(","from_tag_id",",","to_tag_id",")",".","These","are","applied","to","`","viterbi_tags","(",")","`","but","do","not","affect","`","forward","(",")","`",".","These","should","be","derived","from","`","allowed_transitions","`","so","that","the","start","and","end","transitions","are","handled","correctly","for","your","tag","type",".","include_start_end_transitions",":","`","bool","`",",","optional","(","default","=","`","True","`",")","Whether","to","include","the","start","and","end","transition","parameters","."]
docstr: Computes the (batch_size,) denominator term $Z(x)$, per example, for the log-likelihood
  
  This is the sum of the likelihoods across all possible state sequences.
  
  Args:
      logits (torch.Tensor): a (batch_size, sequence_length num_tags) tensor of
          unnormalized log-probabilities
      transitions (torch.Tensor): a (batch_size, num_tags, num_tags) tensor of transition scores
      mask (torch.BoolTensor): a (batch_size, sequence_length) tensor of masking flags
  
  Returns:
      torch.Tensor: (batch_size,) denominator term $Z(x)$, per example, for the log-likelihood
docstr_tok: ["Computes","the","(","batch_size",",",")","denominator","term","$","Z","(","x",")","$",",","per","example",",","for","the","log-likelihood","This","is","the","sum","of","the","likelihoods","across","all","possible","state","sequences",".","Args",":","logits","(","torch.Tensor",")",":","a","(","batch_size",",","sequence_length","num_tags",")","tensor","of","unnormalized","log-probabilities","transitions","(","torch.Tensor",")",":","a","(","batch_size",",","num_tags",",","num_tags",")","tensor","of","transition","scores","mask","(","torch.BoolTensor",")",":","a","(","batch_size",",","sequence_length",")","tensor","of","masking","flags","Returns",":","torch.Tensor",":","(","batch_size",",",")","denominator","term","$","Z","(","x",")","$",",","per","example",",","for","the","log-likelihood"]
code: def _input_likelihood(
      self,
      logits: torch.Tensor,
      transitions: torch.Tensor,
      mask: torch.BoolTensor,
  ) -> torch.Tensor:
      """Computes the (batch_size,) denominator term $Z(x)$, per example, for the log-likelihood
  
      This is the sum of the likelihoods across all possible state sequences.
  
      Args:
          logits (torch.Tensor): a (batch_size, sequence_length num_tags) tensor of
              unnormalized log-probabilities
          transitions (torch.Tensor): a (batch_size, num_tags, num_tags) tensor of transition scores
          mask (torch.BoolTensor): a (batch_size, sequence_length) tensor of masking flags
  
      Returns:
          torch.Tensor: (batch_size,) denominator term $Z(x)$, per example, for the log-likelihood
      """
      batch_size, sequence_length, num_tags = logits.size()
  
      # Transpose batch size and sequence dimensions
      mask = mask.transpose(0, 1).contiguous()
      logits = logits.transpose(0, 1).contiguous()
  
      # Initial alpha is the (batch_size, num_tags) tensor of likelihoods combining the
      # transitions to the initial states and the logits for the first timestep.
      if self.include_start_end_transitions:
          alpha = self.start_transitions.view(1, num_tags) + logits[0]
      else:
          alpha = logits[0]
  
      # For each i we compute logits for the transitions from timestep i-1 to timestep i.
      # We do so in a (batch_size, num_tags, num_tags) tensor where the axes are
      # (instance, current_tag, next_tag)
      for i in range(1, sequence_length):
          # The emit scores are for time i ("next_tag") so we broadcast along the current_tag axis.
          emit_scores = logits[i].view(batch_size, 1, num_tags)
          # Transition scores are (current_tag, next_tag) so we broadcast along the instance axis.
          transition_scores = transitions.view(1, num_tags, num_tags)
          # Alpha is for the current_tag, so we broadcast along the next_tag axis.
          broadcast_alpha = alpha.view(batch_size, num_tags, 1)
  
          # Add all the scores together and logexp over the current_tag axis.
          inner = broadcast_alpha + emit_scores + transition_scores
  
          # In valid positions (mask == True) we want to take the logsumexp over the current_tag dimension
          # of `inner`. Otherwise (mask == False) we want to retain the previous alpha.
          alpha = util.logsumexp(inner, 1) * mask[i].view(
              batch_size, 1
          ) + alpha * (~mask[i]).view(batch_size, 1)
  
      # Every sequence needs to end with a transition to the stop_tag.
      if self.include_start_end_transitions:
          stops = alpha + self.end_transitions.view(1, num_tags)
      else:
          stops = alpha
  
      # Finally we log_sum_exp along the num_tags dim, result is (batch_size,)
      return util.logsumexp(stops)
  
file_path: allennlp/allennlp/modules/conditional_random_field/conditional_random_field.py
imports: from typing import List, Tuple, Dict, Union
  import torch
  from allennlp.common.checks import ConfigurationError
  import allennlp.nn.util
label_desc: Use image node_id 3 for calling the ConditionalRandomField obj's underlying member method code with example usage: obj._input_likelihood(logits, transitions, mask) and returns: util