labscript.outputs.AnalogQuantity

class AnalogQuantity(name, parent_device, connection, limits=None, unit_conversion_class=None, unit_conversion_parameters=None, default_value=None, **kwargs)

Bases: Output

Base class for AnalogOut.

It is also used internally by DDS. You should never instantiate this class directly.

__init__(name, parent_device, connection, limits=None, unit_conversion_class=None, unit_conversion_parameters=None, default_value=None, **kwargs)

Instantiate an Output.

Parameters:

• name (str) – python variable name to assign the Output to.

• parent_device (IntermediateDevice) – Parent device the output is connected to.

• connection (str) – Channel of parent device output is connected to.

• limits (tuple, optional) – (min,max) allowed for the output.

• unit_conversion_class (labscript_utils:labscript_utils.unitconversions, optional) – Unit concersion class to use for the output.

• unit_conversion_parameters (dict, optional) – Dictonary or kwargs to pass to the unit conversion class.

• default_value (float, optional) – Default value of the output if no output is commanded.

• **kwargs – Passed to Device.__init__().

Raises:

LabscriptError – Limits tuple is invalid or unit conversion class units don’t line up.

Methods

__init__(name, parent_device, connection[, ...])	Instantiate an Output.
add_device(device)	Adds a child device to this device.
add_instruction(time, instruction[, units])	Adds a hardware instruction to the device instruction list.
apply_calibration(value, units)	Apply the calibration defined by the unit conversion class, if present.
constant(t, value[, units])	Sets the output to a constant value at time t.
customramp(t, duration, function, *args, ...)	Define a custom function for the output.
do_checks(trigger_times)	Basic error checking to ensure the user's instructions make sense.
exp_ramp(t, duration, initial, final, samplerate)	Exponential ramp whose rate of change is set by an asymptotic value (zero argument).
exp_ramp_t(t, duration, initial, final, ...)	Exponential ramp whose rate of change is set by the time_constant.
expand_timeseries(all_times, flat_all_times_len)	This function evaluates the ramp functions in self.timeseries at the time points in all_times, and creates an array of output values at those times.
generate_code(hdf5_file)	Generate hardware instructions for device and children, then save to h5 file.
get_all_children()	Get all children devices for this device.
get_all_outputs()	Get all children devices that are outputs.
get_change_times()	If this function is being called, it means that the parent Pseudoclock has requested a list of times that this output changes state.
get_properties([location])	Get all properties in location.
get_property(name[, location])	Method to get a property of this device already set using Device.set_property().
get_ramp_times()	If this is being called, then it means the parent Pseuedoclock has asked for a list of the output ramp start and stop times.
init_device_group(hdf5_file)	Creates the device group in the shot file.
instruction_to_string(instruction)	Gets a human readable description of an instruction.
make_timeseries(change_times)	If this is being called, then it means the parent Pseudoclock has asked for a list of this output's states at each time in change_times.
offset_instructions_from_trigger(trigger_times)	Subtracts self.trigger_delay from all instructions at or after each trigger_time.
piecewise_accel_ramp(t, duration, initial, ...)	Changes the output so that the second derivative follows one period of a triangle wave.
quantise_to_pseudoclock(times)	Quantises times to the resolution of the controlling pseudoclock.
ramp(t, duration, initial, final, samplerate)	Command the output to perform a linear ramp.
set_properties(properties_dict, property_names)	Add one or a bunch of properties packed into properties_dict
set_property(name, value[, location, overwrite])	Method to set a property for this device.
sine(t, duration, amplitude, angfreq, phase, ...)	Command the output to perform a sinusoidal modulation.
sine4_ramp(t, duration, initial, final, ...)	Command the output to perform an increasing ramp defined by one half period of a quartic sine wave.
sine4_reverse_ramp(t, duration, initial, ...)	Command the output to perform a decreasing ramp defined by one half period of a quartic sine wave.
sine_ramp(t, duration, initial, final, ...)	Command the output to perform a ramp defined by one half period of a squared sine wave.
square_wave(t, duration, amplitude, ...[, ...])	A standard square wave.
square_wave_levels(t, duration, level_0, ...)	A standard square wave.

Attributes

