diffusers/pr_12807/en/modular_diffusers/modular_diffusers_states.md

States

Blocks rely on the PipelineState and BlockState data structures for communicating and sharing data.

State	Description
PipelineState	Maintains the overall data required for a pipeline's execution and allows blocks to read and update its data.
BlockState	Allows each block to perform its computation with the necessary data from inputs

This guide explains how states work and how they connect blocks.

PipelineState

The PipelineState is a global state container for all blocks. It maintains the complete runtime state of the pipeline and provides a structured way for blocks to read from and write to shared data.

There are two dict's in PipelineState for structuring data.

• The values dict is a mutable state containing a copy of user provided input values and intermediate output values generated by blocks. If a block modifies an input, it will be reflected in the values dict after calling set_block_state.

PipelineState(
  values={
    'prompt': 'a cat'
    'guidance_scale': 7.0
    'num_inference_steps': 25
    'prompt_embeds': Tensor(dtype=torch.float32, shape=torch.Size([1, 1, 1, 1]))
    'negative_prompt_embeds': None
  },
)

BlockState

The BlockState is a local view of the relevant variables an individual block needs from PipelineState for performing it's computations.

Access these variables directly as attributes like block_state.image.

BlockState(
    image: 
)

When a block's __call__ method is executed, it retrieves the BlockState with self.get_block_state(state), performs it's operations, and updates PipelineState with self.set_block_state(state, block_state).

def __call__(self, components, state):
    # retrieve BlockState
    block_state = self.get_block_state(state)

    # computation logic on inputs

    # update PipelineState
    self.set_block_state(state, block_state)
    return components, state

State interaction

PipelineState and BlockState interaction is defined by a block's inputs, and intermediate_outputs.

• inputs, a block can modify an input - like block_state.image - and this change can be propagated globally to PipelineState by calling set_block_state.
• intermediate_outputs, is a new variable that a block creates. It is added to the PipelineState's values dict and is available as for subsequent blocks or accessed by users as a final output from the pipeline.