Hardware loop implementation

[IsaacLA12]

After reading the issue #105 about hardware loop implementation, I want to discuss a possible implementation and use as example the VNA. I believe it is general enough so it can be supported by other instruments, but maybe I am very "VNA minded" so feel free to share your ideas on the implementation.

First, I propose to join Joel's options on how to create a hardware loop so a hw loop would be like this:

center = 8e7
span = 1.5e2
loop = Loop(alias="vna_readout_bus", parameter="Parameter.FREQUENCY_CS", values=[(center, span)], hw_loop=True)

In this case, we would be telling the VNA to sweep the frequency in hardware by specifying the center and the span. Where the parameter FREQUENCY_CS is a hardware loop parameter and hw_loop is a flag. I choose this implementation so the instrument does not need to know if the parameter is setting is because it was set by a hw_loop or a sw_loop as it has specifically a parameter exclusively for hw_loops. Also, the Loop class and the execution itself don't need to know if any specific parameter of an instrument is hardware looped or not as we are setting the flag hw_loop to True.

That means the Loop class will now have a new atribute hw_loop set to False by default. Now we have to integrate the execution of hardware loops into the experiment workflow. To do this, I propose the following implementation:

First, the experiment.run() method will preprocess the hardware loops. This means to prepare the parameters needed on the instrument so that we set up the initial conditions of the hardware loop. To do this, the hardware loops should be the most outer loops. After setting the hw parameter with the needed values from loops.values, the loop.values must be updated with the new values the hardware provides, so at the end we can save on the Results class of the experiment the values that the hardware swept through.

#experiment.py

def run(self):
        ...
        self._asynchronous_data_handling(queue=data_queue)
        self._preprocess_hardware_loops()
        self._execute_recursive_loops(loops=self.options.loops, queue=data_queue)
        ...

def _preprocess_hardware_loops(self):
        """Preprocess all hardware loops from the experiment"""
        for loop in self.options.loops:
                self._process_hardware_loop(loop)

def _process_hardware_loop(self, loop: Loop):
        """Process a hardware loop. It sets the parameters needed for the hardware loop and retrieves the new array of loop.values"""
        if loop.hw_loop:
                element = self.platform.get_element(alias=loop.alias)
                self.set_parameter(
                        element=element, alias=loop.alias, parameter=loop.parameter, value=loop.values, channel_id=loop.channel_id
                )
                loop.values = self.get_hw_values(element, loop.parameter)
                # Recursive checking for hw_loops until we reach the sw_loops, reason why hw_loops are the outer loops
                self._process_hardware_loop(loop.loop)

def get_hw_values(self, element: Instrument | Bus, parameter: Parameter):
        """Get the values of a platform element's parameter"""
        return element.get_hw_values(parameter=parameter)

Therefore, we will need to add the get_hw_values() method for the generic classes Bus, SystemControl and Instrument. I show as example how it should be for the Bus class but the implementation is very similar among the three classes.

#bus.py

def get_hw_values(self, parameter: Parameter):
        """Return the hw values retrieved from the instrument if the parameter is supported"""
        try:
                return self.system_control.get_hw_values(parameter)
       except:
               raise ValueError(f"Parameter: {parameter} not supported to be looped by the hardware")

It also needs to be implemented for every parameter of every instrument that is possible to loop using the hardware. In the case of the VNA would look like this:

#e5080b_vna.py

def get_hw_values(self, parameter: Parameter):
        """Retrurns the values from the device for the supported hardware loop parameters"""
        # Frequency is hw looped on the VNA and can be setted specifying (Center,Span) or (Start,Stop)
        if parameter in [Paremeter.FREQUENCY_CS, Parameter.FREQUENCY_SS]:
                return self.get_frequencies()

That was the first step on procesing and setting the needed values of the required parameters of the instruments to prepare the hardware loop. Now when executing experiment._execute_recursive_loops() method we have to make sure we skip hardware loops to avoid setting parameters that we already preprocessed at the begining of the execution. Therefore we need to modify the experiment._update_parameters_from_loops(values, loops) called inside the previously mentioned method so it skips hardware loops.

#experiment.py

def _update_parameters_from_loops(self, values: list[float], loops: list[Loop]):
        """update parameters from loops"""
        elements = [self.platform.get_element(alias=loop.alias) for loop in loops]

        for value, loop, element in zip(values, loops, elements):
            if not loop.hw_loop:
                    self.set_parameter(
                        element=element, alias=loop.alias, parameter=loop.parameter, value=value, channel_id=loop.channel_id
                    )

I noticed there is experiment._filter_loops_values_with_external_parameters() and still have to look at it because maybe this last step can be done inside that method instead. But this is the easiest way I believe.

The main drawbacks of this implemenation is that the user has to know the values that are hardware looped for an instrument to be able to set the flag hw_loop of the loop to True. Also in case of the VNA, the parameter that suport hw loop is the frequency but in the VNA there are two ways of specifying how is set, giving a (Center, Span) or (Start, Stop) so I had to split the parameter FREQUENCY into FREQUENCY_CS and FREQUENCY_SS which maybe is not ideal and are other ways to implement it.