Arbitrary Waveform Generator (AWG)¤
This category ships in the instro-unstable package (instro[unstable]); its API is not settled and may change without notice.
Errors raised by these methods are documented in Exceptions.
Interface¤
Bases: Instrument
AWG instrument. Methods return Measurement/Command for publishing.
property
writable
¤
background_interval
Seconds between background daemon iterations (0 = no wait).
property
¤
Return an insertion-ordered snapshot of all published channel names.
Names are complete after one full daemon iteration: {name}.loop_time publishes every iteration, so call get_channel("loop_time", wait_for_new_samples=True) then read channel_names to ensure the complete set has arrived.
Raises:
-
RuntimeError–No background buffer;
start()was not called.
add_publisher(publisher: Publisher)
Register a publisher to receive this instrument's Measurement/Command data.
publish(data: Measurement | Command, **kwargs)
Fan data out to every configured publisher; kwargs pass through.
add_background_daemon_function(method: Callable, *args, **kwargs)
Append method to the daemon's call list. Use define_background_daemon to replace instead.
get_channel(
channel_name: str,
length: int = 1,
wait_for_new_samples: bool = False,
timeout: float = 10.0,
) -> Measurement
Return the most recent length samples for channel_name from the in-memory buffer.
If the channel does not exist yet, or no sample is available, the code will always block until timeout expires.
Parameters:
-
(channel_name¤str) –Name of the channel to retrieve.
-
(length¤int, default:1) –Number of trailing samples to return.
-
(wait_for_new_samples¤bool, default:False) –Block until at least
lengthnew values arrive. -
(timeout¤float, default:10.0) –Seconds to wait when insufficient data exists or
wait_for_new_samples=True.
Raises:
-
RuntimeError–No background buffer;
start()was not called. -
ChannelNotFoundError–channel had no values and no data appeared before
timeout.wait_for_new_samples=Trueand channel did not appear withintimeout. -
ChannelValueTimeoutError–wait_for_new_samples=Trueand values did not arrive withintimeout.
get_single_channel_value(channel_name: str) -> float | None
Return the most recent sample for channel_name from the in-memory buffer.
This will not wait, if data is not available then None is returned.
Parameters:
Raises:
-
RuntimeError–No background buffer;
start()was not called.
define_background_daemon(method: Callable, *args, **kwargs)
Replace all daemon functions with a single method (called with the given args).
Program channel with a waveform.
Read back the current waveform definition on channel.
set_amplitude(
channel: int,
amplitude: float,
unit: AmplitudeMeasurementUnit,
**kwargs,
) -> Command
Set the output amplitude on channel.
get_amplitude(channel: int) -> tuple[float, AmplitudeMeasurementUnit]
Read back the current amplitude and its measurement unit on channel.
convert_amplitude(
channel: int,
amplitude: float,
from_unit: AmplitudeMeasurementUnit,
to_unit: AmplitudeMeasurementUnit,
impedance_ohms: float | None = None,
) -> float
Convert an amplitude value between units using channel's configured waveform.
DBM conversions need a load impedance; if impedance_ohms isn't given, channel's
output load is used instead. Raises ValueError if neither is available.
Set the DC offset (volts) on channel.
Enable or disable the output on channel.
Set the output load impedance; None means high-Z.
get_offset(channel: int, **kwargs) -> Measurement | None
Read back the DC offset (volts) on channel.
get_output_state(channel: int, **kwargs) -> Measurement | None
Read back whether the output is enabled on channel.
get_output_load(channel: int, **kwargs) -> Measurement | None
Read back the output load impedance on channel.
set_modulation(
channel: int,
mod_type: ModulationType,
shape: Waveform,
magnitude: float,
**kwargs,
) -> Command
Configure channel's carrier modulation with modulator shape.
NOTE: magnitude varies by mod_type: AM: depth, FM: frequency deviation, PM: phase deviation, ASK: 2nd amplitude, FSK: hop frequency.
Enable or disable modulation on the given channel.
get_modulation_type(channel: int) -> ModulationType
Read back the modulation type currently active on channel.
get_modulation_state(channel: int, **kwargs) -> Measurement | None
Read back whether modulation is enabled on channel.
Configure channel's burst type.
Enable or disable burst mode on the given channel.
Read back the burst type currently active on channel.
get_burst_state(channel: int, **kwargs) -> Measurement | None
Read back whether burst mode is enabled on channel.
set_burst_trigger(
channel: int, source: BurstTriggerSource, **kwargs
) -> Command
Set the burst trigger source on channel.
get_burst_trigger(channel: int) -> BurstTriggerSource
Read back the burst trigger source on channel.
Fire a burst trigger on channel now; the trigger source must already be MANUAL.
Set the burst trigger delay (seconds) on channel.
get_burst_delay(channel: int, **kwargs) -> Measurement | None
Read back the burst trigger delay (seconds) on channel.
set_burst_gate_polarity(
channel: int, gate_polarity: GatePolarity, **kwargs
) -> Command
Set the gate polarity for GATED bursts on channel.
get_burst_gate_polarity(channel: int) -> GatePolarity
Read back the gate polarity for GATED bursts on channel.
Set the number of cycles per trigger for NCYCLE bursts on channel.
get_burst_ncycles(channel: int, **kwargs) -> Measurement | None
Read back the number of cycles per trigger for NCYCLE bursts on channel.
Set the internal burst period (seconds) on channel.
get_burst_period(channel: int, **kwargs) -> Measurement | None
Read back the internal burst period (seconds) on channel.
Configure the sweep type on channel.
Read back the sweep type currently configured on channel.
Enable or disable sweep mode on channel.
get_sweep_state(channel: int, **kwargs) -> Measurement | None
Read back whether sweep mode is enabled on channel.
set_sweep_trigger(
channel: int, source: SweepTriggerSource, **kwargs
) -> Command
Set the sweep trigger source on channel.
get_sweep_trigger(channel: int) -> SweepTriggerSource
Read back the sweep trigger source on channel.
Set the sweep start frequency (Hz) on channel.
get_sweep_start_freq(channel: int, **kwargs) -> Measurement | None
Read back the sweep start frequency (Hz) on channel.
Set the sweep end frequency (Hz) on channel.
get_sweep_end_freq(channel: int, **kwargs) -> Measurement | None
Read back the sweep end frequency (Hz) on channel.
Set the sweep time (seconds) on channel.
get_sweep_time(channel: int, **kwargs) -> Measurement | None
Read back the sweep time (seconds) on channel.
Set the sweep start hold time (seconds) on channel.
get_sweep_start_hold_time(channel: int, **kwargs) -> Measurement | None
Read back the sweep start hold time (seconds) on channel.
Set the sweep stop hold time (seconds) on channel.
get_sweep_stop_hold_time(channel: int, **kwargs) -> Measurement | None
Read back the sweep stop hold time (seconds) on channel.
Set the sweep return time (seconds) on channel.
get_sweep_return_time(channel: int, **kwargs) -> Measurement | None
Read back the sweep return time (seconds) on channel.
Types & Configuration¤
AWG shared types and waveform definitions.
module-attribute
¤
dataclass
¤
dataclass
¤
dataclass
¤
dataclass
¤
dataclass
¤
dataclass
¤
convert_amplitude(
value: float,
from_unit: AmplitudeMeasurementUnit,
to_unit: AmplitudeMeasurementUnit,
waveform: Waveform,
impedance_ohms: float | None = None,
) -> float
Convert an amplitude value between measurement units for a waveform shape.
VPP/VP/VRMS conversions depend on the waveform's crest factor, which is universal
math shared across every driver. DBM additionally requires impedance_ohms (the
load the instrument drives), since power depends on it.
Driver Interface¤
Bases: ABC
Vendor AWG driver contract. Concrete drivers own their transport and lifecycle.
abstractmethod
¤
Program channel with the waveform definition.
abstractmethod
¤
Get the current waveform on channel.
abstractmethod
¤
set_amplitude(
channel: int, amplitude: float, unit: AmplitudeMeasurementUnit
) -> None
Set the output amplitude on channel.
abstractmethod
¤
get_amplitude(channel: int) -> tuple[float, AmplitudeMeasurementUnit]
Get the current output amplitude and voltage unit on channel.
abstractmethod
¤
Set the DC offset (volts) on channel.
abstractmethod
¤
Enable or disable the output on channel.
abstractmethod
¤
Return True if the output on channel is enabled.
Set the output load impedance; None means high-Z.
Get the output load impedance; None means high-Z.
set_modulation(
channel: int,
mod_type: ModulationType,
shape: Waveform,
magnitude: float,
) -> None
Configure channel's carrier modulation with modulator shape.
Enable or disable modulation on the given channel.
get_modulation_type(channel: int) -> ModulationType
Get the modulation type currently active on channel.
Get the modulation enabled state currently active on channel.
Enable or disable burst mode on the given channel.
Get the burst type currently active on channel.
Return True if burst mode is enabled on channel.
set_burst_trigger(channel: int, source: BurstTriggerSource) -> None
Set the burst trigger source on channel.
get_burst_trigger(channel: int) -> BurstTriggerSource
Get the burst trigger source on channel.
fire_burst_trigger(channel: int) -> None
Fire a burst trigger on channel now; the trigger source must already be MANUAL.
Set the burst trigger delay (seconds) on channel.
Get the burst trigger delay (seconds) on channel.
set_burst_gate_polarity(
channel: int, gate_polarity: GatePolarity
) -> None
Set the gate polarity for GATED bursts on channel.
get_burst_gate_polarity(channel: int) -> GatePolarity
Get the gate polarity for GATED bursts on channel.
Set the number of cycles per trigger for NCYCLE bursts on channel.
Get the number of cycles per trigger for NCYCLE bursts on channel.
Set the internal burst period (seconds) on channel.
Get the internal burst period (seconds) on channel.
Configure the sweep type on channel.
Get the sweep type currently configured on channel.
Enable or disable sweep mode on channel.
Return True if sweep mode is enabled on channel.
set_sweep_trigger(channel: int, source: SweepTriggerSource) -> None
Set the sweep trigger source on channel.
get_sweep_trigger(channel: int) -> SweepTriggerSource
Get the sweep trigger source on channel.
Set the sweep start frequency (Hz) on channel.
Get the sweep start frequency (Hz) on channel.
Set the sweep end frequency (Hz) on channel.
Get the sweep end frequency (Hz) on channel.
Set the sweep time (seconds) on channel.
Set the sweep start hold time (seconds) on channel.
Set the sweep stop hold time (seconds) on channel.
Get the sweep start hold time (seconds) on channel.
Get the sweep stop hold time (seconds) on channel.
Set the sweep return time (seconds) on channel.
Get the sweep return time (seconds) on channel.
Vendor Drivers¤
Keysight 33521B¤
Keysight 33521B arbitrary waveform generator driver (33500 series).
Keysight33521B(visa_resource: str | VisaConfig)
Bases: AWGDriverBase
SCPI driver for the Keysight 33521B arbitrary waveform generator.
set_amplitude(
channel: int, amplitude: float, unit: AmplitudeMeasurementUnit
) -> None
set_modulation(
channel: int,
mod_type: ModulationType,
shape: Waveform,
magnitude: float,
) -> None
Configures modulation. Enabled state is persistent across set_modulation calls.
Enables the most recently configured modulation type, or disables modulation.
get_modulation_type(channel: int) -> ModulationType
Returns modulation type currently enabled, or the last type set by the user when modulation is not enabled.
NCYCLE reads back as INFINITE when BURS:NCYC is the hardware's high-water sentinel for INF.
set_burst_gate_polarity(
channel: int, gate_polarity: GatePolarity
) -> None
The 33521B has no SWEep:HTIMe:STARt; HTIMe only holds at the stop frequency.
Set the sweep start hold time (seconds) on channel.
Rigol DG1022Z¤
Rigol DG1022Z arbitrary waveform generator driver (DG1000Z series).
RigolDG1022Z(visa_resource: str | VisaConfig)
Bases: AWGDriverBase
SCPI driver for the Rigol DG1022Z two-channel arbitrary waveform generator.
set_amplitude(
channel: int, amplitude: float, unit: AmplitudeMeasurementUnit
) -> None
set_modulation(
channel: int,
mod_type: ModulationType,
shape: Waveform,
magnitude: float,
) -> None
set_burst_gate_polarity(
channel: int, gate_polarity: GatePolarity
) -> None