ScheduledCircuit#

class tqec.circuit.ScheduledCircuit(moments, schedule, qubit_map, _avoid_checks=False)[source]#

Bases: object

Represent a quantum circuit with scheduled moments.

This class aims at representing a stim.Circuit instance that has all its moments scheduled, i.e., associated with a time slice.

This class explicitly does not support stim.CircuitRepeatBlock (i.e., REPEAT instruction). It will raise an exception if such an instruction is found.

Parameters:

  • moments (list[Moment]) – moments representing the computation that is scheduled. The provided moments should not contain any QUBIT_COORDS instructions. Instead, the qubit coordinates should be provided through the qubit_map parameter.

  • schedule (Schedule | list[int] | int) – schedule of the provided moments. If an integer is provided, each moment of the provided stim.Circuit is scheduled sequentially, starting by the provided integer.

  • qubit_map (QubitMap) – a map from indices to qubits that is used to re-create QUBIT_COORDS instructions when generating a stim.Circuit.

  • _avoid_checks (bool) – if True, the inputs are not checked for pre-condition violation and it is up to the user to ensure that ScheduledCircuit pre-conditions are checked by the provided input.

Raises:

  • ScheduleError – if the provided schedule is invalid.

  • TQECException – if the provided circuit contains at least one stim.CircuitRepeatBlock instance.

  • TQECException – if the provided circuit contains at least one QUBIT_COORDS instruction after the first TICK instruction.

Methods

__init__(moments, schedule, qubit_map[, ...])

Represent a quantum circuit with scheduled moments.

add_to_schedule_index(schedule, moment)

Add the operations contained in the provided moment to the provided schedule.

append_annotation(instruction)

Append an annotation to the last moment.

append_new_moment(moment)

Schedule the provided Moment instance at the end of the circuit.

append_observable(index, targets)

Append an OBSERVABLE_INCLUDE instruction to the last moment.

empty()

Returns an empty ScheduledCircuit instance.

filter_by_qubits(qubits_to_keep)

Filter the circuit to keep only the instructions that are applied on the provided qubits.

from_circuit(circuit[, schedule, qubit_map])

Build a ScheduledCircuit instance from a circuit and a schedule.

get_circuit([include_qubit_coords])

Build and return the stim.Circuit instance represented by self.

get_qubit_coords_definition_preamble()

Get a circuit with only QUBIT_COORDS instructions.

get_repeated_circuit(repetitions[, ...])

Build and return the stim.Circuit instance represented by self encapsulated in a REPEAT block.

map_qubit_indices(qubit_index_map[, inplace])

Map the qubits indices the ScheduledCircuit instance is applied on.

map_to_qubits(qubit_map[, inplace_qubit_map])

Map the qubits the ScheduledCircuit instance is applied on.

moment_at_schedule(schedule)

Get the Moment instance scheduled at the provided schedule.

Attributes

moments

Iterator over the internal moments representing the computation.

num_measurements

Number of measurements in the represented computation.

qubit_map

Qubit map of the circuit.

qubits

Set of qubits on which the circuit is applied.

schedule

Schedule of the internal moments.

scheduled_moments

Yields stim.Circuit instances representing a moment with their computed schedule.

Detailed methods

__init__(moments, schedule, qubit_map, _avoid_checks=False)[source]#

Represent a quantum circuit with scheduled moments.

This class aims at representing a stim.Circuit instance that has all its moments scheduled, i.e., associated with a time slice.

This class explicitly does not support stim.CircuitRepeatBlock (i.e., REPEAT instruction). It will raise an exception if such an instruction is found.

Parameters:

  • moments (list[Moment]) – moments representing the computation that is scheduled. The provided moments should not contain any QUBIT_COORDS instructions. Instead, the qubit coordinates should be provided through the qubit_map parameter.

  • schedule (Schedule | list[int] | int) – schedule of the provided moments. If an integer is provided, each moment of the provided stim.Circuit is scheduled sequentially, starting by the provided integer.

  • qubit_map (QubitMap) – a map from indices to qubits that is used to re-create QUBIT_COORDS instructions when generating a stim.Circuit.

  • _avoid_checks (bool) – if True, the inputs are not checked for pre-condition violation and it is up to the user to ensure that ScheduledCircuit pre-conditions are checked by the provided input.

Raises:

  • ScheduleError – if the provided schedule is invalid.

  • TQECException – if the provided circuit contains at least one stim.CircuitRepeatBlock instance.

  • TQECException – if the provided circuit contains at least one QUBIT_COORDS instruction after the first TICK instruction.

Return type:

None

add_to_schedule_index(schedule, moment)[source]#

Add the operations contained in the provided moment to the provided schedule.

Parameters:

  • schedule (int) – schedule at which operations in moment should be added. If the schedule is negative, it is considered as an index from the end. For example, -1 is the last schedule and -2 is the last schedule - 1 (which might not be the second to last schedule).

  • moment (Moment) – operations that should be added.

Return type:

None

append_annotation(instruction)[source]#

Append an annotation to the last moment.

Parameters:

instruction (CircuitInstruction) – an annotation that will be added to the last moment of self.

Raises:

TQECException – if the provided instruction is not an annotation.

Return type:

None

append_new_moment(moment)[source]#

Schedule the provided Moment instance at the end of the circuit. The new schedule will be the last schedule plus one.

Parameters:

moment (Moment) – the moment to schedule.

Return type:

None

append_observable(index, targets)[source]#

