spin_pulse.transpilation.instructions¶

Instruction representation used in pulse level description of a circuit.

Re-exported objects¶

The following objects can be directly imported from spin_pulse.transpilation.instructions even if they are implemented in submodules.

`GaussianRotationInstruction`	Gaussian-shaped rotation pulse instruction.
`IdleInstruction`	Represent an idle (delay) operation applied to one or more qubits.
`PulseInstruction`	Base class representing a pulse-level instruction applied to qubits.
`RotationInstruction`	Base class for single- and two-qubit rotation pulse instructions.
`SquareRotationInstruction`	Square-shaped rotation pulse with optional linear ramps.

Submodules¶

Classes¶

`IdleInstruction`	Represent an idle (delay) operation applied to one or more qubits.
`PulseInstruction`	Base class representing a pulse-level instruction applied to qubits.
`GaussianRotationInstruction`	Gaussian-shaped rotation pulse instruction.
`RotationInstruction`	Base class for single- and two-qubit rotation pulse instructions.
`SquareRotationInstruction`	Square-shaped rotation pulse with optional linear ramps.

Package Contents¶

class spin_pulse.transpilation.instructions.IdleInstruction(qubits, duration=1)[source]¶

Bases: spin_pulse.transpilation.instructions.pulse_instruction.PulseInstruction

Represent an idle (delay) operation applied to one or more qubits.

This instruction models the absence of active control during a time interval. It is used both for explicit delays in pulse scheduling and as a building block for dynamical decoupling sequences. The duration is expressed in time steps.

- name

Name of the instruction (“delay”).

Type:: str

- qubits

List of qubits on which the idle operation acts.

Type:: list[qiskit.circuit.Qubit]

- duration

Duration of the idle period in time steps.

Type:: int

Initialize an idle instruction on the specified qubits.

Parameters:

qubits (list[qiskit.circuit.Qubit]) – List of qubits where the idle operation is applied.
duration (int) – Duration of the idle period. Default is 1.

Returns:

The idle instruction is stored in the created object.

Return type:

None

name = 'delay'¶

adjust_duration(duration)[source]¶

Parameters:: duration (int)

plot(ax=None, t_start=0, label_gates=True)[source]¶

Plot the idle instruction as a flat line segment.

Parameters:

ax (matplotlib axis, optional) – Axis on which the idle segment is drawn. If None, the current axis is used.
t_start (int) – Starting time of the idle segment. Default is 0.
label_gates (bool) – Unused parameter kept for API compatibility. Default is True.

Returns:

The idle segment is drawn on the provided axis.

Return type:

None

to_hamiltonian()[source]¶

Convert the idle operation to its Hamiltonian representation.

The idle period corresponds to zero Hamiltonian evolution, resulting in no phase accumulation. This method returns a zero Hamiltonian and a zero frequency array compatible with the simulation interface.

Returns:: Array of zeros of length duration.
Return type:: ndarray

to_dynamical_decoupling(hardware_specs, mode=None)[source]¶

Expand the idle instruction into a dynamical decoupling sequence.

Depending on the hardware_specs dynamical decoupling mode, this method replaces the idle period with a sequence of rotations and shorter idle segments. Supported dynamical decoupling modes include:

SPIN_ECHO: Inserts two \(\pi\) rotations with symmetric idle periods.
FULL_DRIVE: Applies repeated \(2\pi\) rotations to average out noise.
None: Returns the idle instruction unchanged.

Parameters:

hardware_specs (HardwareSpecs) – Hardware configuration specifying the dynamical decoupling mode and available pulse shapes.
mode (spin_pulse.transpilation.dynamical_decoupling.DynamicalDecoupling | None)

Returns:

List of PulseInstruction objects implementing the chosen dynamical decoupling sequence.

Return type:

list[PulseInstruction]

class spin_pulse.transpilation.instructions.PulseInstruction(qubits, duration=1)[source]¶

Base class representing a pulse-level instruction applied to qubits.