allowed_children	Defines types of devices that are allowed to be children of this device.
allowed_states
clock_limit	Returns the parent clock line's clock limit.
default_value
description	Brief description of the device.
parent_clock_line	Stores the clocking clockline, which may be itself.
pseudoclock_device	Stores the clocking pseudoclock, which may be itself.
scale_factor
t0	The earliest time output can be commanded from this device at the start of the experiment.
trigger_delay	The earliest time output can be commanded from this device after a trigger.
wait_delay	The earliest time output can be commanded from this device after a wait.

constant(t, value, units=None)

Sets the output to a constant value at time t.

Parameters:

• t (float) – Time, in seconds, to set the constant output.

• value (float) – Value to set.

• units – Units, defined by the unit conversion class, the value is in.

customramp(t, duration, function, *args, **kwargs)

Define a custom function for the output.

Parameters:

• t (float) – Time, in seconds, to start the function.

• duration (float) – Length in time, in seconds, to perform the function.

• function (func) – Function handle that defines the output waveform. First argument is the relative time from function start, in seconds.

• *args – Arguments passed to function.

• **kwargs – Keyword arguments pass to function. Standard kwargs common to other output functions are: units, samplerate, and truncation. These kwargs are optional, but will not be passed to function if present.

Returns:

Duration the function is to be evaluate for. Equivalent to truncation*duration.

Return type:

float

default_value = 0

description = 'analog quantity'

Brief description of the device.

exp_ramp(t, duration, initial, final, samplerate, zero=0, units=None, truncation=None, truncation_type='linear', **kwargs)

Exponential ramp whose rate of change is set by an asymptotic value (zero argument).

Parameters:

• t (float) – time to start the ramp

• duration (float) – duration of the ramp

• initial (float) – initial value of the ramp (sans truncation)

• final (float) – final value of the ramp (sans truncation)

• zero (float) – asymptotic value of the exponential decay/rise, i.e. limit as t –> inf

• samplerate (float) – rate to sample the function

• units – unit conversion to apply to specified values before generating raw output

• truncation_type (str) –

  • 'linear' truncation stops the ramp when it reaches the value given by the truncation parameter, which must be between initial and final

  • 'exponential' truncation stops the ramp after a period of truncation*duration In this instance, the truncation parameter should be between 0 (full truncation) and 1 (no truncation).

exp_ramp_t(t, duration, initial, final, time_constant, samplerate, units=None, truncation=None, truncation_type='linear', **kwargs)

Exponential ramp whose rate of change is set by the time_constant.

Parameters:

• t (float) – time to start the ramp

• duration (float) – duration of the ramp

• initial (float) – initial value of the ramp (sans truncation)

• final (float) – final value of the ramp (sans truncation)

• time_constant (float) – 1/e time of the exponential decay/rise

• samplerate (float) – rate to sample the function

• units – unit conversion to apply to specified values before generating raw output

• truncation_type (str) –

  • 'linear' truncation stops the ramp when it reaches the value given by the truncation parameter, which must be between initial and final

  • 'exponential' truncation stops the ramp after a period of truncation*duration In this instance, the truncation parameter should be between 0 (full truncation) and 1 (no truncation).

piecewise_accel_ramp(t, duration, initial, final, samplerate, units=None, truncation=1.0)

Changes the output so that the second derivative follows one period of a triangle wave.

Parameters:

• t (float) – Time, in seconds, at which to begin the ramp.

• duration (float) – Duration of the ramp, in seconds.

• initial (float) – Initial output value at time t.

• final (float) – Final output value at time t+duration.

• samplerate (float) – Update rate of the output, in Hz.

• units – Units, defined by the unit conversion class, the value is in.

• truncation (float, optional) – Fraction of ramp to perform. Default 1.0.

Returns:

Time the ramp will take to complete.

Return type:

float

ramp(t, duration, initial, final, samplerate, units=None, truncation=1.0)

Command the output to perform a linear ramp.

Defined by f(t) = ((final - initial)/duration)*t + initial

Parameters:

• t (float) – Time, in seconds, to begin the ramp.

• duration (float) – Length, in seconds, of the ramp.

• initial (float) – Initial output value, at time t.

• final (float) – Final output value, at time t+duration.

• samplerate (float) – Rate, in Hz, to update the output.

• units – Units the output values are given in, as specified by the unit conversion class.