Append an OBSERVABLE_INCLUDE instruction to the last moment.

Parameters:

  • index (int) – index of the observable to append measurement records to.

  • targets (Sequence[GateTarget]) – measurement records forming (part of) the observable.

Return type:

None

static empty()[source]#

Returns an empty ScheduledCircuit instance.

Return type:

ScheduledCircuit

filter_by_qubits(qubits_to_keep)[source]#

Filter the circuit to keep only the instructions that are applied on the provided qubits. If an instruction is applied on a qubit that is not in the provided list, it is removed.

After filtering, the empty moments as well as the corresponding schedules are removed.

Parameters:

qubits_to_keep (Iterable[GridQubit]) – the qubits to keep in the circuit.

Returns:

a new instance of ScheduledCircuit with the filtered circuit and schedules.

Return type:

ScheduledCircuit

static from_circuit(circuit, schedule=0, qubit_map=None)[source]#

Build a ScheduledCircuit instance from a circuit and a schedule.

Parameters:

  • circuit (Circuit) – the instance of stim.Circuit that is scheduled. Should not contain any instance of stim.CircuitRepeatBlock.

  • schedule (Schedule | list[int] | int) – a sorted list of positive integers or a positive integer. If a list is given, it should contain as many values as there are moments in the provided stim.Circuit instance. If an integer is provided, each moment of the provided stim.Circuit is scheduled sequentially, starting by the provided schedule.

  • qubit_map (QubitMap | None) – a map from indices to qubits. If None, this function will try to extract the qubit coordinates from the QUBIT_COORDS instructions found in the provided circuit. Else, the provided map will be used.

Raises:

  • ScheduleError – if the provided schedule is invalid.

  • TQECException – if the provided circuit contains at least one stim.CircuitRepeatBlock instance.

  • TQECException – if the provided circuit contains at least one QUBIT_COORDS instruction after the first TICK instruction.

Return type:

ScheduledCircuit

get_circuit(include_qubit_coords=True)[source]#

Build and return the stim.Circuit instance represented by self.

Warning

The circuit is re-built at each call! Use that function wisely.

Returns:

stim.Circuit instance represented by self.

Parameters:

include_qubit_coords (bool)

Return type:

Circuit

get_qubit_coords_definition_preamble()[source]#

Get a circuit with only QUBIT_COORDS instructions.

Return type:

Circuit

get_repeated_circuit(repetitions, include_qubit_coords=True, include_additional_tick_in_body=True)[source]#

Build and return the stim.Circuit instance represented by self encapsulated in a REPEAT block.

Warning

The circuit is re-built at each call! Use that function wisely.

Warning

An extra TICK instruction is appended by default at the end of the body of the REPEAT block to mimic stim way of doing. You can control that behaviour with the include_additional_tick_in_body parameter.

Parameters:

  • repetitions (int) – argument to the enclosing REPEAT block representing the number of repetitions that should be used in the returned circuit.

  • include_qubit_coords (bool) – if True, QUBIT_COORDS instructions are inserted at the beginning of the returned circuit (before the REPEAT block).

  • include_additional_tick_in_body (bool) – if True, an additional TICK instruction is appended to the body (i.e., the circuit inside the REPEAT block) of the returned circuit. This is the default behaviour as stim does that in its code and adding the TICK here makes more sense than after the REPEAT block.

Returns:

stim.Circuit instance represented by self encapsulated in a REPEAT block.

Return type:

Circuit

map_qubit_indices(qubit_index_map, inplace=False)[source]#

Map the qubits indices the ScheduledCircuit instance is applied on.

Note

This method differs from map_to_qubits() because it changes the qubit indices, which requires to iterate the whole circuit and change every instruction target.

This method should be used before combining several ScheduledCircuit instances that are not aware of each other.

Parameters:

  • qubit_index_map (dict[int, int]) – the map used to modify the qubit targets.

  • inplace (bool) – if True, perform the modification in place and return self. Else, perform the modification in a copy and return the copy. Note that the runtime cost of this method should be the same independently of the value provided here.

Returns:

a modified instance of ScheduledCircuit (a copy if inplace is True, else self).

Return type:

ScheduledCircuit

map_to_qubits(qubit_map, inplace_qubit_map=False)[source]#

Map the qubits the ScheduledCircuit instance is applied on.

Note

This method only changes the QUBIT_COORDS instructions at the beginning of the circuit. As such, it never has to iterate on the whole quantum circuit and so this method is very efficient.

Warning

The underlying quantum circuit data-structure is never copied (even if inplace_qubit_map == True), so the returned instance should be used with care, in particular if any method mutating the underlying circuit is called on self or the returned instance after calling that method.

Parameters:

  • qubit_map (Callable[[GridQubit], GridQubit]) – the map used to modify the qubits.

  • inplace_qubit_map (bool) – if True, replaces the qubit map directly in self and return self. Else, create a new instance from self without copying the underlying moments, simply replacing the qubit map.

Returns:

an instance of ScheduledCircuit with a new qubit map.

Return type:

ScheduledCircuit

moment_at_schedule(schedule)[source]#

Get the Moment instance scheduled at the provided schedule.

Parameters:

schedule (int) – the schedule at which the Moment instance should be returned. If the schedule is negative, it is considered as an index from the end. For example, -1 is the last schedule and -2 is the last schedule - 1 (which might not be the second to last schedule).

Raises:

TQECException – if no moment exist at the provided schedule.

Return type:

Moment