Make PicoScope3403 also to accept sample times of 1 and 2 ns, and correct docstrings.

[heevasti]

Description =========== The PicoScope3403 driver does not currently accept time-base values 0 and 1, respectively representing sampling intervals of 1ns and 2ns. The minimum accepted currently is time-base 2 with sampling interval of 4ns. Also, the number of samples is calculated as number_samples = int(time_span / time_base) which makes it impossible for time-base 0. The scientists would find it more intuitive to be able to give the sampling interval as an input, instead of time-base, anyhow. So, we should change the method definition for acquire_by_trigger_and_get_data to use sampling interval instead of time-base as input.

Further remark is that the method descriptions for time_base in the other methods show transformation of "(time_base+1) * 12.5 ns", which is not correct for this model (but for model 4824 instead). These docstring errors need to be fixed as well.

Changes needed:

• The time_base docstrings should read: "The effective time base is (timebase - 2) * 8 ns for timebase > 2 else 2^timebase. Depending on the enabled channels, a minimum value of up to 2 may be required (minimum time base 4 ns)."

• Introduce a new method get_time_base that calculates the time-base from sampling interval:

  def get_time_base(self, sampling_interval: int) -> int:
      """Returns the time base selector for a given sampling interval. For invalid sampling intervals, an exception is raised.
  
      Parameters:
          sampling_interval:    Sampling interval in nanoseconds. Must be 1, 2, 4 or a multiple of 8 ns.
  
      Returns:
          time_base: The respective time-base value for the sampling interval.
      """
      if sampling_interval < 1 or sampling_interval % 8 != 0:
          raise QMI_UsageException("Sampling interval must be 1, 2, 4 or a multiple of 8 ns")
  
      if sampling_interval > 4:
          return int(round((sampling_interval / 8) + 2, 0))
  
      return int(2**sampling_interval)

In acquire_by_trigger_and_get_data:

• change input time_base to sampling_interval (both int) and time_span to allow a float instead of int.

• The parameter description for sampling_interval: Sampling interval in Nanoseconds. Must be 1, 2, 4 or a multiple of 8 ns.

• Also the time_span needs correction in the docstring, and the times return value would be returned also in seconds instead of "us".

• calculate the time-base from sampling_interval and raise exception if invalid value w.r.t. channels enabled is used.

      time_base = self.get_time_base(sampling_interval)
  
      if time_base == 0 and len(channels) > 1:
          raise QMI_UsageException("Sampling interval of 1 ns is not supported for multiple channels")
  
      if time_base == 1 and len(channels) > 2:
          raise QMI_UsageException("Sampling interval of 2 ns is not supported for more than two channels")

• calculate the number of samples based on desired time span and sampling interval.

      number_samples = int(time_span / (sampling_interval))
      _logger.info(f"Timespan = %i Num samples = %i", time_span, number_samples)

• Add disabling of unused channels after channel voltage range check:

      # Disable all channels that are not used
      for chan in range(self.NUM_CHANNELS):
          if chan not in channels:
              self.set_channel(chan, False, ChannelCoupling.DC, 0, 0)

• The input parameters for self.run_block here should now use number_samples // 2 for the number of samples before and after trigger, or number_samples when all samples are taken before or after the trigger, and simply time_base for time-base, not with + 2.

• The return value for timetrace array should get a multiplier of * sampling_interval to make it in nanoseconds.

• For get_time_resolution extend the time resolution solving also for time-base 0 & 1 (sampling_interval = 2**time_base).

Modules to be created

---

N/A

Modules to be modified

---

qmi.instruments.picoscope.picoscope3403

Tests to be created/updated

---

tests.instruments.picoscope.test_picoscope3403

Documentation to be updated

---

• CHANGELOG.md

Hardware

---

PicoScope3403 model. Preferably with 4 channels.