class_docstr: Provider for unrolling codebooks pattern.
  This pattern provider enables to represent the codebook flattened completely or only to some extend
  while also specifying a given delay between the flattened codebooks representation, allowing to
  unroll the codebooks in the sequence.
  
  Example:
      1. Flattening of the codebooks.
      By default, the pattern provider will fully flatten the codebooks such as flattening=range(n_q),
      taking n_q = 3 and timesteps = 4:
      [[1, 2, 3, 4],
       [1, 2, 3, 4],
       [1, 2, 3, 4]]
      will result into:
      [[S, S, 1, S, S, 2, S, S, 3, S, S, 4],
       [S, 1, S, S, 2, S, S, 3, S, S, 4, S],
       [1, S, S, 2, S, S, 3, S, S, 4, S, S]]
      2. Partial flattening of the codebooks. The ``flattening`` parameter allows to specify the inner step
      for each of the codebook, allowing to define which codebook to flatten (or keep in parallel), for example
      taking n_q = 3, timesteps = 4 and flattening = [0, 1, 1]:
      [[1, 2, 3, 4],
       [1, 2, 3, 4],
       [1, 2, 3, 4]]
      will result into:
      [[S, 1, S, S, 2, S, S, 3, S, S, 4, S],
       [S, 1, S, S, 2, S, S, 3, S, S, 4, S],
       [1, S, S, 2, S, S, 3, S, S, 4, S, S]]
      3. Flattening with delay. The ``delay`` parameter allows to further unroll the sequence of codebooks
      allowing to specify the delay per codebook. Note that the delay between codebooks flattened to the
      same inner timestep should be coherent. For example, taking n_q = 3, timesteps = 4, flattening = [0, 1, 1]
      and delays = [0, 3, 3]:
      [[1, 2, 3, 4],
       [1, 2, 3, 4],
       [1, 2, 3, 4]]
      will result into:
      [[S, S, S, 1, S, 2, S, 3, S, 4],
       [S, S, S, 1, S, 2, S, 3, S, 4],
       [1, 2, 3, S, 4, S, 5, S, 6, S]]
  
  Args:
      n_q (int): Number of codebooks.
      flattening (list of int, optional): Flattening schema over the codebooks. If not defined,
          the codebooks will be flattened to 1 codebook per step, meaning that the sequence will
          have n_q extra steps for each timestep.
      delays (list of int, optional): Delay for each of the codebooks. If not defined,
          no delay is added and therefore will default to [0] * ``n_q``.
          Note that two codebooks that will be flattened to the same inner step
          should have the same delay, otherwise the pattern is considered as invalid.
