From a3c13998541ba4dd19b26a74fb201d83f9016c7c Mon Sep 17 00:00:00 2001
From: Oksana Shliakhtun <oksana.shliakhtun@psi.ch>
Date: Tue, 20 Aug 2024 13:51:00 +0200
Subject: [PATCH] Driver with comments

Change-Id: Ic2d35960de6b33e4d61ad1920d2416e2d5ed1ded
---
 frappy_psi/SR830.py | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/frappy_psi/SR830.py b/frappy_psi/SR830.py
index 584e6ab..cfa71bf 100644
--- a/frappy_psi/SR830.py
+++ b/frappy_psi/SR830.py
@@ -15,6 +15,7 @@
 #
 # Module authors: Oksana Shliakhtun <oksana.shliakhtun@psi.ch>
 # *****************************************************************************
+"""Stanford Research Systems SR830 DS Lock-in Amplifier"""
 
 import re
 import time
@@ -25,6 +26,11 @@ from frappy.errors import IsBusyError
 
 
 def string_to_value(value):
+    """
+    Converting the value to float, removing the units, converting the prefix into the number.
+    :param value: value
+    :return: float value without units
+    """
     value_with_unit = re.compile(r'(\d+)([pnumkMG]?)')
     value, pfx = value_with_unit.match(value).groups()
     pfx_dict = {'p': 1e-12, 'n': 1e-9, 'u': 1e-6, 'm': 1e-3, 'k': 1e3, 'M': 1e6, 'G': 1e9}
@@ -40,6 +46,13 @@ class SR830_IO(StringIO):
 
 class StanfRes(HasIO, Readable):
     def set_par(self, cmd, *args):
+        """
+        Set parameter.
+        Query commands are the same as setting commands, but they have a question mark.
+        :param cmd: command
+        :param args: value(s)
+        :return: reply
+        """
         head = ','.join([cmd] + [a if isinstance(a, str) else f'{a:g}' for a in args])
         tail = cmd.replace(' ', '? ')
         new_tail = re.sub(r'[0-9.]+', '', tail)
@@ -149,6 +162,10 @@ class XY(StanfRes):
         return IDLE, ''
 
     def read_value(self):
+        """
+        Read XY. The manual autorange implemented.
+        :return:
+        """
         if self.read_status()[0] == BUSY:
             raise IsBusyError('changing gain')
         reply = self.get_par('SNAP? 1, 2')
@@ -166,11 +183,13 @@ class XY(StanfRes):
         return int(self.get_par('SENS?'))
 
     def read_range(self):
+        """Sensitivity range value"""
         idx = self.read_irange()
         name = self.SEN_RANGE[idx]
         return string_to_value(name)
 
     def write_irange(self, irange):
+        """Index of sensitivity from the range"""
         value = int(irange)
         self.set_par(f'SENS {value}')
         self._autogain_started = time.time()
@@ -178,6 +197,12 @@ class XY(StanfRes):
         return value
 
     def write_range(self, target):
+        """
+        Setting the sensitivity range.
+        cl_idx/cl_value is the closest index/value from the range to the target
+        :param target:
+        :return: closest value of the sensitivity range
+        """
         target = float(target)
         cl_idx = None
         cl_value = float('inf')
@@ -194,6 +219,7 @@ class XY(StanfRes):
         return cl_value
 
     def read_itc(self):
+        """Time constant index from the range"""
         return int(self.get_par(f'OFLT?'))
 
     def write_itc(self, itc):
@@ -201,11 +227,18 @@ class XY(StanfRes):
         return self.set_par(f'OFLT {value}')
 
     def read_tc(self):
+        """Read time constant value from the range"""
         idx = self.read_itc()
         name = self.TIME_CONST[idx]
         return string_to_value(name)
 
     def write_tc(self, target):
+        """
+        Setting the time constant from the range.
+        cl_idx/cl_value is the closest index/value from the range to the target
+        :param target: time constant
+        :return: closest time constant value
+        """
         target = float(target)
         cl_idx = None
         cl_value = float('inf')