Skip to content

circuit

Circuit

The Circuit class is the only interface to access OpenSquirrel's features.

Examples:

>>> c = Circuit.from_string("version 3.0; qubit[3] q; h q[0]")
>>> c
version 3.0

qubit[3] q

h q[0]

>>> c.decomposer(decomposer=mckay_decomposer.McKayDecomposer)
>>> c
version 3.0

qubit[3] q

x90 q[0]
rz q[0], 1.5707963
x90 q[0]
Source code in opensquirrel\circuit.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
class Circuit:
    """The Circuit class is the only interface to access OpenSquirrel's features.

    Examples:
        >>> c = Circuit.from_string("version 3.0; qubit[3] q; h q[0]")
        >>> c
        version 3.0
        <BLANKLINE>
        qubit[3] q
        <BLANKLINE>
        h q[0]
        <BLANKLINE>
        >>> c.decomposer(decomposer=mckay_decomposer.McKayDecomposer)
        >>> c
        version 3.0
        <BLANKLINE>
        qubit[3] q
        <BLANKLINE>
        x90 q[0]
        rz q[0], 1.5707963
        x90 q[0]
        <BLANKLINE>
    """

    def __init__(self, register_manager: RegisterManager, ir: IR) -> None:
        """Create a circuit object from a register manager and an IR."""
        self.register_manager = register_manager
        self.ir = ir

    def __repr__(self) -> str:
        """Write the circuit to a cQASM 3 string."""
        from opensquirrel.writer import writer

        return writer.circuit_to_string(self)

    def __eq__(self, other: Any) -> bool:
        if not isinstance(other, Circuit):
            return False
        return self.register_manager == other.register_manager and self.ir == other.ir

    @classmethod
    def from_string(
        cls,
        cqasm3_string: str,
        gate_set: list[Callable[..., Gate]] = default_gate_set,
        gate_aliases: Mapping[str, Callable[..., Gate]] = default_gate_aliases,
        measurement_set: list[Callable[..., Measure]] = default_measurement_set,
    ) -> Circuit:
        """Create a circuit object from a cQasm3 string. All the gates in the circuit need to be defined in
        the `gates` argument.

        * type-checking is performed, eliminating qubit indices errors and incoherences
        * checks that used gates are supported and mentioned in `gates` with appropriate signatures
        * does not support map or variables, and other things...
        * for example of `gates` dictionary, please look at TestGates.py

        Args:
            cqasm3_string: a cQASM 3 string
            gate_set: an array of gate semantic functions. See default_gates for examples
            gate_aliases: a dictionary of extra gate aliases, mapping strings to functions in the gate set
            measurement_set: an array of measurement semantic functions. See default_measurements for examples
        """
        from opensquirrel.parser.libqasm.parser import Parser

        parser = Parser(
            gate_set=gate_set,
            gate_aliases=gate_aliases,
            measurement_set=measurement_set,
        )
        return parser.circuit_from_string(cqasm3_string)

    @property
    def qubit_register_size(self) -> int:
        return self.register_manager.get_qubit_register_size()

    @property
    def bit_register_size(self) -> int:
        return self.register_manager.get_bit_register_size()

    @property
    def qubit_register_name(self) -> str:
        return self.register_manager.get_qubit_register_name()

    @property
    def bit_register_name(self) -> str:
        return self.register_manager.get_bit_register_name()

    def merge_single_qubit_gates(self) -> None:
        """Merge all consecutive 1-qubit gates in the circuit.
        Gates obtained from merging other gates become anonymous gates.
        """
        from opensquirrel.merger import general_merger

        general_merger.merge_single_qubit_gates(self)

    def decompose(self, decomposer: Decomposer) -> None:
        """Generic decomposition pass.
        It applies the given decomposer function to every gate in the circuit.
        """
        from opensquirrel.decomposer import general_decomposer

        general_decomposer.decompose(self.ir, decomposer)

    def map(self, mapper: Mapper) -> None:
        """Generic qubit mapper pass.
        Map the (virtual) qubits of the circuit to the physical qubits of the target hardware.
        """
        from opensquirrel.mapper.qubit_remapper import remap_ir

        remap_ir(self, mapper.get_mapping())

    def replace(self, gate_generator: Callable[..., Gate], f: Callable[..., list[Gate]]) -> None:
        """Manually replace occurrences of a given gate with a list of gates.
        `f` is a callable that takes the arguments of the gate that is to be replaced and
        returns the decomposition as a list of gates.
        """
        from opensquirrel.decomposer import general_decomposer

        general_decomposer.replace(self.ir, gate_generator, f)

    def export(self, fmt: Literal[ExportFormat.QUANTIFY_SCHEDULER] | None = None) -> Any:
        if fmt == ExportFormat.QUANTIFY_SCHEDULER:
            from opensquirrel.exporter import quantify_scheduler_exporter

            return quantify_scheduler_exporter.export(self)
        msg = "unknown exporter format"
        raise ValueError(msg)