This class defines the common interface for all pulse instructions, including rotation pulses and idle periods. Each instruction targets one or more qubits and spans a given discrete duration. Subclasses extend this class to implement specific pulse behaviors.

- name

Name identifying the type of pulse instruction.

Type:: str

- qubits

List of qubits on which the instruction acts.

Type:: list[qiskit.circuit.Qubit]

- num_qubits

Number of qubits targeted by the instruction.

Type:: int

- duration

Duration of the instruction in time steps.

Type:: int

Initialize a pulse instruction acting on the given qubits.

Parameters:

qubits (list[qiskit.circuit.Qubit]) – List of qubits on which the instruction is applied.
duration (int) – Duration of the instruction in time steps. Default is 1.

Returns:

The configured instruction is stored in the created object.

Return type:

None

name = '_name'¶

qubits¶

num_qubits¶

duration = 1¶

class spin_pulse.transpilation.instructions.GaussianRotationInstruction(name, qubits, amplitude, sign, coeff_duration, duration)[source]¶

Bases: RotationInstruction

Gaussian-shaped rotation pulse instruction.

This instruction implements a Gaussian pulse envelope centered in time, with width controlled by coeff_duration and amplitude chosen to generate a target rotation angle. The sign parameter controls the direction of the rotation.

- name

Name of the generating operator, for example “x”, “y”, “z”, or “Heisenberg”.

Type:: str

- qubits

List of qubits on which the rotation is applied.

Type:: list[qiskit.circuit.Qubit]

- num_qubits

Number of qubits targeted by the instruction.

Type:: int

- duration

Total duration of the pulse in time steps.

Type:: int

- amplitude

Peak amplitude of the Gaussian pulse.

Type:: float

- coeff_duration

Factor relating pulse duration to the Gaussian standard deviation.

Type:: float

- sign

Sign of the rotation, typically +1 or -1.

Type:: float

Initialize a Gaussian rotation pulse with given parameters.

The pulse is modeled as a Gaussian envelope with a peak amplitude given by amplitude, centered in the middle of the time window, and with a standard deviation derived from duration and coeff_duration.

Parameters:

name (str) – Name of the generating operator, for example “x”, “y”, “z”, or “Heisenberg”.
qubits (list[qiskit.circuit.Qubit]) – List of qubits on which the rotation is applied.
amplitude (float) – Peak amplitude of the Gaussian pulse.
sign (float) – Sign of the rotation, typically +1 or -1.
coeff_duration (float) – Factor used to set the Gaussian width sigma = duration / coeff_duration.
duration (int) – Total duration of the pulse in time steps.

Returns:

The Gaussian rotation instruction is stored in the created object.

Return type:

None

amplitude¶

coeff_duration¶

sign¶

classmethod from_angle(name, qubits, angle, hardware_specs)[source]¶

Build a Gaussian pulse that performs a target rotation angle.

A search over pulse duration is performed to find a configuration where the peak amplitude remains below the hardware field limit and the total integrated area matches the requested angle. The Gaussian width is controlled by hardware_specs.coeff_duration.

Parameters:

name (str) – Name of the generating operator, for example “x”, “y”, “z”, or “Heisenberg”.
qubits (list[qiskit.circuit.Qubit]) – List of qubits on which the rotation is applied.
angle (float) – Target rotation angle in radians.
hardware_specs (HardwareSpecs) – Hardware configuration providing maximum allowed field strengths and the duration coefficient.

Returns:

A Gaussian pulse instruction that performs the requested angle within the hardware limits.

Return type:

GaussianRotationInstruction

eval(t)[source]¶

Evaluate the Gaussian pulse envelope at the given time indices.

The envelope is defined as amplitude * sign * exp( - (t - t0)^2 / (2 * sigma^2) ).

where t0 is the center of the pulse window and sigma is given by duration/coeff_duration.

Parameters:: t (ndarray or array-like) – Discrete time indices at which the pulse envelope is evaluated.
Returns:: Pulse amplitudes at the specified time indices.
Return type:: ndarray

class spin_pulse.transpilation.instructions.RotationInstruction(name, qubits, duration)[source]¶

