cirq.flatten

Creates a copy of val with any symbols or expressions replaced with new symbols.

cirq.flatten(
    val: Any
) -> tuple[Any, ExpressionMap]

Used in the notebooks

Used in the tutorials

val can be a Circuit, Gate, Operation, or other type.

flatten goes through every parameter in val and does the following:

  • If the parameter is a number, don't change it.
  • If the parameter is a symbol, don't change it.
  • If the parameter is an expression, replace it with a symbol. The new symbol will be sympy.Symbol('<x + 1>') if the expression was sympy.Symbol('x') + 1. In the unlikely case that an expression with a different meaning also has the string 'x + 1', a number is appended to the name to avoid collision: sympy.Symbol('<x + 1>_1').

This function also creates a dictionary mapping from expressions and symbols in val to the new symbols in the flattened copy of val. E.g. cirq.ExpressionMap({sympy.Symbol('x')+1: sympy.Symbol('<x + 1>')}). This ExpressionMap can be used to transform a sweep over the symbols in val to a sweep over the flattened symbols e.g. a sweep over sympy.Symbol('x') to a sweep over sympy.Symbol('<x + 1>').

val The value to copy and substitute parameter expressions with flattened symbols.

The tuple (new value, expression map) where new value and expression map are described above.

Examples:

qubit = cirq.LineQubit(0)
a = sympy.Symbol('a')
circuit = cirq.Circuit(
    cirq.X(qubit) ** (a/4),
    cirq.Y(qubit) ** (1-a/2),
)
print(circuit)
0: ───X^(a/4)───Y^(1 - a/2)───
 
sweep = cirq.Linspace(a, start=0, stop=3, length=4)
print(cirq.ListSweep(sweep))
Sweep:
{'a': 0.0}
{'a': 1.0}
{'a': 2.0}
{'a': 3.0}
 
c_flat, expr_map = cirq.flatten(circuit)
print(c_flat)
0: ───X^(<a/4>)───Y^(<1 - a/2>)───
expr_map
cirq.ExpressionMap({a/4: <a/4>, 1 - a/2: <1 - a/2>})
 
new_sweep = expr_map.transform_sweep(sweep)
print(new_sweep)
Sweep:
{'<a/4>': 0.0, '<1 - a/2>': 1.0}
{'<a/4>': 0.25, '<1 - a/2>': 0.5}
{'<a/4>': 0.5, '<1 - a/2>': 0.0}
{'<a/4>': 0.75, '<1 - a/2>': -0.5}
 
for params in sweep:  # Original
    print(circuit,
          '=>',
          cirq.resolve_parameters(circuit, params))
0: ───X^(a/4)───Y^(1 - a/2)─── => 0: ───X^0───Y───
0: ───X^(a/4)───Y^(1 - a/2)─── => 0: ───X^0.25───Y^0.5───
0: ───X^(a/4)───Y^(1 - a/2)─── => 0: ───X^0.5───Y^0───
0: ───X^(a/4)───Y^(1 - a/2)─── => 0: ───X^0.75───Y^-0.5───
 
for params in new_sweep:  # Flattened
    print(c_flat, '=>', end=' ')
    print(cirq.resolve_parameters(c_flat, params))
0: ───X^(<a/4>)───Y^(<1 - a/2>)─── => 0: ───X^0───Y───
0: ───X^(<a/4>)───Y^(<1 - a/2>)─── => 0: ───X^0.25───Y^0.5───
0: ───X^(<a/4>)───Y^(<1 - a/2>)─── => 0: ───X^0.5───Y^0───
0: ───X^(<a/4>)───Y^(<1 - a/2>)─── => 0: ───X^0.75───Y^-0.5───