class_docstr_tok: ["Provider","for","unrolling","codebooks","pattern",".","This","pattern","provider","enables","to","represent","the","codebook","flattened","completely","or","only","to","some","extend","while","also","specifying","a","given","delay","between","the","flattened","codebooks","representation",",","allowing","to","unroll","the","codebooks","in","the","sequence",".","Example",":","1",".","Flattening","of","the","codebooks",".","By","default",",","the","pattern","provider","will","fully","flatten","the","codebooks","such","as","flattening=range","(","n_q",")",",","taking","n_q","=","3","and","timesteps","=","4",":","[","[","1",",","2",",","3",",","4","]",",","[","1",",","2",",","3",",","4","]",",","[","1",",","2",",","3",",","4","]","]","will","result","into",":","[","[","S",",","S",",","1",",","S",",","S",",","2",",","S",",","S",",","3",",","S",",","S",",","4","]",",","[","S",",","1",",","S",",","S",",","2",",","S",",","S",",","3",",","S",",","S",",","4",",","S","]",",","[","1",",","S",",","S",",","2",",","S",",","S",",","3",",","S",",","S",",","4",",","S",",","S","]","]","2",".","Partial","flattening","of","the","codebooks",".","The","``","flattening","``","parameter","allows","to","specify","the","inner","step","for","each","of","the","codebook",",","allowing","to","define","which","codebook","to","flatten","(","or","keep","in","parallel",")",",","for","example","taking","n_q","=","3",",","timesteps","=","4","and","flattening","=","[","0",",","1",",","1","]",":","[","[","1",",","2",",","3",",","4","]",",","[","1",",","2",",","3",",","4","]",",","[","1",",","2",",","3",",","4","]","]","will","result","into",":","[","[","S",",","1",",","S",",","S",",","2",",","S",",","S",",","3",",","S",",","S",",","4",",","S","]",",","[","S",",","1",",","S",",","S",",","2",",","S",",","S",",","3",",","S",",","S",",","4",",","S","]",",","[","1",",","S",",","S",",","2",",","S",",","S",",","3",",","S",",","S",",","4",",","S",",","S","]","]","3",".","Flattening","with","delay",".","The","``","delay","``","parameter","allows","to","further","unroll","the","sequence","of","codebooks","allowing","to","specify","the","delay","per","codebook",".","Note","that","the","delay","between","codebooks","flattened","to","the","same","inner","timestep","should","be","coherent",".","For","example",",","taking","n_q","=","3",",","timesteps","=","4",",","flattening","=","[","0",",","1",",","1","]","and","delays","=","[","0",",","3",",","3","]",":","[","[","1",",","2",",","3",",","4","]",",","[","1",",","2",",","3",",","4","]",",","[","1",",","2",",","3",",","4","]","]","will","result","into",":","[","[","S",",","S",",","S",",","1",",","S",",","2",",","S",",","3",",","S",",","4","]",",","[","S",",","S",",","S",",","1",",","S",",","2",",","S",",","3",",","S",",","4","]",",","[","1",",","2",",","3",",","S",",","4",",","S",",","5",",","S",",","6",",","S","]","]","Args",":","n_q","(","int",")",":","Number","of","codebooks",".","flattening","(","list","of","int",",","optional",")",":","Flattening","schema","over","the","codebooks",".","If","not","defined",",","the","codebooks","will","be","flattened","to","1","codebook","per","step",",","meaning","that","the","sequence","will","have","n_q","extra","steps","for","each","timestep",".","delays","(","list","of","int",",","optional",")",":","Delay","for","each","of","the","codebooks",".","If","not","defined",",","no","delay","is","added","and","therefore","will","default","to","[","0","]","*","``","n_q","``",".","Note","that","two","codebooks","that","will","be","flattened","to","the","same","inner","step","should","have","the","same","delay",",","otherwise","the","pattern","is","considered","as","invalid","."]
docstr: Build a flattened codebooks representation as a dictionary of inner step
  and the actual codebook indices corresponding to the flattened codebook. For convenience, we
  also store the delay associated to the flattened codebook to avoid maintaining an extra mapping.
docstr_tok: ["Build","a","flattened","codebooks","representation","as","a","dictionary","of","inner","step","and","the","actual","codebook","indices","corresponding","to","the","flattened","codebook",".","For","convenience",",","we","also","store","the","delay","associated","to","the","flattened","codebook","to","avoid","maintaining","an","extra","mapping","."]
code: def _build_flattened_codebooks(
      self, delays: tp.List[int], flattening: tp.List[int]
  ):
      """Build a flattened codebooks representation as a dictionary of inner step
      and the actual codebook indices corresponding to the flattened codebook. For convenience, we
      also store the delay associated to the flattened codebook to avoid maintaining an extra mapping.
      """
      flattened_codebooks: dict = {}
      for q, (inner_step, delay) in enumerate(zip(flattening, delays)):
          if inner_step not in flattened_codebooks:
              flat_codebook = UnrolledPatternProvider.FlattenedCodebook(
                  codebooks=[q], delay=delay
              )
          else:
              flat_codebook = flattened_codebooks[inner_step]
              assert flat_codebook.delay == delay, (
                  "Delay and flattening between codebooks is inconsistent: ",
                  "two codebooks flattened to the same position should have the same delay.",
              )
              flat_codebook.codebooks.append(q)
          flattened_codebooks[inner_step] = flat_codebook
      return flattened_codebooks
  
imports: from collections import namedtuple
  from dataclasses import dataclass
  from functools import lru_cache
  import logging
  import typing
  from abc import ABC, abstractmethod
  import torch
label_desc: Use image node_id 2 for calling the UnrolledPatternProvider obj's underlying member method code with example usage: obj._build_flattened_codebooks(delays, flattening) and returns: flattened_codebooks