Updating LakeShore331 (#44)

* Updated Lake Shore Cryogenics name in docs
* Updating LakeShore331 with A and B sensor temperatures
* Updated LakeShore 331 with temperature setting capability
* Added should_stop function to LakeShore 331 wait_for_temperature
* Fixed precentage in LaskeShore 331 wait_for_temperature
* Updated docs and minor fixes for LakeShore331
* Minor units fix for LakeShore 331
* Bug fixes to wait_for_temperature

docs/api/instruments/lakeshore/adapters.rst

@@ -1,6 +1,6 @@
-##################
-LakeShore Adapters
-##################
+###################
+Lake Shore Adapters
+###################
 
 .. autoclass:: pymeasure.instruments.lakeshore.LakeShoreUSBAdapter
     :members:

docs/api/instruments/lakeshore/index.rst

@@ -1,10 +1,10 @@
 .. module:: pymeasure.instruments.lakeshore
 
-#########
-LakeShore
-#########
+#####################
+Lake Shore Cryogenics
+#####################
 
-This section contains specific documentation on the LakeShore instruments that are implemented. If you are interested in an instrument not included, please consider :doc:`adding the instrument </dev/adding_instruments>`.
+This section contains specific documentation on the Lake Shore Cryogenics instruments that are implemented. If you are interested in an instrument not included, please consider :doc:`adding the instrument </dev/adding_instruments>`.
 
 .. toctree::
    :maxdepth: 2

docs/api/instruments/lakeshore/lakeshore331.rst

@@ -1,6 +1,6 @@
-####################################
-LakeShore 331 Temperature Controller
-####################################
+#####################################
+Lake Shore 331 Temperature Controller
+#####################################
 
 .. autoclass:: pymeasure.instruments.lakeshore.LakeShore331
     :members:

docs/api/instruments/lakeshore/lakeshore425.rst

@@ -1,6 +1,6 @@
-########################
-LakeShore 425 Gaussmeter
-########################
+#########################
+Lake Shore 425 Gaussmeter
+#########################
 
 .. autoclass:: pymeasure.instruments.lakeshore.LakeShore425
     :members:

pymeasure/instruments/lakeshore/lakeshore331.py

@@ -22,21 +22,100 @@
 # THE SOFTWARE.
 #
 
+import logging
+log = logging.getLogger(__name__)
+log.addHandler(logging.NullHandler())
+
+from time import sleep, time
+
 from pymeasure.instruments import Instrument
+from pymeasure.instruments.validators import strict_discrete_set
 
 
 class LakeShore331(Instrument):
-    """Instrument object for the Lake Shore 331 Temperature Controller"""
+    """ Represents the Lake Shore 331 Temperature Controller and provides
+    a high-level interface for interacting with the instrument.
+
+    .. code-block:: python
+
+        controller = LakeShore331("GPIB::1")
+
+        print(controller.setpoint_1)        # Print the current setpoint for loop 1
+        controller.setpoint_1 = 50          # Change the setpoint to 50 K
+        controller.heater_range = 'low'     # Change the heater range to Low
+        controller.wait_for_temperature()   # Wait for the temperature to stabilize
+        print(controller.temperature_A)     # Print the temperature at sensor A
+
+    """
+
+    temperature_A = Instrument.measurement(
+        "KRDG? A",
+        """ Reads the temperature of the sensor A in Kelvin. """
+    )
+    temperature_B = Instrument.measurement(
+        "KRDG? B",
+        """ Reads the temperature of the sensor B in Kelvin. """
+    )
+    setpoint_1 = Instrument.control(
+        "SETP? 1", "SETP 1, %g",
+        """ A floating point property that controls the setpoint temperature
+        in Kelvin for Loop 1. """
+    )
+    setpoint_2 = Instrument.control(
+        "SETP? 2", "SETP 2, %g",
+        """ A floating point property that controls the setpoint temperature
+        in Kelvin for Loop 2. """
+    )
+    heater_range = Instrument.control(
+        "RANGE?", "RANGE %d",
+        """ A string property that controls the heater range, which
+        can take the values: off, low, medium, and high. These values
+        correlate to 0, 0.5, 5 and 50 W respectively. """,
+        validator=strict_discrete_set,
+        values={'off':0, 'low':1, 'medium':2, 'high':3},
+        map_values=True
+    )
 
     def __init__(self, adapter, **kwargs):
-        super(Lakeshore331, self).__init__(
+        super(LakeShore331, self).__init__(
             adapter,
-            "Lakeshore 331 Temperature Controller",
+            "Lake Shore 331 Temperature Controller",
             **kwargs
         )
 
-    @property
-    def temperature(self):
-        """ Temperature in Kelvin
+    def disable_heater(self):
+        """ Turns the :attr:`~.heater_range` to :code:`off` to disable the heater. """
+        self.heater_range = 'off'
+
+    def wait_for_temperature(self, accuracy=0.1, 
+            interval=0.1, sensor='A', setpoint=1, timeout=360,
+            should_stop=lambda: False):
+        """ Blocks the program, waiting for the temperature to reach the setpoint
+        within the accuracy (%), checking this each interval time in seconds.
+
+        :param accuracy: An acceptable percentage deviation between the 
+                         setpoint and temperature
+        :param interval: A time in seconds that controls the refresh rate
+        :param sensor: The desired sensor to read, either A or B
+        :param setpoint: The desired setpoint loop to read, either 1 or 2
+        :param timeout: A timeout in seconds after which an exception is raised
+        :param should_stop: A function that returns True if waiting should stop, by
+                            default this always returns False
         """
-        return self.ask("KRDG?")
+        temperature_name = 'temperature_%s' % sensor
+        setpoint_name = 'setpoint_%d' % setpoint
+        # Only get the setpoint once, assuming it does not change
+        setpoint_value = getattr(self, setpoint_name)
+        def percent_difference(temperature):
+            return abs(100*(temperature - setpoint_value)/setpoint_value)
+        t = time()
+        while percent_difference(getattr(self, temperature_name)) > accuracy:
+            sleep(interval)
+            if (time()-t) > timeout:
+                raise Exception((
+                    "Timeout occurred after waiting %g seconds for "
+                    "the LakeShore 331 temperature to reach %g K."
+                ) % (timeout, setpoint))
+            if should_stop():
+                return
+