broadbean package

Submodules

broadbean.blueprint module

class broadbean.blueprint.BluePrint(funlist=None, argslist=None, namelist=None, marker1=None, marker2=None, segmentmarker1=None, segmentmarker2=None, SR=None, durslist=None)

Bases: object

The class of a waveform to become.

property SR

Sample rate of the blueprint

classmethod blueprint_from_description(blue_dict)

Returns a blueprint from a description given as a dict

Parameters:

• blue_dict – a dict in the same form as returned by

• BluePrint.description

changeArg(name, arg, value, replaceeverywhere=False)

Change an argument of one or more of the functions in the blueprint.

Parameters:

• name (str) – The name of the segment in which to change an argument

• arg (Union[int, str]) – Either the position (int) or name (str) of the argument to change

• value (Union[int, float]) – The new value of the argument

• replaceeverywhere (bool) – If True, the same argument is overwritten in ALL segments where the name matches. E.g. ‘gaussian1’ will match ‘gaussian’, ‘gaussian2’, etc. If False, only the segment with exact name match gets a replacement.

Raises:

• ValueError – If the argument can not be matched (either the argument name does not match or the argument number is wrong).

• ValueError – If the name can not be matched.

changeDuration(name, dur, replaceeverywhere=False)

Change the duration of one or more segments in the blueprint

Parameters:

• name (str) – The name of the segment in which to change duration

• dur (Union[float, int]) – The new duration.

• replaceeverywhere (Optional[bool]) – If True, the duration(s) is(are) overwritten in ALL segments where the name matches. E.g. ‘gaussian1’ will match ‘gaussian’, ‘gaussian2’, etc. If False, only the segment with exact name match gets a replacement.

Raises:

• ValueError – If durations are not specified for the blueprint

• ValueError – If too many or too few durations are given.

• ValueError – If no segment matches the name.

• ValueError – If dur is not positive

• ValueError – If SR is given for the blueprint and dur is less than 1/SR.

copy()

Returns a copy of the BluePrint

property description

Returns a dict describing the blueprint.

property duration

The total duration of the BluePrint. If necessary, all the arrays are built.

property durations

The list of durations

classmethod init_from_json(path_to_file: str) → BluePrint

Reads blueprint from JSON file

Parameters:

• path_to_file – the path to the file to be read ex:

• path_to_file/blueprint.json

• write_to_json (by the function)

• writen (The JSON file needs to be structured as if it was)

• write_to_json

insertSegment(pos, func, args=(), dur=None, name=None, durs=None)

Insert a segment into the bluePrint.

Parameters:

• pos (int) – The position at which to add the segment. Counts like a python list; 0 is first, -1 is last. Values below -1 are not allowed, though.

• func (function) – Function describing the segment. Must have its duration as the last argument (unless its a special function).

• args (Optional[Tuple[Any]]) – Tuple of arguments BESIDES duration. Default: ()

• dur (Optional[Union[int, float]]) – The duration of the segment. Must be given UNLESS the segment is ‘waituntil’ or ‘ensureaverage_fixed_level’

• Optional[str] (name) – Name of the segment. If none is given, the segment will receive the name of its function, possibly with a number appended.

Raises:

• ValueError – If the position is negative

• ValueError – If the name ends in a number

property length_segments

Returns the number of segments in the blueprint

property points

The total number of points in the BluePrint. If necessary, all the arrays are built.

removeSegment(name)

Remove the specified segment from the blueprint.

Parameters:

name (str) – The name of the segment to remove.

removeSegmentMarker(name: str, markerID: int) → None

Remove all bound markers from a specific segment

Parameters:

• name (str) – Name of the segment

• markerID (int) – Which marker channel to remove from (1 or 2).

• number (int) – The number of the marker, in case several markers are bound to one element. Default: 1 (the first marker).

setSR(SR)

Set the associated sample rate

Parameters:

SR (Union[int, float]) – The sample rate in Sa/s.

setSegmentMarker(name, specs, markerID)

Bind a marker to a specific segment.

Parameters:

• name (str) – Name of the segment

