spin_pulse.transpilation.pulse_circuit

Pulse-level representation of a quantum circuit.

Classes

PulseCircuit

Pulse-level representation of a quantum circuit.

Module Contents

class spin_pulse.transpilation.pulse_circuit.PulseCircuit(circ, qubits, pulse_layers, hardware_specs, exp_env=None)

Pulse-level representation of a quantum circuit.

A PulseCircuit stores a layered decomposition of a qiskit.QuantumCircuit into PulseLayer objects and, optionally, a stochastic noise environment. It provides utilities to visualize the pulse schedule, convert it back to a gate-level circuit, and compute fidelities or average channels under sampled noise realizations.

- original_circ

Original quantum circuit from which the PulseCircuit was constructed.

Type:

qiskit.QuantumCircuit

- num_qubits

Number of qubits in the circuit.

Type:

int

- qubits

Ordered list of qubits acted on by the circuit.

Type:

list[qiskit.circuit.Qubit]

- pulse_layers

Ordered list of pulse layers that implement the circuit at the pulse level.

Type:

list[PulseLayer]

- n_layers

Number of pulse layers.

Type:

int

- duration

Total duration of the pulse circuit, given by the sum of all layer durations (in the discrete time unit of the model).

Type:

int

- t_lab

Current position in the laboratory time axis, used to attach successive noise time traces when averaging over samples.

Type:

int

Initialize a PulseCircuit from pulse layers.

The constructor records the original circuit, the list of qubits and the sequence of PulseLayer objects. It computes the total duration, assigns starting times to all layers and computes a dynamical decoupling sequence according to the hardware specifications. If an ExperimentalEnvironment is provided, noise time traces are attached to the circuit and its layers. Optionally, a container for storing per-sample time series can be created.

Parameters:

• circ (QuantumCircuit) – Original quantum circuit represented at the pulse level.

• qubits (list[qiskit.circuit.Qubit]) – Ordered list of qubits involved in the circuit.

• pulse_layers (list[PulseLayer]) – Pulse layers that realize the circuit in time order.

• hardware_specs (HardwareSpecs) – Hardware configuration specifying fields, couplings and dynamical decoupling options.

• exp_env (ExperimentalEnvironment | None) – Noise environment from which time traces are drawn and attached to this circuit. If None, no noise trace is attached.

original_circ: qiskit.QuantumCircuit

qubits: list[qiskit.circuit.Qubit]

num_qubits

pulse_layers

n_layers

duration

t_lab = 0

classmethod from_circuit(circ, hardware_specs, exp_env=None)

Construct a PulseCircuit from a qiskit.QuantumCircuit.

The input is first converted to a qiskit.dagcircuit.DAGCircuit then all barrier and measurement gate are removed, and each DAG layer is translated into a PulseLayer using the hardware specifications. Empty layers (containing only barriers) are skipped. The resulting list of pulse layers is used to build a PulseCircuit.

Parameters:

• circ (qiskit.QuantumCircuit) – Circuit to translate into pulse layers.

• hardware_specs (HardwareSpecs) – Hardware specification used to map gate operations to pulse sequences.

• exp_env (ExperimentalEnvironment | None) – Experimental environment providing noise specification and noise time traces. If None, no noise is attached to the pulses.

Returns:

A pulse-level representation of the input circuit.

Return type:

PulseCircuit

classmethod from_dag_circuit(dag, hardware_specs, exp_env=None, original_circuit=None)

Construct a PulseCircuit from a qiskit.dagcircuit.DAGCircuit.

The input circuit is first stripped of measurements and barrier, if present. Then each DAG layer is translated into a PulseLayer using the hardware specifications. Empty layers (containing only barriers) are skipped. The resulting list of pulse layers is used to build a PulseCircuit.

Parameters:

• dag (qiskit.dagcircuit.DAGCircuit) – Circuit to translate into pulse layers.

• hardware_specs (HardwareSpecs) – Hardware specification used to map gate operations to pulse sequences.

• exp_env (ExperimentalEnvironment | None) – Experimental environment providing noise specification and noise time traces. If None, no noise is attached to the pulses.

• original_circuit (qiskit.QuantumCircuit | None)

Returns:

A pulse-level representation of the input circuit.

Return type:

PulseCircuit

assign_starting_times()

Assign a starting time to each pulse layer to synchronize the different layers and pulse instructions.

The starting time t_start of each PulseLayer is computed as the cumulative duration of all previous layers, with the first layer starting at time zero. This defines a global time axis for the PulseCircuit.

plot(hardware_specs=None, label_gates=True)

Plot the pulse schedule of the circuit.

This method creates a multi-panel matplotlib figure showing, for each layer, the one-qubit and two-qubit pulse envelopes applied to each qubit and coupling. The vertical scale is chosen consistently with the hardware field and coupling amplitudes if given.

Parameters:

• hardware_specs (HardwareSpecs | None) – Hardware specification used to set the limits of manipulation parameter amplitudes. If None, default symmetric limits are used.

• label_gates (bool) – If True, gate labels are shown.

to_circuit(measure_all=False)

Convert the pulse circuit back to a qiskit.QuantumCircuit.

Each PulseLayer is converted into equivalent circuit that are composed into a copy of the original circuit structure. Optionally, a final measurement on all qubits is added.

Parameters:

measure_all (bool) – If True, all qubits are measured at the end of the reconstructed circuit.

Returns:

A circuit implementing the same unitary evolution as the PulseCircuit (up to numerical approximations).

Return type:

qiskit.QuantumCircuit

circuit_samples(exp_env=None)

Compute the number of noisy circuit samples that can be obtained with the given environment.

