3.5.3. qupulse.program.protocol

Definition of the program builder protocol.

Classes

BaseProgramBuilder([initial_context, ...])

Helper base class for program builder to reduce code duplication.

BuildContext([scope, measurement_mapping, ...])

This dataclass bundles the mutable context information during the build.

BuildSettings(to_single_waveform)

This dataclass bundles the immutable settings.

Program(*args, **kwargs)

This protocol is used to inspect and or manipulate programs.

ProgramBuilder(*args, **kwargs)

This protocol is used by PulseTemplate.create_program() to build a program via a variation of the visitor pattern.
class BaseProgramBuilder(initial_context: BuildContext = None, initial_settings: BuildSettings = None)[source]

Bases: ProgramBuilder, ABC

Helper base class for program builder to reduce code duplication. The interface is defined by ProgramBuilder.

This class provides shared functionality for context and settings and correct transformation handling.

property build_context: BuildContext

Get the current build context.

property build_settings: BuildSettings

Get the current build settings

hold_voltage(duration: TimeType | DynamicLinearValue[TimeType], voltages: Mapping[str, float | DynamicLinearValue[float]])[source]

Hold the specified voltage for a given time. Advances the current time by duration. The values are hardware dependent type which are inserted into the parameter scope via ProgramBuilder.with_iteration().

Parameters:

  • duration – Duration of voltage hold

  • voltages – Voltages for each channel

override(scope: Scope = None, measurement_mapping: Mapping[str, str | None] | None = None, channel_mapping: Mapping[str | int, str | int | None] | None = None, global_transformation: Transformation | None = None, to_single_waveform: AbstractSet[str | PulseTemplate] = None)[source]

Override the non-None values in context and settings

play_arbitrary_waveform(waveform: Waveform)[source]

Insert the playback of an arbitrary waveform. If possible pulse templates should use more specific commands like ProgramBuilder.hold_voltage() (the only more specific command at the time of this writing).

Parameters:

waveform – The waveform to play

with_mappings(*, parameter_mapping: Mapping[str, Expression], measurement_mapping: Mapping[str, str | None], channel_mapping: Mapping[str | int, str | int | None])[source]

Modify the build context for the duration of the context manager.

Parameters:

  • parameter_mapping – A mapping of parameter names to expressions.

  • measurement_mapping – A mapping of measurement names to measurement names or None.

  • channel_mapping – A mapping of channel IDs to channel IDs or None.

with_metadata(metadata: TemplateMetadata)[source]

Modify the build context for the duration of the context manager.

with_transformation(transformation: Transformation)[source]

Modify the build context for the duration of the context manager.

class BuildContext(scope: Scope = None, measurement_mapping: Mapping[str, str | None] = None, channel_mapping: Mapping[str | int, str | int | None] = None, transformation: Transformation | None = None, minimal_sample_rate: TimeType | None = None)[source]

Bases: object

This dataclass bundles the mutable context information during the build.

apply_mappings(parameter_mapping: Mapping[str, Expression] = None, measurement_mapping: Mapping[str, str | None] = None, channel_mapping: Mapping[str | int, str | int | None] = None) → BuildContext[source]
channel_mapping: Mapping[str | int, str | int | None] = None
measurement_mapping: Mapping[str, str | None] = None
minimal_sample_rate: TimeType | None = None
scope: Scope = None
transformation: Transformation | None = None
class BuildSettings(to_single_waveform: AbstractSet[str | object])[source]

Bases: object

This dataclass bundles the immutable settings.

to_single_waveform: AbstractSet[str | object]
class Program(*args, **kwargs)[source]

Bases: Protocol

This protocol is used to inspect and or manipulate programs. As you can see the functionality is very limited because most of a program class’ capability are specific to the implementation.

abstract property duration: TimeType

The duration of the program in nanoseconds.

abstractmethod get_defined_channels() → AbstractSet[str | int][source]

Get the set of channels that are used in this program.

class ProgramBuilder(*args, **kwargs)[source]

Bases: Protocol

This protocol is used by PulseTemplate.create_program() to build a program via a variation of the visitor pattern.

The pulse templates call the methods that correspond to their functionality on the program builder. For example, ConstantPulseTemplate translates itself into a simple ProgramBuilder.hold_voltage() call while SequencePulseTemplate uses ProgramBuilder.with_sequence() to signify a logical unit with attached measurements and passes the resulting object to the sequenced sub-templates.