• specs (tuple) – Marker specification tuple, (delay, duration), where the delay is relative to the segment start

• markerID (int) – Which marker channel to output on. Must be 1 or 2.

showPrint()

Pretty-print the contents of the BluePrint. Not finished.

write_to_json(path_to_file: str) → None

Writes blueprint to JSON file

Parameters:

• path_to_file – the path to the file to write to ex:

• path_to_file/blueprint.json

exception broadbean.blueprint.SegmentDurationError

Bases: Exception

broadbean.broadbean module

class broadbean.broadbean.PulseAtoms

Bases: object

A class full of static methods. The basic pulse shapes.

Any pulse shape function should return a list or an np.array and have SR, npoints as its final two arguments.

Rounding errors are a real concern/pain in the business of making waveforms of short duration (few samples). Therefore, the PulseAtoms take the number of points rather than the duration as input argument, so that all ambiguity can be handled in one place (the _subelementBuilder)

static arb_func(func: Callable, kwargs, SR, npts)

This function is used to generate an arbitrary waveform from a function. The function must be of the form f(time, **kwargs) where time is a numpy array and kwargs is a dict that provides any additional parameters needed for the function.

Example:

func = lambda time, freq, ampl, off, phase: ampl*np.sin(freq*time+phase)+off
kwargs = {'freq': 1e6, 'ampl': 1, 'off': 0, 'phase': 0}

static gaussian(ampl, sigma, mu, offset, SR, npts)

Returns a Gaussian of peak height ampl (when offset==0)

Is by default centred in the middle of the interval

static gaussian_smooth_cutoff(ampl, sigma, mu, offset, SR, npts)

Returns a Gaussian of peak height ampl (when offset==0)

Is by default centred in the middle of the interval

smooth cutoff by making offsetting the Gaussian so endpoint = 0 and normalizing the hight to 1

static ramp(start, stop, SR, npts)

static sine(freq, ampl, off, phase, SR, npts)

static waituntil(dummy, SR, npts)

broadbean.broadbean.marked_for_deletion(replaced_by: str | None = None) → Callable

A decorator for functions we want to kill. The function still gets called.

broadbean.element module

class broadbean.element.Element

Bases: object

Object representing an element. An element is a collection of waves that are to be run simultaneously. The element consists of a number of channels that are then each filled with anything of the appropriate length.

property SR

Returns the sample rate, if well-defined. Else raises an error about what went wrong.

addArray(channel: int | str, waveform: ndarray, SR: int, **kwargs) → None

Add an array of voltage value to the element on the specified channel. Overwrites whatever was there before. Markers can be specified via the kwargs, i.e. the kwargs must specify arrays of markers. The names can be ‘m1’, ‘m2’, ‘m3’, etc.

Parameters:

• channel – The channel number

• waveform – The array of waveform values (V)

• SR – The sample rate in Sa/s

addBluePrint(channel: str | int, blueprint: BluePrint) → None

Add a blueprint to the element on the specified channel. Overwrites whatever was there before.

addFlags(channel: str | int, flags: Sequence[str | int]) → None

Adds flags for the specified channel. List of 4 flags, each of which should be 0 or “” for ‘No change’, 1 or “H” for ‘High’, 2 or “L” for ‘Low’, 3 or “T” for ‘Toggle’, 4 or “P” for ‘Pulse’.

changeArg(channel: str | int, name: str, arg: str | int, value: int | float, replaceeverywhere: bool = False) → None

Change the argument of a function of the blueprint on the specified channel.

Parameters:

• channel – The channel where the blueprint sits.

• name – The name of the segment in which to change an argument

• arg – Either the position (int) or name (str) of the argument to change

• value – The new value of the argument

• replaceeverywhere – If True, the same argument is overwritten in ALL segments where the name matches. E.g. ‘gaussian1’ will match ‘gaussian’, ‘gaussian2’, etc. If False, only the segment with exact name match gets a replacement.

Raises:

• ValueError – If the specified channel has no blueprint.

• ValueError – If the argument can not be matched (either the argument name does not match or the argument number is wrong).