The number of circuit samples is given by the integer ratio between the environment duration and the pulse-circuit duration. If no environment is provided, a single sample is assumed.

Parameters:

exp_env (ExperimentalEnvironment | None) – Experimental environment providing the total duration.

Returns:

Number of non-overlapping samples that can be drawn from the duration of the experiment.

Return type:

int

get_logical_bitstring(physical_bistring)

Restore the original logical qubit layout before transpilation. During Qiskit transpilation process, the qubit register may be reordered to produce an optimized physical layout that minimizes gate costs. To recover the logical bitstring and interpret measurement outcomes correctly, it is necessary to invert this remapping and reconstruct the initial logical ordering of the qubits.

The mapping is derived from the layout associated with the original circuit used to build the PulseCircuit. If a TranspileLayout is present, the final index layout is used. If only a Layout is available, its permutation is used and a warning is emitted, as this typically indicates that the circuit was not transpiled. If no layout information is present, the physical and logical orders are assumed to coincide and a warning is emitted.

Parameters:

physical_bistring (str) – Bitstring obtained from a measurement in the physical qubit ordering.

Returns:

Bitstring reordered into the logical qubit basis.

Return type:

str

averaging_over_samples(f, exp_env=None, *args)

Estimate the average value over as many noisy samples as the experimental environment allows it, of a user-provided function using the pulse circuit.

This method repeatedly attaches new pieces of the noise time traces from the experimental environment to the PulseCircuit and evaluates a user-provided function f(self, *args) for each realization. The results are averaged over all samples, effectively performing a Monte Carlo average over noise trajectories.

Parameters:

• f (Callable) – Function that takes the PulseCircuit as first argument and returns a numerical quantity to be averaged.

• exp_env (ExperimentalEnvironment | None) – Noise environment from which time traces are drawn. If None, a single deterministic evaluation is performed.

• *Parameters – Additional positional arguments forwarded to f.

Returns:

The sample-averaged value of f(self, *args).

Return type:

Any

run_experiment(exp_env, simulator=AerSimulator())

Simulate single-shot measurement on noisy instances of the circuit.

This method repeatedly attaches new pieces of the noise time traces from the experimental environment to the PulseCircuit and simulates with MPS method a single-shot measurement thanks to Qiskit Aer. The results are stored in a dictionary that gather the counts obtained for all possible bitstrings.

Parameters:

• exp_env (ExperimentalEnvironment | None) – Noise environment from which time traces are drawn. If None, a single deterministic evaluation is performed.

• simulator (-) – an instance of qiksit’s AerSimulator.

Returns:

A dictionary which keys are the obtained bitstrings and their respective number of occurences.

Return type:

dict

fidelity(circ_ref=None)

Compute the average gate fidelity with respect to a reference circuit.

The PulseCircuit is converted to a qiskit.QuantumCircuit, and the average gate fidelity between its unitary and that of the reference circuit is computed using the qiskit.quantum_info.Operator representation.

Parameters:

circ_ref (qiskit.QuantumCircuit) – Reference circuit used to define the target unitary. Default is self.original_circ

Returns:

Average gate fidelity between the PulseCircuit unitary and the reference circuit unitary.

Return type:

float

mean_fidelity(exp_env, circ_ref=None)

Estimate the mean fidelity under a stochastic noise environment.

The average gate fidelity with respect to a reference circuit is computed for multiple noise realizations drawn from the experimental environment, and the results are averaged using averaging_over_samples.

Parameters:

• circ_ref (qiskit.QuantumCircuit) – Reference circuit used to define the target unitary.

• exp_env (ExperimentalEnvironment | None) – Noise environment from which time traces are drawn.

Returns:

Sample-averaged gate fidelity under the specified noise model.

Return type:

float

mean_channel(exp_env=None)

Estimate the mean quantum channel generated by the pulse circuit.

For each noise realization, the PulseCircuit is converted to a qiskit.QuantumCircuit and then to a SuperOp representing the corresponding quantum channel. The channels are averaged over samples using averaging_over_samples.

Parameters:

exp_env (ExperimentalEnvironment | None) – Noise environment from which time traces are drawn.

Returns:

Sample-averaged quantum channel acting on the qubit register.

Return type:

qiskit.quantum_info.SuperOp

attach_time_traces(exp_env=None)

Attach noise time traces from the experimental environment to the pulse circuit.

If an experimental environment is provided, this method extracts segments of the environment time traces that match the total circuit duration and assigns them to the PulseCircuit and each PulseLayer. For one-qubit pulse sequences, the corresponding single-qubit time traces are attached (qubit’s frequency deviation). For two-qubit sequences, coupling time traces are attached if available (i.e. J coupling noise) and used to set the J noise deviation during two-qubit gates.

The internal laboratory time pointer t_lab is incremented by the circuit duration after attaching the time traces, so that subsequent calls use the next segment of the noise time trace.

Parameters:

exp_env (ExperimentalEnvironment | None) – Experimental environment providing qubit’s frequency deviation time trace and, optionally, J coupling deviation time traces. If None, no trace is attached.

attach_dynamical_decoupling(hardware_specs)

Insert dynamical decoupling sequences into all pulse layers, when possible (i.e. Idle time sufficiently long).

If a dynamical decoupling mode is specified in the hardware specifications, each PulseLayer in the circuit is updated by calling its attach_dynamical_decoupling method with the chosen mode. If no dynamical decoupling is configured, the circuit is left unchanged.

Parameters:

hardware_specs (HardwareSpecs) – Hardware configuration specifying the dynamical decoupling mode and available pulse shapes.