Due to backward compatibility, the handling of measurements is a bit weird since they have to be omitted in certain cases. However, this is not relevant for HDAWG specific implementations because these are expected to ignore ProgramBuilder.measure() calls.

This interface makes heavy use of context managers and generators/iterators which allows for flexible iteration and repetition implementation.

abstract property build_context: BuildContext

Get the current build context.

abstract property build_settings: BuildSettings

Get the current build settings

abstractmethod hold_voltage(duration: TimeType | DynamicLinearValue[TimeType], voltages: Mapping[str, float | DynamicLinearValue[float]])[source]

Hold the specified voltage for a given time. Advances the current time by duration. The values are hardware dependent type which are inserted into the parameter scope via ProgramBuilder.with_iteration().

Parameters:

  • duration – Duration of voltage hold

  • voltages – Voltages for each channel

abstractmethod measure(measurements: Sequence[Tuple[str, Real, Real]] | None)[source]

Unconditionally add given measurements relative to the current position.

Parameters:

measurements – Measurements to add.

abstractmethod new_subprogram() → ContextManager[ProgramBuilder][source]

Create a context managed program builder whose contents are translated into a single waveform upon exit if it is not empty.

Returns:

A context manager that returns a ProgramBuilder on entering.

abstractmethod override(scope: Scope = None, measurement_mapping: Mapping[str, str | None] | None = None, channel_mapping: Mapping[str | int, str | int | None] | None = None, global_transformation: Transformation | None = None, to_single_waveform: AbstractSet[str | object] = None)[source]

Override the non-None values in context and settings

abstractmethod play_arbitrary_waveform(waveform: Waveform)[source]

Insert the playback of an arbitrary waveform. If possible pulse templates should use more specific commands like ProgramBuilder.hold_voltage() (the only more specific command at the time of this writing).

Parameters:

waveform – The waveform to play

abstractmethod time_reversed() → ContextManager[ProgramBuilder][source]

This returns a new context manager that will reverse everything added to it in time upon exit.

Returns:

A context manager that returns a ProgramBuilder on entering.

abstractmethod to_program() → Program | None[source]

Generate the final program. This is allowed to invalidate the program builder.

Returns:

A program implementation. None if nothing was added to this program builder.

abstractmethod with_iteration(index_name: str, rng: range, measurements: Sequence[Tuple[str, Real, Real]] | None = None) → Iterable[ProgramBuilder][source]

Create an iterable that represent the body of the iteration. This can be an iterable with an element for each step in the iteration or a single object that represents the complete iteration.

Parameters:

  • index_name – The name of index

  • rng – The range if the index

  • measurements – Measurements to add iff the iteration body is not empty.

abstractmethod with_mappings(*, parameter_mapping: Mapping[str, Expression], measurement_mapping: Mapping[str, str | None], channel_mapping: Mapping[str | int, str | int | None]) → ContextManager[ProgramBuilder][source]

Modify the build context for the duration of the context manager.

Parameters:

  • parameter_mapping – A mapping of parameter names to expressions.

  • measurement_mapping – A mapping of measurement names to measurement names or None.

  • channel_mapping – A mapping of channel IDs to channel IDs or None.

abstractmethod with_metadata(metadata: TemplateMetadata) → ContextManager[ProgramBuilder][source]

Modify the build context for the duration of the context manager.

abstractmethod with_repetition(repetition_count: int | VolatileRepetitionCount | DynamicLinearValue[int], measurements: Sequence[Tuple[str, Real, Real]] | None = None) → Iterable[ProgramBuilder][source]

Start a new repetition context with given repetition count. The caller has to iterate over the return value and call :py:meth:.ProgramBuilder.inner_scope` inside the iteration context.

Parameters:

  • repetition_count – Repetition count

  • measurements – These measurements are added relative to the position at the start of the iteration iff the iteration is not empty.

Returns:

An iterable of ProgramBuilder instances.

abstractmethod with_sequence(measurements: Sequence[Tuple[str, Real, Real]] | None = None) → ContextManager[ProgramBuilder][source]

Start a new sequence context. The caller has to enter the returned context manager and add the sequenced elements there.

Measurements that are added in to the returned program builder are discarded if the sequence is empty on exit.

Parameters:

  • measurements – These measurements are added relative to the position at the start of the sequence iff the

  • empty. (sequence is not)

Returns:

A context manager that returns a ProgramBuilder on entering.

abstractmethod with_transformation(transformation: Transformation) → ContextManager[ProgramBuilder][source]

Modify the build context for the duration of the context manager.