changeDuration(channel: str | int, name: str, newdur: int | float, replaceeverywhere: bool = False) → None

Change the duration of a segment of the blueprint on the specified channel

Parameters:

• channel – The channel holding the blueprint in question

• name) – The name of the segment to modify

• newdur – The new duration.

• replaceeverywhere – If True, all segments matching the base name given will have their duration changed. If False, only the segment with an exact name match will have its duration changed. Default: False.

property channels

The channels that has something on them

copy()

Return a copy of the element

property description

Returns a dict describing the element.

property duration

Returns the duration in seconds of the element, if said duration is well-defined. Else raises an error.

classmethod element_from_description(element_dict)

Returns a blueprint from a description given as a dict

Parameters:

• element_dict – a dict in the same form as returned by

• Element.description

getArrays(includetime: bool = False) → dict[int, dict[str, ndarray]]

Return arrays of the element. Heavily used by the Sequence.

Parameters:

includetime – Whether to include time arrays. They will have the key ‘time’. Time should be included when plotting, otherwise not.

Returns:

Dictionary with channel numbers (ints) as keys and forged blueprints as values. A forged blueprint is a dict with the mandatory key ‘wfm’ and optional keys ‘m1’, ‘m2’, ‘m3’ (etc) and ‘time’.

Return type:

dict

classmethod init_from_json(path_to_file: str) → Element

Reads Element from JSON file

Parameters:

• path_to_file – the path to the file to be read ex:

• path_to_file/Element.json

• write_to_json (by the function)

• writen (The JSON file needs to be structured as if it was)

• write_to_json

property points: int

Returns the number of points of each channel if that number is well-defined. Else an error is raised.

validateDurations()

Check that all channels have the same specified duration, number of points and sample rate.

write_to_json(path_to_file: str) → None

Writes element to JSON file

Parameters:

• path_to_file – the path to the file to write to ex:

• path_to_file/element.json

exception broadbean.element.ElementDurationError

Bases: Exception

broadbean.plotting module

broadbean.plotting.getSIScalingAndPrefix(minmax: tuple[float, float]) → tuple[float, str]

Return the scaling exponent and unit prefix. E.g. (-2e-3, 1e-6) will return (1e3, ‘m’)

Parameters:

minmax – The (min, max) value of the signal

Returns:

A tuple of the scaling (inverse of the prefix) and the prefix

string.

broadbean.plotting.plotter(obj_to_plot: Sequence | BluePrint | Element, **forger_kwargs) → None

The one plot function to be called. Turns whatever it gets into a sequence, forges it, and plots that.

broadbean.ripasso module

exception broadbean.ripasso.MissingFrequenciesError

Bases: Exception

broadbean.ripasso.applyCustomTransferFunction(signal, SR, tf_freqs, tf_amp, invert=False)

Apply custom transfer function

Given a signal, its sample rate, and a provided transfer function, apply the transfer function to the signal.

Parameters:

• signal (np.array) – A numpy array containing the signal

• SR (int) – The sample rate of the signal (Sa/s)

• tf_freqs (np.array) – The frequencies of the transfer function. Must be monotonically increasing.

• tf_amp (np.array) – The amplitude of the transfer function. Must be dimensionless.

• invert (Optional[bool]) – If True, the inverse transfer function is applied. Default: False.

Returns:

The modified signal.

Return type:

np.array

broadbean.ripasso.applyInverseRCFilter(signal, SR, kind, f_cut, order, DCgain=1)

Apply the inverse of an RC-circuit filter to a signal and return the compensated signal.

Note that a high-pass filter in principle has identically zero DC gain which requires an infinite offset to compensate.

Parameters:

• signal (np.array) – The input signal. The signal is assumed to start at t=0 and be evenly sampled at sample rate SR.

• SR (int) – Sample rate (Sa/s) of the input signal

• kind (str) – The type of filter. Either ‘HP’ or ‘LP’.

• f_cut (float) – The cutoff frequency of the filter (Hz)

• order (int) – The order of the filter. The first order filter is applied order times.

• DCgain (Optional[float]) – The DC gain of the filter. ONLY used by the high-pass filter. Default: 1.