• truncation (float, optional) – Fraction of ramp to perform. Must be between 0 and 1.

Returns:

Length of time ramp will take to complete.

Return type:

float

sine(t, duration, amplitude, angfreq, phase, dc_offset, samplerate, units=None, truncation=1.0)

Command the output to perform a sinusoidal modulation.

Defined by f(t) = amplitude*sin(angfreq*t + phase) + dc_offset

Parameters:

• t (float) – Time, in seconds, to begin the ramp.

• duration (float) – Length, in seconds, of the ramp.

• amplitude (float) – Amplitude of the modulation.

• angfreq (float) – Angular frequency, in radians per second.

• phase (float) – Phase offset of the sine wave, in radians.

• dc_offset (float) – DC offset of output away from 0.

• samplerate (float) – Rate, in Hz, to update the output.

• units – Units the output values are given in, as specified by the unit conversion class.

• truncation (float, optional) – Fraction of duration to perform. Must be between 0 and 1.

Returns:

Length of time modulation will take to complete. Equivalent to truncation*duration.

Return type:

float

sine4_ramp(t, duration, initial, final, samplerate, units=None, truncation=1.0)

Command the output to perform an increasing ramp defined by one half period of a quartic sine wave.

Defined by f(t) = (final-initial)*(sin(pi*t/(2*duration)))^4 + initial

Parameters:

• t (float) – Time, in seconds, to begin the ramp.

• duration (float) – Length, in seconds, of the ramp.

• initial (float) – Initial output value, at time t.

• final (float) – Final output value, at time t+duration.

• samplerate (float) – Rate, in Hz, to update the output.

• units – Units the output values are given in, as specified by the unit conversion class.

• truncation (float, optional) – Fraction of ramp to perform. Must be between 0 and 1.

Returns:

Length of time ramp will take to complete.

Return type:

float

sine4_reverse_ramp(t, duration, initial, final, samplerate, units=None, truncation=1.0)

Command the output to perform a decreasing ramp defined by one half period of a quartic sine wave.

Defined by f(t) = (final-initial)*(sin(pi*t/(2*duration)))^4 + initial

Parameters:

• t (float) – Time, in seconds, to begin the ramp.

• duration (float) – Length, in seconds, of the ramp.

• initial (float) – Initial output value, at time t.

• final (float) – Final output value, at time t+duration.

• samplerate (float) – Rate, in Hz, to update the output.

• units – Units the output values are given in, as specified by the unit conversion class.

• truncation (float, optional) – Fraction of ramp to perform. Must be between 0 and 1.

Returns:

Length of time ramp will take to complete.

Return type:

float

sine_ramp(t, duration, initial, final, samplerate, units=None, truncation=1.0)

Command the output to perform a ramp defined by one half period of a squared sine wave.

Defined by f(t) = (final-initial)*(sin(pi*t/(2*duration)))^2 + initial

Parameters:

• t (float) – Time, in seconds, to begin the ramp.

• duration (float) – Length, in seconds, of the ramp.

• initial (float) – Initial output value, at time t.

• final (float) – Final output value, at time t+duration.

• samplerate (float) – Rate, in Hz, to update the output.

• units – Units the output values are given in, as specified by the unit conversion class.

• truncation (float, optional) – Fraction of ramp to perform. Must be between 0 and 1.

Returns:

Length of time ramp will take to complete.

Return type:

float

square_wave(t, duration, amplitude, frequency, phase, offset, duty_cycle, samplerate, units=None, truncation=1.0)

A standard square wave.

This method generates a square wave which starts HIGH (when its phase is zero) then transitions to/from LOW at the specified frequency in Hz. The amplitude parameter specifies the peak-to-peak amplitude of the square wave which is centered around offset. For example, setting amplitude=1 and offset=0 would give a square wave which transitions between 0.5 and -0.5. Similarly, setting amplitude=2 and offset=3 would give a square wave which transitions between 4 and 2. To instead specify the HIGH/LOW levels directly, use square_wave_levels().

Note that because the transitions of a square wave are sudden and discontinuous, small changes in timings (e.g. due to numerical rounding errors) can affect the output value. This is particularly relevant at the end of the waveform, as the final output value may be different than expected if the end of the waveform is close to an edge of the square wave. Care is taken in the implementation of this method to avoid such effects, but it still may be desirable to call constant() after square_wave() to ensure a particular final value. The output value may also be different than expected at certain moments in the middle of the waveform due to the finite samplerate (which may be different than the requested samplerate), particularly if the actual samplerate is not a multiple of frequency.