Bases: spin_pulse.transpilation.instructions.pulse_instruction.PulseInstruction

Base class for single- and two-qubit rotation pulse instructions.

A rotation instruction represents a shaped control pulse that generates a rotation around a given axis or interaction, such as x, y, z, or Heisenberg. Subclasses define the time-dependent envelope via the eval method and provide constructors from a target rotation angle.

- name

Label of the generating operator, for example “x”, “y”, “z”, or “Heisenberg”.

Type:: str

- qubits

List of qubits on which the rotation acts.

Type:: list[qiskit.circuit.Qubit]

- num_qubits

Number of qubits targeted by the instruction.

Type:: int

- duration

Duration of the pulse in time steps.

Type:: int

- amplitude

Optional amplitude parameter used to rescale the pulse envelope when adjusting the duration.

Type:: float

Initialize a rotation instruction with a given name and duration.

Parameters:

name (str) – Name of the generating operator, for example “x”, “y”, “z”, or “Heisenberg”.
qubits (list[qiskit.circuit.Qubit]) – List of qubits on which the rotation is applied.
duration (int) – Duration of the pulse in time steps.

Returns:

The rotation instruction is stored in the created object.

Return type:

None

name¶

classmethod from_angle(name, qubits, angle, hardware_specs)[source]¶

Abstractmethod:

Construct a rotation instruction from a target angle.

This class method must be implemented by subclasses to map a target rotation angle to a concrete pulse shape and duration, using the hardware specifications.

Parameters:

name (str) – Name of the generating operator, for example “x”, “y”, “z”, or “Heisenberg”.
qubits (list[qiskit.circuit.Qubit]) – List of qubits on which the rotation is applied.
angle (float) – Target rotation angle in radians.
hardware_specs (HardwareSpecs) – Hardware configuration used to determine pulse shape and duration.

Returns:

Instance of the subclass implementing the requested rotation.

Return type:

RotationInstruction

Raises:

NotImplementedError – If the method is not implemented in the subclass.

abstract eval(t)[source]¶

Evaluate the pulse envelope at the given time indices.

Subclasses must implement this method to return the pulse amplitude at each time step contained in the input array.

Parameters:: t (ndarray or array-like) – Discrete time indices at which the pulse envelope is evaluated.
Returns:: Pulse amplitudes at the specified time indices.
Return type:: ndarray
Raises:: NotImplementedError – If the method is not implemented in the subclass.

to_pulse()[source]¶

Return the full pulse envelope over the instruction duration.

The envelope is evaluated on the interval from 0 to duration-1. If the instruction has an attribute distort_factor, the pulse is corrected by an additional multiplicative factor.

Returns:: Pulse amplitudes over the full duration.
Return type:: ndarray

to_angle()[source]¶

Compute the effective rotation angle generated by the pulse.

The effective angle is taken as the sum of all pulse amplitudes over the duration of the instruction.

Returns:: Total rotation angle in radians.
Return type:: float

to_hamiltonian()[source]¶

Build the generator Hamiltonian associated with this rotation.

The method returns the static Hamiltonian matrix corresponding to the chosen generating operator, together with the time-dependent scalar coefficients given by the pulse envelope.

For example:

“x” uses the Pauli \(X\) operator.
“y” uses the Pauli \(Y\) operator.
“z” uses the Pauli \(Z\) operator.
“Heisenberg” uses the sum of \(XX\), \(YY\), and \(ZZ\) interactions.

Returns:

Tuple containing the Hamiltonian matrix of size \(2^n\) by \(2^n\), where \(n\) is the number of qubits, and the time-dependent coefficients defined by the pulse envelope.

Return type:

tuple(ndarray,ndarray)

adjust_duration(duration)[source]¶

Rescale the pulse amplitude to match a new duration.

The total rotation angle is preserved by adjusting the pulse amplitude after changing the duration. The method computes the original angle, sets a new duration, evaluates the new angle, and rescales the amplitude so that the final effective angle remains unchanged.