Returns:

The filtered signal along the original time axis. Imaginary parts are discarded prior to return.

Return type:

np.array

Raises:

• ValueError – If kind is neither ‘HP’ nor ‘LP’

• ValueError – If DCgain is zero.

broadbean.ripasso.applyRCFilter(signal, SR, kind, f_cut, order, DCgain=0)

Apply a simple RC-circuit filter to signal and return the filtered signal.

Parameters:

• signal (np.array) – The input signal. The signal is assumed to start at t=0 and be evenly sampled at sample rate SR.

• SR (int) – Sample rate (Sa/s) of the input signal

• kind (str) – The type of filter. Either ‘HP’ or ‘LP’.

• f_cut (float) – The cutoff frequency of the filter (Hz)

• order (int) – The order of the filter. The first order filter is applied order times.

• DCgain (Optional[float]) – The DC gain of the filter. ONLY used by the high-pass filter. Default: 0.

Returns:

The filtered signal along the original time axis. Imaginary parts are discarded prior to return.

Return type:

np.array

Raises:

ValueError – If kind is neither ‘HP’ nor ‘LP’

broadbean.sequence module

exception broadbean.sequence.InvalidForgedSequenceError

Bases: Exception

class broadbean.sequence.Sequence

Bases: object

Sequence object

property SR

Returns the sample rate, if defined. Else returns -1.

addElement(position: int, element: Element) → None

Add an element to the sequence. Overwrites previous values.

Parameters:

• position (int) – The sequence position of the element (lowest: 1)

• element (Element) – An element instance

Raises:

ValueError – If the element has inconsistent durations

addSubSequence(position: int, subsequence: Sequence) → None

Add a subsequence to the sequence. Overwrites anything previously assigned to this position. The subsequence can not contain any subsequences itself.

Parameters:

• position – The sequence position (starting from 1)

• subsequence – The subsequence to add

property channels

Returns a list of the specified channels of the sequence

checkConsistency(verbose=False)

Checks wether the sequence can be built, i.e. wether all elements have waveforms on the same channels and of the same length.

copy()

Returns a copy of the sequence.

property description

Return a dictionary fully describing the Sequence.

property duration: float

Returns the duration in seconds of the sequence.

element(pos)

Returns the element at the given position. Changes made to the return value of this methods will apply to the sequence. If this is undesired, make a copy of the returned element using Element.copy

Parameters:

pos (int) – The sequence position

Raises:

KeyError – If no element is specified at the given position

forge(apply_delays: bool = True, apply_filters: bool = True, includetime: bool = False) → dict[int, dict]

Forge the sequence, applying all specified transformations (delays and ripasso filter corrections). Copies the data, so that the sequence is not modified by forging.

Parameters:

• apply_delays – Whether to apply the assigned channel delays (if any)

• apply_filters – Whether to apply the assigned channel filters (if any)

• includetime – Whether to include the time axis and the segment durations (a list) with the arrays. Used for plotting.

Returns:

A nested dictionary holding the forged sequence.

classmethod init_from_json(path_to_file: str) → Sequence

Reads sequense from JSON file

Parameters:

• path_to_file – the path to the file to be read ex:

• path_to_file/sequense.json

• write_to_json (by the function)

• writen (The JSON file needs to be structured as if it was)

• write_to_json

property length_sequenceelements

Returns the current number of specified sequence elements

property name

outputForAWGFile()

Returns a sliceable object with items matching the call signature of the ‘make_*_awg_file’ functions of the QCoDeS AWG5014 driver. One may then construct an awg file as follows (assuming that seq is the sequence object):

package = seq.outputForAWGFile()
make_awg_file(*package[:], **kwargs)

outputForSEQXFile() → tuple[list[int], list[int], list[int], list[int], list[int], list[list[ndarray]], list[float], str]

Generate a tuple matching the call signature of the QCoDeS AWG70000A driver’s makeSEQXFile function. If channel delays have been specified, they are added to the ouput before exporting. The intended use of this function together with the QCoDeS driver is

pkg = seq.outputForSEQXFile()
seqx = awg70000A.makeSEQXFile(*pkg)

