Debian Codegraph @

pymeasure/instruments/oxfordinstruments/itc503.py

raw
1 #
2 # This file is part of the PyMeasure package.
3 #
4 # Copyright (c) 2013-2024 PyMeasure Developers
5 #
6 # Permission is hereby granted, free of charge, to any person obtaining a copy
7 # of this software and associated documentation files (the "Software"), to deal
8 # in the Software without restriction, including without limitation the rights
9 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 # copies of the Software, and to permit persons to whom the Software is
11 # furnished to do so, subject to the following conditions:
12 #
13 # The above copyright notice and this permission notice shall be included in
14 # all copies or substantial portions of the Software.
15 #
16 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 # THE SOFTWARE.
23 #
24
25
26 import logging
27 from time import sleep, time
28 from enum import IntFlag
29
30 import numpy as np
31
32 from pymeasure.instruments import Instrument
33 from pymeasure.instruments.validators import strict_discrete_set, \
34 truncated_range, strict_range
35
36 from .base import OxfordInstrumentsBase
37
38 # Setup logging
39 log = logging.getLogger(__name__)
40 log.addHandler(logging.NullHandler())
41
42
43 def pointer_validator(value, values):
44 """ Provides a validator function that ensures the passed value is
45 a tuple or a list with a length of 2 and passes every item through
46 the strict_range validator.
47
48 :param value: A value to test
49 :param values: A range of values (passed to strict_range)
50 :raises: TypeError if the value is not a tuple or a list
51 :raises: IndexError if the value is not of length 2
52 """
53
54 if not isinstance(value, (list, tuple)):
55 raise TypeError('{:g} is not a list or tuple'.format(value))
56 if not len(value) == 2:
57 raise IndexError('{:g} is not of length 2'.format(value))
58 return tuple(strict_range(v, values) for v in value)
59
60
61 class ITC503(OxfordInstrumentsBase):
62 """Represents the Oxford Intelligent Temperature Controller 503.
63
64 .. code-block:: python
65
66 itc = ITC503("GPIB::24") # Default channel for the ITC503
67
68 itc.control_mode = "RU" # Set the control mode to remote
69 itc.heater_gas_mode = "AUTO" # Turn on auto heater and flow
70 itc.auto_pid = True # Turn on auto-pid
71
72 print(itc.temperature_setpoint) # Print the current set-point
73 itc.temperature_setpoint = 300 # Change the set-point to 300 K
74 itc.wait_for_temperature() # Wait for the temperature to stabilize
75 print(itc.temperature_1) # Print the temperature at sensor 1
76
77 """
78
79 def __init__(self,
80 adapter,
81 name="Oxford ITC503",
82 clear_buffer=True,
83 min_temperature=0,
84 max_temperature=1677.7,
85 **kwargs):
86
87 super().__init__(
88 adapter=adapter,
89 name=name,
90 **kwargs,
91 )
92
93 # Clear the buffer in order to prevent communication problems
94 if clear_buffer:
95 self.adapter.connection.clear()
96
97 self.temperature_setpoint_values = [min_temperature, max_temperature]
98
99 class FLOW_CONTROL_STATUS(IntFlag):
100 """ IntFlag class for decoding the flow control status. Contains the following
101 flags:
102
103 === ====================== ==============================================
104 bit flag meaning
105 === ====================== ==============================================
106 4 HEATER_ERROR_SIGN Sign of heater-error; True means negative
107 3 TEMPERATURE_ERROR_SIGN Sign of temperature-error; True means negative
108 2 SLOW_VALVE_ACTION Slow valve action occurring
109 1 COOLDOWN_TERMINATION Cooldown-termination occurring
110 0 FAST_COOLDOWN Fast-cooldown occurring
111 === ====================== ==============================================
112
113 """
114 HEATER_ERROR_SIGN = 16
115 TEMPERATURE_ERROR_SIGN = 8
116 SLOW_VALVE_ACTION = 4
117 COOLDOWN_TERMINATION = 2
118 FAST_COOLDOWN = 1
119
120 version = Instrument.measurement(
121 "V",
122 """ A string property that returns the version of the IPS. """,
123 preprocess_reply=lambda v: v,
124 )
125
126 control_mode = Instrument.control(
127 "X", "C%d",
128 """ A string property that sets the ITC in `local` or `remote` and `locked`
129 or `unlocked`, locking the LOC/REM button. Allowed values are:
130
131 ===== =================
132 value state
133 ===== =================
134 LL local & locked
135 RL remote & locked
136 LU local & unlocked
137 RU remote & unlocked
138 ===== =================
139 """,
140 preprocess_reply=lambda v: v[5:6],
141 cast=int,
142 validator=strict_discrete_set,
143 values={"LL": 0, "RL": 1, "LU": 2, "RU": 3},
144 map_values=True,
145 )
146
147 heater_gas_mode = Instrument.control(
148 "X", "A%d",
149 """ A string property that sets the heater and gas flow control to
150 `auto` or `manual`. Allowed values are:
151
152 ====== =======================
153 value state
154 ====== =======================
155 MANUAL heater & gas manual
156 AM heater auto, gas manual
157 MA heater manual, gas auto
158 AUTO heater & gas auto
159 ====== =======================
160 """,
161 preprocess_reply=lambda v: v[3:4],
162 cast=int,
163 validator=strict_discrete_set,
164 values={"MANUAL": 0, "AM": 1, "MA": 2, "AUTO": 3},
165 map_values=True,
166 )
167
168 heater = Instrument.control(
169 "R5", "O%f",
170 """ A floating point property that represents the heater output power
171 as a percentage of the maximum voltage. Can be set if the heater is in
172 manual mode. Valid values are in range 0 [off] to 99.9 [%]. """,
173 validator=truncated_range,
174 values=[0, 99.9]
175 )
176
177 heater_voltage = Instrument.measurement(
178 "R6",
179 """ A floating point property that represents the heater output power
180 in volts. For controlling the heater, use the :class:`ITC503.heater`
181 property. """,
182 )
183
184 gasflow = Instrument.control(
185 "R7", "G%f",
186 """ A floating point property that controls gas flow when in manual
187 mode. The value is expressed as a percentage of the maximum gas flow.
188 Valid values are in range 0 [off] to 99.9 [%]. """,
189 validator=truncated_range,
190 values=[0, 99.9]
191 )
192
193 proportional_band = Instrument.control(
194 "R8", "P%f",
195 """ A floating point property that controls the proportional band
196 for the PID controller in Kelvin. Can be set if the PID controller
197 is in manual mode. Valid values are 0 [K] to 1677.7 [K]. """,
198 validator=truncated_range,
199 values=[0, 1677.7]
200 )
201
202 integral_action_time = Instrument.control(
203 "R9", "I%f",
204 """ A floating point property that controls the integral action time
205 for the PID controller in minutes. Can be set if the PID controller
206 is in manual mode. Valid values are 0 [min.] to 140 [min.]. """,
207 validator=truncated_range,
208 values=[0, 140]
209 )
210
211 derivative_action_time = Instrument.control(
212 "R10", "D%f",
213 """ A floating point property that controls the derivative action time
214 for the PID controller in minutes. Can be set if the PID controller
215 is in manual mode. Valid values are 0 [min.] to 273 [min.]. """,
216 validator=truncated_range,
217 values=[0, 273]
218 )
219
220 auto_pid = Instrument.control(
221 "X", "L%d",
222 """ A boolean property that sets the Auto-PID mode on (True) or off (False).
223 """,
224 preprocess_reply=lambda v: v[12:13],
225 cast=int,
226 validator=strict_discrete_set,
227 values={True: 1, False: 0},
228 map_values=True,
229 )
230
231 sweep_status = Instrument.control(
232 "X", "S%d",
233 """ An integer property that sets the sweep status. Values are:
234
235 ========= =========================================
236 value meaning
237 ========= =========================================
238 0 Sweep not running
239 1 Start sweep / sweeping to first set-point
240 2P - 1 Sweeping to set-point P
241 2P Holding at set-point P
242 ========= =========================================
243 """,
244 preprocess_reply=lambda v: v[7:9],
245 cast=int,
246 validator=strict_range,
247 values=[0, 32]
248 )
249
250 temperature_setpoint = Instrument.control(
251 "R0", "T%f",
252 """ A floating point property that controls the temperature set-point of
253 the ITC in kelvin. """,
254 validator=truncated_range,
255 values=[0, 1677.7], # Kelvin, 0 - 1677.7K is the maximum range of the instrument
256 dynamic=True,
257 )
258
259 temperature_1 = Instrument.measurement(
260 "R1",
261 """ Reads the temperature of the sensor 1 in Kelvin. """,
262 )
263
264 temperature_2 = Instrument.measurement(
265 "R2",
266 """ Reads the temperature of the sensor 2 in Kelvin. """,
267 )
268
269 temperature_3 = Instrument.measurement(
270 "R3",
271 """ Reads the temperature of the sensor 3 in Kelvin. """,
272 )
273
274 temperature_error = Instrument.measurement(
275 "R4",
276 """ Reads the difference between the set-point and the measured
277 temperature in Kelvin. Positive when set-point is larger than
278 measured. """,
279 )
280
281 front_panel_display = Instrument.setting(
282 "F%d",
283 """ A string property that controls what value is displayed on
284 the front panel of the ITC. Valid values are:
285 'temperature setpoint', 'temperature 1', 'temperature 2',
286 'temperature 3', 'temperature error', 'heater', 'heater voltage',
287 'gasflow', 'proportional band', 'integral action time',
288 'derivative action time', 'channel 1 freq/4', 'channel 2 freq/4',
289 'channel 3 freq/4'.
290 """,
291 validator=strict_discrete_set,
292 map_values=True,
293 values={
294 "temperature setpoint": 0,
295 "temperature 1": 1,
296 "temperature 2": 2,
297 "temperature 3": 3,
298 "temperature error": 4,
299 "heater": 5,
300 "heater voltage": 6,
301 "gasflow": 7,
302 "proportional band": 8,
303 "integral action time": 9,
304 "derivative action time": 10,
305 "channel 1 freq/4": 11,
306 "channel 2 freq/4": 12,
307 "channel 3 freq/4": 13,
308 },
309 )
310
311 x_pointer = Instrument.setting(
312 "x%d",
313 """ An integer property to set pointers into tables for loading and
314 examining values in the table. The significance and valid values for
315 the pointer depends on what property is to be read or set. """,
316 validator=strict_range,
317 values=[0, 128]
318 )
319
320 y_pointer = Instrument.setting(
321 "y%d",
322 """ An integer property to set pointers into tables for loading and
323 examining values in the table. The significance and valid values for
324 the pointer depends on what property is to be read or set. """,
325 validator=strict_range,
326 values=[0, 128]
327 )
328
329 pointer = Instrument.setting(
330 "$x%d\r$y%d",
331 """ A tuple property to set pointers into tables for loading and
332 examining values in the table, of format (x, y). The significance
333 and valid values for the pointer depends on what property is to be
334 read or set. The value for x and y can be in the range 0 to 128. """,
335 validator=pointer_validator,
336 values=[0, 128]
337 )
338
339 sweep_table = Instrument.control(
340 "r", "s%f",
341 """ A property that controls values in the sweep table. Relies on
342 :class:`ITC503.x_pointer` and :class:`ITC503.y_pointer` (or
343 :class:`ITC503.pointer`) to point at the location in the table that is
344 to be set or read.
345
346 The x-pointer selects the step of the sweep (1 to 16); the y-pointer
347 selects the parameter:
348
349 ========= =======================
350 y-pointer parameter
351 ========= =======================
352 1 set-point temperature
353 2 sweep-time to set-point
354 3 hold-time at set-point
355 ========= =======================
356 """,
357 )
358
359 auto_pid_table = Instrument.control(
360 "q", "p%f",
361 """ A property that controls values in the auto-pid table. Relies on
362 :class:`ITC503.x_pointer` and :class:`ITC503.y_pointer` (or
363 :class:`ITC503.pointer`) to point at the location in the table that
364 is to be set or read.
365
366 The x-pointer selects the table entry (1 to 16); the y-pointer
367 selects the parameter:
368
369 ========= =======================
370 y-pointer parameter
371 ========= =======================
372 1 upper temperature limit
373 2 proportional band
374 3 integral action time
375 4 derivative action time
376 ========= =======================
377 """,
378 )
379
380 target_voltage_table = Instrument.control(
381 "t", "v%f",
382 """ A property that controls values in the target heater voltage table.
383 Relies on the :class:`ITC503.x_pointer` to select the entry in the table
384 that is to be set or read (1 to 64).
385 """,
386 )
387
388 gasflow_configuration_parameter = Instrument.control(
389 "d", "c%f",
390 """ A property that controls the gas flow configuration parameters.
391 Relies on the :class:`ITC503.x_pointer` to select which parameter
392 is set or read:
393
394 ========= =====================================
395 x-pointer parameter
396 ========= =====================================
397 1 valve gearing
398 2 target table & features configuration
399 3 gas flow scaling
400 4 temperature error sensitivity
401 5 heater voltage error sensitivity
402 6 minimum gas valve in auto
403 ========= =====================================
404 """,
405 )
406
407 gasflow_control_status = Instrument.measurement(
408 "m",
409 """ A property that reads the gas-flow control status. Returns
410 the status in the form of a :class:`ITC503.FLOW_CONTROL_STATUS`
411 IntFlag. """,
412 cast=int,
413 get_process=lambda v: ITC503.FLOW_CONTROL_STATUS(v),
414 )
415
416 target_voltage = Instrument.measurement(
417 "n",
418 """ A float property that reads the current heater target voltage
419 with which the actual heater voltage is being compared. Only valid
420 if gas-flow in auto mode. """,
421 )
422
423 valve_scaling = Instrument.measurement(
424 "o",
425 """ A float property that reads the valve scaling parameter. Only
426 valid if gas-flow in auto mode. """,
427 )
428
429 def wait_for_temperature(self,
430 error=0.01,
431 timeout=3600,
432 check_interval=0.5,
433 stability_interval=10,
434 thermalize_interval=300,
435 should_stop=lambda: False,
436 ):
437 """
438 Wait for the ITC to reach the set-point temperature.
439
440 :param error: The maximum error in Kelvin under which the temperature
441 is considered at set-point
442 :param timeout: The maximum time the waiting is allowed to take. If
443 timeout is exceeded, a TimeoutError is raised. If
444 timeout is None, no timeout will be used.
445 :param check_interval: The time between temperature queries to the ITC.
446 :param stability_interval: The time over which the temperature_error is
447 to be below error to be considered stable.
448 :param thermalize_interval: The time to wait after stabilizing for the
449 system to thermalize.
450 :param should_stop: Optional function (returning a bool) to allow the
451 waiting to be stopped before its end.
452 """
453
454 number_of_intervals = int(stability_interval / check_interval)
455 stable_intervals = 0
456 attempt = 0
457
458 t0 = time()
459 while True:
460 temp_error = self.temperature_error
461 if abs(temp_error) < error:
462 stable_intervals += 1
463 else:
464 stable_intervals = 0
465 attempt += 1
466
467 if stable_intervals >= number_of_intervals:
468 break
469
470 if timeout is not None and (time() - t0) > timeout:
471 raise TimeoutError(
472 "Timeout expired while waiting for the Oxford ITC305 to "
473 "reach the set-point temperature"
474 )
475
476 if should_stop():
477 return
478
479 sleep(check_interval)
480
481 if attempt == 0:
482 return
483
484 t1 = time() + thermalize_interval
485 while time() < t1:
486 sleep(check_interval)
487 if should_stop():
488 return
489
490 return
491
492 def program_sweep(self, temperatures, sweep_time, hold_time, steps=None):
493 """
494 Program a temperature sweep in the controller. Stops any running sweep.
495 After programming the sweep, it can be started using
496 OxfordITC503.sweep_status = 1.
497
498 :param temperatures: An array containing the temperatures for the sweep
499 :param sweep_time: The time (or an array of times) to sweep to a
500 set-point in minutes (between 0 and 1339.9).
501 :param hold_time: The time (or an array of times) to hold at a
502 set-point in minutes (between 0 and 1339.9).
503 :param steps: The number of steps in the sweep, if given, the
504 temperatures, sweep_time and hold_time will be
505 interpolated into (approximately) equal segments
506 """
507 # Check if in remote control
508 if not self.control_mode.startswith("R"):
509 raise AttributeError(
510 "Oxford ITC503 not in remote control mode"
511 )
512
513 # Stop sweep if running to be able to write the program
514 self.sweep_status = 0
515
516 # Convert input np.ndarrays
517 temperatures = np.array(temperatures, ndmin=1)
518 sweep_time = np.array(sweep_time, ndmin=1)
519 hold_time = np.array(hold_time, ndmin=1)
520
521 # Make steps array
522 if steps is None:
523 steps = temperatures.size
524 steps = np.linspace(1, steps, steps)
525
526 # Create interpolated arrays
527 interpolator = np.round(
528 np.linspace(1, steps.size, temperatures.size))
529 temperatures = np.interp(steps, interpolator, temperatures)
530
531 interpolator = np.round(
532 np.linspace(1, steps.size, sweep_time.size))
533 sweep_time = np.interp(steps, interpolator, sweep_time)
534
535 interpolator = np.round(
536 np.linspace(1, steps.size, hold_time.size))
537 hold_time = np.interp(steps, interpolator, hold_time)
538
539 # Pad with zeros to wipe unused steps (total 16) of the sweep program
540 padding = 16 - temperatures.size
541 temperatures = np.pad(temperatures, (0, padding), 'constant',
542 constant_values=temperatures[-1])
543 sweep_time = np.pad(sweep_time, (0, padding), 'constant')
544 hold_time = np.pad(hold_time, (0, padding), 'constant')
545
546 # Setting the arrays to the controller
547 for line, (setpoint, sweep, hold) in \
548 enumerate(zip(temperatures, sweep_time, hold_time), 1):
549 self.pointer = (line, 1)
550 self.sweep_table = setpoint
551
552 self.pointer = (line, 2)
553 self.sweep_table = sweep
554
555 self.pointer = (line, 3)
556 self.sweep_table = hold
557
558 def wipe_sweep_table(self):
559 """ Wipe the currently programmed sweep table. """
560 self.write("w")