Parameters:: duration (int) – New duration of the pulse in time steps.
Returns:: The internal duration and amplitude are updated in place.
Return type:: None

plot(ax=None, t_start=0, label_gates=True)[source]¶

Plot the pulse envelope as a filled region.

The pulse is drawn over the interval from t_start to t_start + duration using a color that depends on the generating operator name. Optionally, a label containing the gate name and rotation angle is appended to the axis title.

Parameters:

ax (matplotlib axis, optional) – Axis on which to draw the pulse. If None, the current axis is used.
t_start (int) – Starting time index of the pulse on the plot. Default is 0.
label_gates (bool) – If True, appends a textual label with the gate name and rotation angle to the axis title. Default is True.

Returns:

The pulse envelope is drawn on the provided axis.

Return type:

None

class spin_pulse.transpilation.instructions.SquareRotationInstruction(name, qubits, amplitude, sign, ramp_duration, duration)[source]¶

Bases: RotationInstruction

Square-shaped rotation pulse with optional linear ramps.

This instruction implements a piecewise-linear pulse envelope composed of a rising ramp, a constant plateau, and a falling ramp. The total duration and amplitude determine the effective rotation angle. The sign parameter controls the direction of the rotation.

- name

Name of the generating operator, for example “x”, “y”, “z”, or “Heisenberg”.

Type:: str

- qubits

List of qubits on which the rotation is applied.

Type:: list[qiskit.circuit.Qubit]

- num_qubits

Number of qubits targeted by the instruction.

Type:: int

- duration

Total duration of the pulse in time steps.

Type:: int

- amplitude

Pulse amplitude during the plateau.

Type:: float

- sign

Sign of the rotation, typically +1 or -1.

Type:: float

- ramp_duration

Duration of each ramp region at the beginning and end of the pulse.

Type:: int

Initialize a square rotation pulse with ramps and plateau.

The pulse is defined by a linear ramp up, a constant-amplitude plateau, and a linear ramp down. The plateau duration is given by duration - 2 * ramp_duration and must be non-negative.

Parameters:

name (str) – Name of the generating operator, for example “x”, “y”, “z”, or “Heisenberg”.
qubits (list[qiskit.circuit.Qubit]) – List of qubits on which the rotation is applied.
amplitude (float) – Amplitude of the square plateau.
sign (float) – Sign of the rotation, typically +1 or -1.
ramp_duration (int) – Duration of each linear ramp region.
duration (int) – Total duration of the pulse in time steps.

Returns:

The square rotation instruction is stored in the created object.

Return type:

None

Raises:

ValueError – If the plateau duration is negative, i.e., duration < 2 * ramp_duration.

amplitude¶

sign¶

ramp_duration¶

duration¶

classmethod from_angle(name, qubits, angle, hardware_specs)[source]¶

Build a square pulse that performs a rotation of the target angle.

A binary search is used over the pulse duration to find a combination of duration and amplitude that matches the requested angle while respecting the hardware field limits specified in hardware_specs. The procedure starts from the minimal duration compatible with the ramp time and iteratively refines the duration.

Parameters:

name (str) – Name of the generating operator, for example “x”, “y”, “z”, or “Heisenberg”.
qubits (list[qiskit.circuit.Qubit]) – List of qubits on which the rotation is applied.
angle (float) – Target rotation angle in radians.
hardware_specs (HardwareSpecs) – Hardware configuration providing ramp duration and maximum allowed field strengths.

Returns:

A square pulse instruction that performs the requested rotation with the target angle within the hardware limits.

Return type:

SquareRotationInstruction

eval(t)[source]¶

Evaluate the square pulse envelope at the given time indices.

The envelope is composed of:

a linear rise from 0 to the target amplitude during the first ramp,
a constant plateau with full amplitude,
a symmetric linear fall back to 0 during the final ramp.

If ramp_duration is zero, a pure square pulse with constant height is returned over the whole duration.

Parameters:: t (ndarray or array-like) – Discrete time indices at which the pulse envelope is evaluated.
Returns:: Pulse amplitudes at the specified time indices.
Return type:: ndarray