cirq.GateFamily

Wrapper around gate instances/types describing a set of accepted gates.

cirq.GateFamily(
    gate: (type[raw_types.Gate] | raw_types.Gate),
    *,
    name: (str | None) = None,
    description: (str | None) = None,
    ignore_global_phase: bool = True,
    tags_to_accept: Sequence[Hashable] = (),
    tags_to_ignore: Sequence[Hashable] = ()
) -> None

GateFamily supports initialization via

  • Non-parameterized instances of cirq.Gate (Instance Family).
  • Python types inheriting from cirq.Gate (Type Family).

By default, the containment checks depend on the initialization type:

For example:

  • Instance Family:

    gate_family = cirq.GateFamily(cirq.X)
assert cirq.X in gate_family
assert cirq.Rx(rads=np.pi) in gate_family
assert cirq.X ** sympy.Symbol("theta") not in gate_family

  • Type Family:

    gate_family = cirq.GateFamily(cirq.XPowGate)
assert cirq.X in gate_family
assert cirq.Rx(rads=np.pi) in gate_family
assert cirq.X ** sympy.Symbol("theta") in gate_family

As seen in the examples above, GateFamily supports containment checks for instances of both cirq.Operation and cirq.Gate. By default, a cirq.Operation instance op is accepted if the underlying op.gate is accepted.

Further constraints can be added on containment checks for cirq.Operation objects by setting tags_to_accept and/or tags_to_ignore in the GateFamily constructor. For a tagged operation, the underlying gate op.gate will be checked for containment only if both:

  • op.tags has no intersection with tags_to_ignore
  • tags_to_accept is not empty, then op.tags should have a non-empty intersection with tags_to_accept.

If a cirq.Operation contains tags from both tags_to_accept and tags_to_ignore, it is rejected. Furthermore, tags cannot appear in both tags_to_accept and tags_to_ignore.

For the purpose of tag comparisons, a Gate is considered as an Operation without tags.

>>> q = cirq.NamedQubit('q')
>>> gate_family = cirq.GateFamily(cirq.ZPowGate, tags_to_accept=['accepted_tag'])
>>> assert cirq.Z(q).with_tags('accepted_tag') in gate_family
>>> assert cirq.Z(q).with_tags('other_tag') not in gate_family
>>> assert cirq.Z(q) not in gate_family
>>> assert cirq.Z not in gate_family
...
>>> gate_family = cirq.GateFamily(cirq.ZPowGate, tags_to_ignore=['ignored_tag'])
>>> assert cirq.Z(q).with_tags('ignored_tag') not in gate_family
>>> assert cirq.Z(q).with_tags('other_tag') in gate_family
>>> assert cirq.Z(q) in gate_family
>>> assert cirq.Z in gate_family

In order to create gate families with constraints on parameters of a gate type, users should derive from the cirq.GateFamily class and override the _predicate method used to check for gate containment.

gate A python type inheriting from cirq.Gate for type based membership checks, or a non-parameterized instance of a cirq.Gate for equality based membership checks.
name The name of the gate family.
description Human readable description of the gate family.
ignore_global_phase If True, value equality is checked via cirq.equal_up_to_global_phase.
tags_to_accept If non-empty, only cirq.Operations containing at least one tag in this sequence can be accepted.
tags_to_ignore Any cirq.Operation containing at least one tag in this sequence is rejected. Note that this takes precedence over tags_to_accept, so an operation which contains tags from both tags_to_accept and tags_to_ignore is rejected.

ValueError if gate is not a cirq.Gate instance or subclass.
ValueError if gate is a parameterized instance of cirq.Gate.
ValueError if tags_to_accept and tags_to_ignore contain common tags.

description

gate

name

tags_to_accept

tags_to_ignore

Methods

__contains__

View source

__contains__(
    item: (raw_types.Gate | raw_types.Operation)
) -> bool

__eq__

View source

__eq__(
    other: _SupportsValueEquality
) -> bool

__ne__

View source

__ne__(
    other: _SupportsValueEquality
) -> bool