Returns:

A tuple holding (trig_waits, nreps, event_jumps, event_jump_to,

go_to, wfms, amplitudes, seqname)

outputForSEQXFileWithFlags() → tuple[list[int], list[int], list[int], list[int], list[int], list[list[ndarray]], list[float], str, list[list[list[int]]]]

Generate a tuple matching the call signature of the QCoDeS AWG70000A driver’s makeSEQXFile function. Same as outputForSEQXFile(), but also includes information about the flags.

Returns:

A tuple holding (trig_waits, nreps, event_jumps, event_jump_to,

go_to, wfms, amplitudes, seqname, flags)

property points

Returns the number of points of the sequence, disregarding sequencing info (like repetitions). Useful for asserting upload times, i.e. the size of the built sequence.

classmethod sequence_from_description(seq_dict: dict) → Sequence

Returns a sequence from a description given as a dict

Parameters:

• seq_dict – a dict in the same form as returned by

• Sequence.description

setChannelAmplitude(channel: int | str, ampl: float) → None

Assign the physical voltage amplitude of the channel. This is used when making output for real instruments.

Parameters:

• channel – The channel number

• ampl – The channel peak-to-peak amplitude (V)

setChannelDelay(channel: int | str, delay: float) → None

Assign a delay to a channel. This is used when making output for .awg files. Use the delay to compensate for cable length differences etc. Zeros are prepended to the waveforms to delay them and correspondingly appended to non (or less) delayed channels.

Parameters:

• channel – The channel number/name

• delay – The required delay (s)

Raises:

ValueError – If a non-integer or non-non-negative channel number is given.

setChannelFilterCompensation(channel: str | int, kind: str, order: int = 1, f_cut: float | None = None, tau: float | None = None) → None

Specify a filter to compensate for.

The specified channel will get a compensation (pre-distorion) to compensate for the specified frequency filter. Just to be clear: the INVERSE transfer function of the one you specify is applied. Only compensation for simple RC-circuit type high pass and low pass is supported.

Parameters:

• channel – The channel to apply this to.

• kind – Either ‘LP’ or ‘HP’

• order – The order of the filter to compensate for. May be negative. Default: 1.

• f_cut – The cut_off frequency (Hz).

• tau) – The time constant (s). Note that tau = 1/f_cut and that only one of the two can be specified.

Raises:

• ValueError – If kind is not ‘LP’ or ‘HP’

• ValueError – If order is not an int.

• SpecificationInconsistencyError – If both f_cut and tau are given.

setChannelOffset(channel: int | str, offset: float) → None

Assign the physical voltage offset of the channel. This is used by some backends when making output for real instruments

Parameters:

• channel – The channel number/name

• offset – The channel offset (V)

setChannelVoltageRange(channel, ampl, offset)

Assign the physical voltages of the channel. This is used when making output for .awg files. The corresponding parameters in the QCoDeS AWG5014 driver are called chXX_amp and chXX_offset. Please ensure that the channel in question is indeed in ampl/offset mode and not in high/low mode.

Parameters:

• channel (int) – The channel number

• ampl (float) – The channel peak-to-peak amplitude (V)

• offset (float) – The channel offset (V)

setSR(SR)

Set the sample rate for the sequence

setSequenceSettings(pos, wait, nreps, jump, goto)

Set the sequence setting for the sequence element at pos.

Parameters:

• pos (int) – The sequence element (counting from 1)

• wait (int) – The wait state specifying whether to wait for a trigger. 0: OFF, don’t wait, 1: ON, wait. For some backends, additional integers are allowed to specify the trigger input. 0 always means off.

• nreps (int) – Number of repetitions. 0 corresponds to infinite repetitions

• jump (int) – Event jump target, the position of a sequence element. If 0, the event jump state is off.

• goto (int) – Goto target, the position of a sequence element. 0 means next.

setSequencingEventInput(pos: int, jump_input: int) → None

Set the event input for the sequence element at pos. This setting is ignored by the AWG 5014.

Parameters:

• pos – The sequence element (counting from 1)

