3.1.2. qupulse._program package¶
3.1.2.1. Submodules¶
3.1.2.2. qupulse._program._loop module¶
-
class
qupulse._program._loop.
Loop
(parent=None, children=[], waveform=None, measurements=None, repetition_count=1)[source]¶ Bases:
qupulse.utils.tree.Node
-
MAX_REPR_SIZE
= 2000¶ Build a loop tree. The leaves of the tree are loops with one element.
-
compare_key
¶ Implements
compare_key
.Return type: Tuple
-
flatten_and_balance
(depth)[source]¶ Modifies the program so all tree branches have the same depth :type depth:
int
:param depth: Target depth of the program :rtype:None
:return:
-
3.1.2.3. qupulse._program.instructions module¶
This module defines the abstract hardware instruction model of qupulse.
- Classes:
- Trigger: Representation of a hardware trigger.
- Instruction: Base class for hardware instructions.
- CJMPInstruction: Conditional jump instruction.
- REPJInstruction: Repetition jump instruciton.
- EXECInstruction: Instruction to execute a waveform.
- GOTOInstruction: Unconditional jump instruction.
- STOPInstruction: Instruction which indicates the end of execution.
- AbstractInstructionBlock: A block of instructions (abstract base class)
- InstructionBlock: A mutable block of instructions to which instructions can be added
- ImmutableInstructionBlock: An immutable InstructionBlock
- InstructionSequence: A single final sequence of instructions.
- InstructionPointer: References an instruction’s location in a sequence.
-
class
qupulse._program.instructions.
Trigger
[source]¶ Bases:
qupulse.comparable.Comparable
Abstract representation of a hardware trigger for hardware based branching decisions.
-
compare_key
¶ Implements
compare_key
.Return type: Any
-
-
class
qupulse._program.instructions.
InstructionPointer
(block, offset=0)[source]¶ Bases:
qupulse.comparable.Comparable
Reference to the location of an instruction used in expressing targets of jumps.
The target instruction is referenced by the instruction block it resides in and its offset within this block.
Create a new InstructionPointer instance.
Parameters: - block (
AbstractInstructionBlock
) – The instruction block the referenced instruction resides in. - offset (
int
) – The position/offset of the referenced instruction in its block.
Raises: ValueError
– If offset is negative-
__init__
(block, offset=0)[source]¶ Create a new InstructionPointer instance.
Parameters: - block (
AbstractInstructionBlock
) – The instruction block the referenced instruction resides in. - offset (
int
) – The position/offset of the referenced instruction in its block.
Raises: ValueError
– If offset is negativeReturn type: None
- block (
-
block
¶ The instruction block containing the referenced instruction.
Return type: AbstractInstructionBlock
-
compare_key
¶ Implements
compare_key
.Return type: Any
- block (
-
class
qupulse._program.instructions.
Instruction
[source]¶ Bases:
qupulse.comparable.Comparable
A hardware instruction.
-
class
qupulse._program.instructions.
CJMPInstruction
(trigger, target)[source]¶ Bases:
qupulse._program.instructions.Instruction
A conditional jump hardware instruction.
Will cause the execution to jump to the instruction indicated by the InstructionPointer held by this CJMPInstruction if the given Trigger was fired. If not, this Instruction will have no effect, the execution will continue with the following.
Create a new CJMPInstruction object.
Parameters: - trigger (Trigger) – Representation of the hardware trigger which controls whether the conditional jump occurs or not.
- target (InstructionPointer) – Instruction pointer referencing the instruction targeted by the conditional jump.
-
__init__
(trigger, target)[source]¶ Create a new CJMPInstruction object.
Parameters: - trigger (Trigger) – Representation of the hardware trigger which controls whether the conditional jump occurs or not.
- target (InstructionPointer) – Instruction pointer referencing the instruction targeted by the conditional jump.
Return type: None
-
compare_key
¶ Implements
compare_key
.Return type: Any
-
class
qupulse._program.instructions.
EXECInstruction
(waveform)[source]¶ Bases:
qupulse._program.instructions.Instruction
An instruction to execute/play back a waveform.
Create a new EXECInstruction object.
Parameters: waveform ( Waveform
) – The waveform that will be executed by this instruction.-
__init__
(waveform)[source]¶ Create a new EXECInstruction object.
Parameters: waveform ( Waveform
) – The waveform that will be executed by this instruction.Return type: None
-
compare_key
¶ Implements
compare_key
.Return type: Waveform
-
-
class
qupulse._program.instructions.
GOTOInstruction
(target)[source]¶ Bases:
qupulse._program.instructions.Instruction
An unconditional jump hardware instruction.
Will cause the execution to jump to the instruction indicated by the InstructionPointer held by this GOTOInstruction.
Create a new GOTOInstruction object.
Parameters: target (InstructionPointer) – Instruction pointer referencing the instruction targeted by the unconditional jump. -
__init__
(target)[source]¶ Create a new GOTOInstruction object.
Parameters: target (InstructionPointer) – Instruction pointer referencing the instruction targeted by the unconditional jump. Return type: None
-
compare_key
¶ Implements
compare_key
.Return type: Any
-
-
class
qupulse._program.instructions.
STOPInstruction
[source]¶ Bases:
qupulse._program.instructions.Instruction
An instruction which indicates the end of the program.
Create a new STOPInstruction object.
-
compare_key
¶ Implements
compare_key
.Return type: Any
-
-
class
qupulse._program.instructions.
REPJInstruction
(count, target)[source]¶ Bases:
qupulse._program.instructions.Instruction
A repetition jump instruction.
Will cause the execution to jump to the instruction indicated by the InstructionPointer held by this REPJInstruction for the first n times this REPJInstruction is encountered, where n is a parameter.
Create a new REPJInstruction object.
Parameters: - count (int) – A positive integer indicating how often the repetition jump is triggered.
- target (InstructionPointer) – Instruction pointer referencing the instruction targeted by the repetition jump.
Raises: ValueError, if count is a negative number.
-
__init__
(count, target)[source]¶ Create a new REPJInstruction object.
Parameters: - count (int) – A positive integer indicating how often the repetition jump is triggered.
- target (InstructionPointer) – Instruction pointer referencing the instruction targeted by the repetition jump.
Raises: ValueError, if count is a negative number.
Return type: None
-
compare_key
¶ Implements
compare_key
.Return type: Any
-
class
qupulse._program.instructions.
AbstractInstructionBlock
[source]¶ Bases:
qupulse.comparable.Comparable
“Abstract base class of a block of instructions representing a (sub)sequence in the control flow of a pulse template instantiation.
Because of included jump instructions, instruction blocks typically form a “calling” hierarchy. Due to how the sequencing process works, this hierarchy will typically resemble the pulse template from which it was translated closely.
An instruction block might define a return instruction pointer specifying to which instruction the control flow should return after execution of the block has finished.
Instruction blocks define the item access and the iterable interface to allow access to the contained instructions. When using these interfaces, a final stop or goto instruction is automatically added after the regular instructions according to whether a return instruction pointer was set or not (to return control flow to a calling block or stop the execution). Consequently, the len() operation includes this additional instruction in the returned length.
The property “instructions” allows access to the contained instructions without the additional stop/goto instruction mentioned above.
See also
InstructionBlock ImmutableInstructionBlock
Create a new AbstractInstructionBlock instance.
-
compare_key
¶ Implements
compare_key
.Return type: Any
-
instructions
¶ The instructions contained in this block (excluding a final stop or return goto).
Return type: Sequence
[Instruction
]
-
return_ip
¶ The return instruction pointer indicating the instruction to which the control flow shall return after exection of this instruction block has finished.
Return type: Optional
[InstructionPointer
]
-
-
class
qupulse._program.instructions.
InstructionBlock
[source]¶ Bases:
qupulse._program.instructions.AbstractInstructionBlock
A block of instructions representing a (sub)sequence in the control flow of a pulse template instantiation.
Because of included jump instructions, instruction blocks typically form a “calling” hierarchy. Due to how the sequencing process works, this hierarchy will typically resemble the pulse template from which it was translated closely.
An instruction block might define a return instruction pointer specifying to which instruction the control flow should return after execution of the block has finished.
Instruction blocks define the item access and the iterable interface to allow access to the contained instructions. When using these interfaces, a final stop or goto instruction is automatically added after the regular instructions according to whether a return instruction pointer was set or not (to return control flow to a calling block or stop the execution). Consequently, the len() operation includes this additional instruction in the returned length.
The property “instructions” allows access to the contained instructions without the additional stop/goto instruction mentioned above.
Create a new InstructionBlock instance.
-
add_instruction
(instruction)[source]¶ Append an instruction at the end of this instruction block.
Parameters: instruction (Instruction) – The instruction to append. Return type: None
-
add_instruction_chan
(channel_to_instruction)[source]¶ Create and append a new CHANInstruction at the end of this instruction block.
Return type: None
-
add_instruction_cjmp
(trigger, target_block)[source]¶ Create and append a new CJMPInstruction object at the end of this instruction block.
Parameters: - trigger (Trigger) – The hardware trigger that will control the new CJMPInstruction.
- target_block (InstructionBlock) – The instruction block the new CJMPInstruction will jump to. Execution will begin at the start of that block, i.e., the offset of the instruction pointer of the CJMPInstruction will be zero.
Return type: None
-
add_instruction_exec
(waveform)[source]¶ Create and append a new EXECInstruction object for the given waveform at the end of this instruction block.
Parameters: waveform (Waveform) – The Waveform object referenced by the new EXECInstruction. Return type: None
-
add_instruction_goto
(target_block)[source]¶ Create and append a new GOTOInstruction object with a given target block at the end of this instruction block.
Parameters: target_block (InstructionBlock) – The instruction block the new GOTOInstruction will jump to. Execution will begin at the start of that block, i.e., the offset of the instruction pointer of the GOTOInstruction will be zero. Return type: None
-
add_instruction_meas
(measurements)[source]¶ Create and append a MEASInstruction at the end of the instruction block.
Parameters: measurements ( List
[Tuple
[str
,Real
,Real
]]) – The measurement windows this instruction causes
-
add_instruction_repj
(count, target_block)[source]¶ Create and append a new REPJInstruction object at the end of this instruction block.
Parameters: - count (int) – The amount of repetitions of the new REPJInstruction.
- target_block (InstructionBlock) – The instruction block the new REPJInstruction will jump to. Execution will begin at the start of that block, i.e., the offset of the instruction pointer of the REPJInstruction will be zero.
Return type: None
-
add_instruction_stop
()[source]¶ Create and append a new STOPInstruction object at the end of this instruction block.
Return type: None
-
instructions
¶ Implements
instructions
.Return type: List
[Instruction
]
-
return_ip
¶ Implements
return_ip
.Return type: InstructionPointer
-
-
class
qupulse._program.instructions.
ImmutableInstructionBlock
(block, context=None)[source]¶ Bases:
qupulse._program.instructions.AbstractInstructionBlock
An immutable instruction block which cannot be altered.
See also
InstructionBlock
Create a new ImmutableInstructionBlock hierarchy from a (mutable) InstructionBlock hierarchy.
Will create a deep copy (including all embedded blocks) of the given instruction block.
Parameters: - block (AbstractInstructionBlock) – The instruction block that will be copied into an immutable one.
- context (Dict(AbstractInstructionBlock -> ImmutableInstructionBlock)) – A dictionary to look up already existing conversions of instruction blocks. Required to resolve return instruction pointers. Will be altered by the process.
-
__init__
(block, context=None)[source]¶ Create a new ImmutableInstructionBlock hierarchy from a (mutable) InstructionBlock hierarchy.
Will create a deep copy (including all embedded blocks) of the given instruction block.
Parameters: - block (AbstractInstructionBlock) – The instruction block that will be copied into an immutable one.
- context (Dict(AbstractInstructionBlock -> ImmutableInstructionBlock)) – A dictionary to look up already existing conversions of instruction blocks. Required to resolve return instruction pointers. Will be altered by the process.
Return type: None
-
instructions
¶ Implements
instructions
.Return type: Tuple
[Instruction
, …]
-
return_ip
¶ Implements
return_ip
.Return type: InstructionPointer
3.1.2.4. qupulse._program.transformation module¶
-
class
qupulse._program.transformation.
ChainedTransformation
(*transformations)[source]¶ Bases:
qupulse._program.transformation.Transformation
-
chain
(next_transformation)[source]¶ Return type: ChainedTransformation
-
compare_key
¶ Implements
compare_key
.Return type: Tuple
[Transformation
, …]
-
get_input_channels
(output_channels)[source]¶ Implements
get_input_channels()
.Return type: Set
[Union
[str
,int
]]
-
get_output_channels
(input_channels)[source]¶ Implements
get_output_channels()
.Return type: Set
[Union
[str
,int
]]
-
transformations
¶ Return type: Tuple
[Transformation
, …]
-
-
class
qupulse._program.transformation.
IdentityTransformation
[source]¶ Bases:
qupulse._program.transformation.Transformation
-
chain
(next_transformation)[source]¶ Return type: Transformation
-
compare_key
¶ Implements
compare_key
.Return type: None
-
-
class
qupulse._program.transformation.
LinearTransformation
(transformation_matrix, input_channels, output_channels)[source]¶ Bases:
qupulse._program.transformation.Transformation
Parameters: transformation_matrix ( ndarray
) – columns are input and index are output channels-
__init__
(transformation_matrix, input_channels, output_channels)[source]¶ Parameters: transformation_matrix ( ndarray
) – columns are input and index are output channels
-
compare_key
¶ Implements
compare_key
.Return type: Tuple
[Tuple
[Union
[str
,int
]],Tuple
[Union
[str
,int
]],bytes
]
-
-
class
qupulse._program.transformation.
ParallelConstantChannelTransformation
(channels)[source]¶ Bases:
qupulse._program.transformation.Transformation
Set channel values to given values regardless their former existence
Parameters: channels ( Mapping
[Union
[str
,int
],Real
]) –-
__init__
(channels)[source]¶ Set channel values to given values regardless their former existence
Parameters: channels ( Mapping
[Union
[str
,int
],Real
]) –
-
-
class
qupulse._program.transformation.
Transformation
[source]¶ Bases:
qupulse.comparable.Comparable
-
chain
(next_transformation)[source]¶ Return type: Transformation
-
-
qupulse._program.transformation.
chain_transformations
(*transformations)[source]¶ Return type: Transformation
3.1.2.5. qupulse._program.waveforms module¶
This module contains all waveform classes
- Classes:
- Waveform: An instantiated pulse which can be sampled to a raw voltage value array.
-
class
qupulse._program.waveforms.
Waveform
[source]¶ Bases:
qupulse.comparable.Comparable
Represents an instantiated PulseTemplate which can be sampled to retrieve arrays of voltage values for the hardware.
-
defined_channels
¶ The channels this waveform should played on. Use
get_measurement_windows()
to get a waveform for a subset of these.Return type: Set
[Union
[str
,int
]]
-
get_sampled
(channel, sample_times, output_array=None)[source]¶ A wrapper to the unsafe_sample method which caches the result. This method enforces the constrains unsafe_sample expects and caches the result to save memory.
- Args/Result:
sample_times: Times at which this Waveform will be sampled. output_array: Has to be either None or an array of the same size and type as sample_times.
If an array is given, the sampled values will be written into the given array and it will be returned. Otherwise, a new array will be created and cached to save memory.- Result:
- The sampled values of this Waveform at the provided sample times.
Return type: ndarray
-
get_subset_for_channels
(channels)[source]¶ Get a waveform that only describes the channels contained in channels.
Parameters: channels ( Set
[Union
[str
,int
]]) – A channel set the return value should confine to.Raises: KeyError
– If channels is not a subset of the waveform’s defined channels.Return type: Waveform
Returns: A waveform with waveform.defined_channels == channels
-
unsafe_get_subset_for_channels
(channels)[source]¶ Unsafe version of
get_measurement_windows()
.Return type: Waveform
-
unsafe_sample
(channel, sample_times, output_array=None)[source]¶ Sample the waveform at given sample times.
The unsafe means that there are no sanity checks performed. The provided sample times are assumed to be monotonously increasing and lie in the range of [0, waveform.duration]
Parameters: - sample_times (
ndarray
) – Times at which this Waveform will be sampled. - output_array (
Optional
[ndarray
]) – Has to be either None or an array of the same size and type as sample_times. If not None, the sampled values will be written here and this array will be returned
- Result:
- The sampled values of this Waveform at the provided sample times. Has the same number of elements as sample_times.
Return type: ndarray
- sample_times (
-
-
class
qupulse._program.waveforms.
TableWaveform
(channel, waveform_table)[source]¶ Bases:
qupulse._program.waveforms.Waveform
Create a new TableWaveform instance.
Parameters: waveform_table (ImmutableList(WaveformTableEntry)) – A list of instantiated table entries of the form (time as float, voltage as float, interpolation strategy). -
EntryInInit
= typing.Union[qupulse._program.waveforms.TableWaveformEntry, typing.Tuple[float, float, qupulse.pulses.interpolation.InterpolationStrategy]]¶ Waveform obtained from instantiating a TablePulseTemplate.
-
__init__
(channel, waveform_table)[source]¶ Create a new TableWaveform instance.
Parameters: waveform_table (ImmutableList(WaveformTableEntry)) – A list of instantiated table entries of the form (time as float, voltage as float, interpolation strategy). Return type: None
-
compare_key
¶ Implements
compare_key
.Return type: Any
-
unsafe_get_subset_for_channels
(channels)[source]¶ Implements
unsafe_get_subset_for_channels()
.Return type: Waveform
-
unsafe_sample
(channel, sample_times, output_array=None)[source]¶ Implements
unsafe_sample()
.Return type: ndarray
-
-
class
qupulse._program.waveforms.
TableWaveformEntry
(t, v, interp)[source]¶ Bases:
qupulse._program.waveforms.TableWaveformEntry
Create new instance of TableWaveformEntry(t, v, interp)
-
class
qupulse._program.waveforms.
FunctionWaveform
(expression, duration, channel)[source]¶ Bases:
qupulse._program.waveforms.Waveform
Waveform obtained from instantiating a FunctionPulseTemplate.
Creates a new FunctionWaveform instance.
Parameters: - expression (
ExpressionScalar
) – The function represented by this FunctionWaveform as a mathematical expression where ‘t’ denotes the time variable. It must not have other variables - duration (
float
) – The duration of the waveform - measurement_windows – A list of measurement windows
- channel (
Union
[str
,int
]) – The channel this waveform is played on
-
__init__
(expression, duration, channel)[source]¶ Creates a new FunctionWaveform instance.
Parameters: - expression (
ExpressionScalar
) – The function represented by this FunctionWaveform as a mathematical expression where ‘t’ denotes the time variable. It must not have other variables - duration (
float
) – The duration of the waveform - measurement_windows – A list of measurement windows
- channel (
Union
[str
,int
]) – The channel this waveform is played on
Return type: None
- expression (
-
compare_key
¶ Implements
compare_key
.Return type: Any
-
unsafe_get_subset_for_channels
(channels)[source]¶ Implements
unsafe_get_subset_for_channels()
.Return type: Waveform
-
unsafe_sample
(channel, sample_times, output_array=None)[source]¶ Implements
unsafe_sample()
.Return type: ndarray
- expression (
-
class
qupulse._program.waveforms.
SequenceWaveform
(sub_waveforms)[source]¶ Bases:
qupulse._program.waveforms.Waveform
This class allows putting multiple PulseTemplate together in one waveform on the hardware.
Parameters: subwaveforms – All waveforms must have the same defined channels -
__init__
(sub_waveforms)[source]¶ Parameters: subwaveforms – All waveforms must have the same defined channels
-
compare_key
¶ Implements
compare_key
.Return type: Tuple
[Waveform
]
-
unsafe_get_subset_for_channels
(channels)[source]¶ Implements
unsafe_get_subset_for_channels()
.Return type: Waveform
-
unsafe_sample
(channel, sample_times, output_array=None)[source]¶ Implements
unsafe_sample()
.Return type: ndarray
-
-
class
qupulse._program.waveforms.
MultiChannelWaveform
(sub_waveforms)[source]¶ Bases:
qupulse._program.waveforms.Waveform
A MultiChannelWaveform is a Waveform object that allows combining arbitrary Waveform objects to into a single waveform defined for several channels.
The number of channels used by the MultiChannelWaveform object is the sum of the channels used by the Waveform objects it consists of.
MultiChannelWaveform allows an arbitrary mapping of channels defined by the Waveforms it consists of and the channels it defines. For example, if the MultiChannelWaveform consists of a two Waveform objects A and B which define two channels each, then the channels of the MultiChannelWaveform may be 0: A.1, 1: B.0, 2: B.1, 3: A.0 where A.0 means channel 0 of Waveform object A.
- The following constraints must hold:
- The durations of all Waveform objects must be equal.
- The channel mapping must be sane, i.e., no channel of the MultiChannelWaveform must be
- assigned more than one channel of any Waveform object it consists of
Create a new MultiChannelWaveform instance.
Requires a list of subwaveforms in the form (Waveform, List(int)) where the list defines the channel mapping, i.e., a value y at index x in the list means that channel x of the subwaveform will be mapped to channel y of this MultiChannelWaveform object.
Parameters: sub_waveforms (Iterable( Waveform )) – The list of sub waveforms of this MultiChannelWaveform
Raises: - ValueError, if a channel mapping is out of bounds of the channels defined by this – MultiChannelWaveform
- ValueError, if several subwaveform channels are assigned to a single channel of this – MultiChannelWaveform
- ValueError, if subwaveforms have inconsistent durations
-
__init__
(sub_waveforms)[source]¶ Create a new MultiChannelWaveform instance.
Requires a list of subwaveforms in the form (Waveform, List(int)) where the list defines the channel mapping, i.e., a value y at index x in the list means that channel x of the subwaveform will be mapped to channel y of this MultiChannelWaveform object.
Parameters: sub_waveforms (Iterable( Waveform )) – The list of sub waveforms of this MultiChannelWaveform
Raises: - ValueError, if a channel mapping is out of bounds of the channels defined by this – MultiChannelWaveform
- ValueError, if several subwaveform channels are assigned to a single channel of this – MultiChannelWaveform
- ValueError, if subwaveforms have inconsistent durations
Return type: None
-
compare_key
¶ Implements
compare_key
.Return type: Any
-
unsafe_get_subset_for_channels
(channels)[source]¶ Implements
unsafe_get_subset_for_channels()
.Return type: Waveform
-
unsafe_sample
(channel, sample_times, output_array=None)[source]¶ Implements
unsafe_sample()
.Return type: ndarray
-
class
qupulse._program.waveforms.
RepetitionWaveform
(body, repetition_count)[source]¶ Bases:
qupulse._program.waveforms.Waveform
This class allows putting multiple PulseTemplate together in one waveform on the hardware.
-
compare_key
¶ Implements
compare_key
.Return type: Tuple
[Any
,int
]
-
unsafe_get_subset_for_channels
(channels)[source]¶ Implements
unsafe_get_subset_for_channels()
.Return type: RepetitionWaveform
-
unsafe_sample
(channel, sample_times, output_array=None)[source]¶ Implements
unsafe_sample()
.Return type: ndarray
-
-
class
qupulse._program.waveforms.
TransformingWaveform
(inner_waveform, transformation)[source]¶ Bases:
qupulse._program.waveforms.Waveform
-
compare_key
¶ Implements
compare_key
.Return type: Tuple
[Waveform
,Transformation
]
-
transformation
¶ Return type: Transformation
-
unsafe_get_subset_for_channels
(channels)[source]¶ Implements
unsafe_get_subset_for_channels()
.Return type: SubsetWaveform
-
unsafe_sample
(channel, sample_times, output_array=None)[source]¶ Implements
unsafe_sample()
.Return type: ndarray
-