Principle:Huggingface Optimum Transformation Composition

Overview

Mechanism for combining multiple graph transformations into a single composite transformation that applies them in sequence.

Description

The compose function takes multiple Transformation instances and creates a single composite Transformation that applies them left-to-right. This enables building reusable optimization pipelines where multiple graph rewrites are bundled together and managed as a single unit.

Key behaviors:

• Sequential application -- Transformations are applied in the order they are passed: the first argument is applied first, the second argument is applied to its result, and so on.
• Reversibility propagation -- If all input transformations are ReversibleTransformation instances, the composed result is also reversible. The reversal applies transformations in right-to-left order (the inverse of the forward order).
• Computation preservation -- The composed transformation has preserves_computation=True only if all input transformations preserve computation.
• In-place control -- An optional inplace=False parameter prepends a DeepCopy transformation to avoid modifying the original graph module.

Composition Behavior

Scenario	Result Type	Reversible
All inputs are ReversibleTransformation	ReversibleTransformation	Yes
Any input is non-reversible Transformation	Transformation	No
inplace=False specified	Same as above, but with DeepCopy prepended	Same as above

Usage

Use when applying multiple optimizations to a model and wanting to manage them as a single unit. Common scenarios include:

• Building standard optimization pipelines -- Combine commonly used transformations (e.g., merge linears, fuse bias, convert divisions) into one reusable pipeline.
• Atomic apply/revert -- Apply all optimizations at once and, if all are reversible, revert all at once.
• Non-destructive experimentation -- Use inplace=False to try optimizations without modifying the original model.

Theoretical Basis

Function composition applied to graph transformations. The composition follows the standard mathematical definition:

For transformations T1, T2, T3:

compose(T1, T2, T3)(G) = T3(T2(T1(G)))

For reversibility (applied right-to-left):

reverse(compose(T1, T2, T3))(G) = T1.reverse(T2.reverse(T3.reverse(G)))

This ordering is essential for correctness: since T3 was the last transformation applied, it must be the first one reversed. Each transformation's reverse method undoes only the changes made by that specific transformation, relying on the signature-based marking system to identify which nodes it modified.

The lint_and_recompile parameter is set to False for intermediate transformations within the composition (to avoid redundant work) and only performed once at the end by the final __call__.

Related

• implemented_by -> Implementation:Huggingface_Optimum_Compose

Connections

• Implementation:Huggingface_Optimum_Compose