• jump_input – The input specifier, 0 for off, 1 for ‘TrigA’, 2 for ‘TrigB’, 3 for ‘Internal’.

setSequencingEventJumpTarget(pos: int, jump_target: int) → None

Set the event jump target for the sequence element at pos.

Parameters:

• pos – The sequence element (counting from 1)

• jump_target – The sequence element to jump to (counting from 1)

setSequencingGoto(pos: int, goto: int) → None

Set the goto target (which element to play after the current one ends) for the sequence element at pos.

Parameters:

• pos – The sequence element (counting from 1)

• goto – The position of the element to play. 0 means ‘next in line’

setSequencingNumberOfRepetitions(pos: int, nrep: int) → None

Set the number of repetitions for the sequence element at pos.

Parameters:

• pos – The sequence element (counting from 1)

• nrep – The number of repetitions (0 means infinite)

setSequencingTriggerWait(pos: int, wait: int) → None

Set the trigger wait for the sequence element at pos. For AWG 5014 out, this can be 0 or 1, For AWG 70000A output, this can be 0, 1, 2, or 3.

Parameters:

• pos – The sequence element (counting from 1)

• wait – The wait state/input depending on backend.

write_to_json(path_to_file: str) → None

Writes sequences to JSON file

Parameters:

• path_to_file – the path to the file to write to ex:

• path_to_file/sequense.json

exception broadbean.sequence.SequenceCompatibilityError

Bases: Exception

exception broadbean.sequence.SequenceConsistencyError

Bases: Exception

exception broadbean.sequence.SequencingError

Bases: Exception

exception broadbean.sequence.SpecificationInconsistencyError

Bases: Exception

broadbean.tools module

broadbean.tools.makeLinearlyVaryingSequence(baseelement, channel, name, arg, start, stop, step)

Make a pulse sequence where a single parameter varies linearly. The pulse sequence will consist of N copies of the same element with just the specified argument changed (N = abs(stop-start)/steps)

Parameters:

• baseelement (Element) – The basic element.

• channel (int) – The channel where the change should happen

• name (str) – Name of the blueprint segment to change

• arg (Union[str, int]) – Name (str) or position (int) of the argument to change. If the arg is ‘duration’, the duration is changed instead.

• start (float) – Start point of the variation (included)

• stop (float) – Stop point of the variation (included)

• step (float) – Increment of the variation

broadbean.tools.makeVaryingSequence(baseelement, channels, names, args, iters)

Make a pulse sequence where N parameters vary simultaneously in M steps. The user inputs a baseelement which is copied M times and changed according to the given inputs.

Parameters:

• baseelement (Element) – The basic element.

• channels (Union[list, tuple]) – Either a list or a tuple of channels on which to find the blueprint to change. Must have length N.

• names (Union[list, tuple]) – Either a list or a tuple of names of the segment to change. Must have length N.

• args (Union[list, tuple]) – Either a list or a tuple of argument specifications for the argument to change. Use ‘duration’ to change the segment duration. Must have length N.

• iters (Union[list, tuple]) – Either a list or a tuple of length N containing Union[list, tuple, range] of length M.

Raises:

• ValueError – If not channels, names, args, and iters are of the same length.

• ValueError – If not each iter in iters specifies the same number of values.

broadbean.tools.repeatAndVarySequence(seq, poss, channels, names, args, iters)

Repeat a sequence and vary part(s) of it. Returns a new sequence. Given N specifications of M steps, N parameters are varied in M steps.

Parameters:

• seq (Sequence) – The sequence to be repeated.

• poss (Union[list, tuple]) – A length N list/tuple specifying at which sequence position(s) the blueprint to change is.

• channels (Union[list, tuple]) – A length N list/tuple specifying on which channel(s) the blueprint to change is.

• names (Union[list, tuple]) – A length N list/tuple specifying the name of the segment to change.

• args (Union[list, tuple]) – A length N list/tuple specifying which argument to change. A valid argument is also ‘duration’.

• iters (Union[list, tuple]) – A length N list/tuple containing length M indexable iterables with the values to step through.

Module contents