Parameters:

• t (float) – The time at which to start the square wave.

• duration (float) – The duration for which to output a square wave when truncation is set to 1. When truncation is set to a value less than 1, the actual duration will be shorter than duration by that factor.

• amplitude (float) – The peak-to-peak amplitude of the square wave. See above for an example of how to calculate the HIGH/LOW output values given the amplitude and offset values.

• frequency (float) – The frequency of the square wave, in Hz.

• phase (float) – The initial phase of the square wave. Note that the square wave is defined such that the phase goes from 0 to 1 (NOT 2 pi) over one cycle, so setting phase=0.5 will start the square wave advanced by 1/2 of a cycle. Setting phase equal to duty_cycle will cause the waveform to start LOW rather than HIGH.

• offset (float) – The offset of the square wave, which is the value halfway between the LOW and HIGH output values. Note that this is NOT the LOW output value; setting offset to 0 will cause the HIGH/LOW values to be symmetrically split around 0. See above for an example of how to calculate the HIGH/LOW output values given the amplitude and offset values.

• duty_cycle (float) – The fraction of the cycle for which the output should be HIGH. This should be a number between zero and one inclusively. For example, setting duty_cycle=0.1 will create a square wave which outputs HIGH over 10% of the cycle and outputs LOW over 90% of the cycle.

• samplerate (float) – The requested rate at which to update the output value. Note that the actual samplerate used may be different if, for example, another output of the same device has a simultaneous ramp with a different requested samplerate, or if 1 / samplerate isn’t an integer multiple of the pseudoclock’s timing resolution.

• units (str, optional) – The units of the output values. If set to None then the output’s base units will be used. Defaults to None.

• truncation (float, optional) – The actual duration of the square wave will be duration * truncation and truncation must be set to a value in the range [0, 1] (inclusively). Set to 1 to output the full duration of the square wave. Setting it to 0 will skip the square wave entirely. Defaults to 1..

Returns:

The actual duration of the square wave, accounting

for truncation.

Return type:

duration (float)

square_wave_levels(t, duration, level_0, level_1, frequency, phase, duty_cycle, samplerate, units=None, truncation=1.0)

A standard square wave.

This method generates a square wave which starts at level_0 (when its phase is zero) then transitions to/from level_1 at the specified frequency. This is the same waveform output by square_wave(), but parameterized differently. See that method’s docstring for more information.

Parameters:

• t (float) – The time at which to start the square wave.

• duration (float) – The duration for which to output a square wave when truncation is set to 1. When truncation is set to a value less than 1, the actual duration will be shorter than duration by that factor.

• level_0 (float) – The initial level of the square wave, when the phase is zero.

• level_1 (float) – The other level of the square wave.

• frequency (float) – The frequency of the square wave, in Hz.

• phase (float) – The initial phase of the square wave. Note that the square wave is defined such that the phase goes from 0 to 1 (NOT 2 pi) over one cycle, so setting phase=0.5 will start the square wave advanced by 1/2 of a cycle. Setting phase equal to duty_cycle will cause the waveform to start at level_1 rather than level_0.

• duty_cycle (float) – The fraction of the cycle for which the output should be set to level_0. This should be a number between zero and one inclusively. For example, setting duty_cycle=0.1 will create a square wave which outputs level_0 over 10% of the cycle and outputs level_1 over 90% of the cycle.

• samplerate (float) – The requested rate at which to update the output value. Note that the actual samplerate used may be different if, for example, another output of the same device has a simultaneous ramp with a different requested samplerate, or if 1 / samplerate isn’t an integer multiple of the pseudoclock’s timing resolution.

• units (str, optional) – The units of the output values. If set to None then the output’s base units will be used. Defaults to None.

• truncation (float, optional) – The actual duration of the square wave will be duration * truncation and truncation must be set to a value in the range [0, 1] (inclusively). Set to 1 to output the full duration of the square wave. Setting it to 0 will skip the square wave entirely. Defaults to 1..

Returns:

The actual duration of the square wave, accounting

for truncation.

Return type:

duration (float)