__init__(register_manager, ir)

Create a circuit object from a register manager and an IR.

Source code in opensquirrel\circuit.py 
41
42
43
44
def __init__(self, register_manager: RegisterManager, ir: IR) -> None:
    """Create a circuit object from a register manager and an IR."""
    self.register_manager = register_manager
    self.ir = ir

__repr__()

Write the circuit to a cQASM 3 string.

Source code in opensquirrel\circuit.py 
46
47
48
49
50
def __repr__(self) -> str:
    """Write the circuit to a cQASM 3 string."""
    from opensquirrel.writer import writer

    return writer.circuit_to_string(self)

decompose(decomposer)

Generic decomposition pass. It applies the given decomposer function to every gate in the circuit.

Source code in opensquirrel\circuit.py 
112
113
114
115
116
117
118
def decompose(self, decomposer: Decomposer) -> None:
    """Generic decomposition pass.
    It applies the given decomposer function to every gate in the circuit.
    """
    from opensquirrel.decomposer import general_decomposer

    general_decomposer.decompose(self.ir, decomposer)

from_string(cqasm3_string, gate_set=default_gate_set, gate_aliases=default_gate_aliases, measurement_set=default_measurement_set) classmethod

Create a circuit object from a cQasm3 string. All the gates in the circuit need to be defined in the gates argument.

  • type-checking is performed, eliminating qubit indices errors and incoherences
  • checks that used gates are supported and mentioned in gates with appropriate signatures
  • does not support map or variables, and other things...
  • for example of gates dictionary, please look at TestGates.py

Parameters:

Name Type Description Default
cqasm3_string str

a cQASM 3 string

 required
gate_set list[Callable[..., Gate]]

an array of gate semantic functions. See default_gates for examples

 default_gate_set
gate_aliases Mapping[str, Callable[..., Gate]]

a dictionary of extra gate aliases, mapping strings to functions in the gate set

 default_gate_aliases
measurement_set list[Callable[..., Measure]]

an array of measurement semantic functions. See default_measurements for examples

 default_measurement_set
Source code in opensquirrel\circuit.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
@classmethod
def from_string(
    cls,
    cqasm3_string: str,
    gate_set: list[Callable[..., Gate]] = default_gate_set,
    gate_aliases: Mapping[str, Callable[..., Gate]] = default_gate_aliases,
    measurement_set: list[Callable[..., Measure]] = default_measurement_set,
) -> Circuit:
    """Create a circuit object from a cQasm3 string. All the gates in the circuit need to be defined in
    the `gates` argument.

    * type-checking is performed, eliminating qubit indices errors and incoherences
    * checks that used gates are supported and mentioned in `gates` with appropriate signatures
    * does not support map or variables, and other things...
    * for example of `gates` dictionary, please look at TestGates.py

    Args:
        cqasm3_string: a cQASM 3 string
        gate_set: an array of gate semantic functions. See default_gates for examples
        gate_aliases: a dictionary of extra gate aliases, mapping strings to functions in the gate set
        measurement_set: an array of measurement semantic functions. See default_measurements for examples
    """
    from opensquirrel.parser.libqasm.parser import Parser

    parser = Parser(
        gate_set=gate_set,
        gate_aliases=gate_aliases,
        measurement_set=measurement_set,
    )
    return parser.circuit_from_string(cqasm3_string)

map(mapper)

Generic qubit mapper pass. Map the (virtual) qubits of the circuit to the physical qubits of the target hardware.

Source code in opensquirrel\circuit.py 
120
121
122
123
124
125
126
def map(self, mapper: Mapper) -> None:
    """Generic qubit mapper pass.
    Map the (virtual) qubits of the circuit to the physical qubits of the target hardware.
    """
    from opensquirrel.mapper.qubit_remapper import remap_ir

    remap_ir(self, mapper.get_mapping())

merge_single_qubit_gates()

Merge all consecutive 1-qubit gates in the circuit. Gates obtained from merging other gates become anonymous gates.

Source code in opensquirrel\circuit.py 
104
105
106
107
108
109
110
def merge_single_qubit_gates(self) -> None:
    """Merge all consecutive 1-qubit gates in the circuit.
    Gates obtained from merging other gates become anonymous gates.
    """
    from opensquirrel.merger import general_merger

    general_merger.merge_single_qubit_gates(self)

replace(gate_generator, f)

Manually replace occurrences of a given gate with a list of gates. f is a callable that takes the arguments of the gate that is to be replaced and returns the decomposition as a list of gates.

Source code in opensquirrel\circuit.py 
128
129
130
131
132
133
134
135
def replace(self, gate_generator: Callable[..., Gate], f: Callable[..., list[Gate]]) -> None:
    """Manually replace occurrences of a given gate with a list of gates.
    `f` is a callable that takes the arguments of the gate that is to be replaced and
    returns the decomposition as a list of gates.
    """
    from opensquirrel.decomposer import general_decomposer

    general_decomposer.replace(self.ir, gate_generator, f)