Debian Codegraph @

pymeasure/instruments/oxfordinstruments/ips120_10.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
29 from pymeasure.instruments import Instrument
30 from pymeasure.instruments.validators import strict_discrete_set
31 from pymeasure.instruments.validators import truncated_range
32
33 from .base import OxfordInstrumentsBase
34
35 # Setup logging
36 log = logging.getLogger(__name__)
37 log.addHandler(logging.NullHandler())
38
39
40 class MagnetError(ValueError):
41 """ Exception that is raised for issues regarding the state of the magnet or power supply. """
42 pass
43
44
45 class SwitchHeaterError(ValueError):
46 """ Exception that is raised for issues regarding the state of the superconducting switch. """
47 pass
48
49
50 class IPS120_10(OxfordInstrumentsBase):
51 """Represents the Oxford Superconducting Magnet Power Supply IPS 120-10.
52
53 .. code-block:: python
54
55 ips = IPS120_10("GPIB::25") # Default channel for the IPS
56
57 ips.enable_control() # Enables the power supply and remote control
58
59 ips.train_magnet([ # Train the magnet after it has been cooled-down
60 (11.8, 1.0),
61 (13.9, 0.4),
62 (14.9, 0.2),
63 (16.0, 0.1),
64 ])
65
66 ips.set_field(12) # Bring the magnet to 12 T. The switch heater will
67 # be turned off when the field is reached and the
68 # current is ramped back to 0 (i.e. persistent mode).
69
70 print(self.field) # Print the current field (whether in persistent or
71 # non-persistent mode)
72
73 ips.set_field(0) # Bring the magnet to 0 T. The persistent mode will be
74 # turned off first (i.e. current back to set-point and
75 # switch-heater on); afterwards the switch-heater will
76 # again be turned off.
77
78 ips.disable_control() # Disables the control of the supply, turns off the
79 # switch-heater and clamps the output.
80
81 :param clear_buffer: A boolean property that controls whether the instrument
82 buffer is clear upon initialisation.
83 :param switch_heater_heating_delay: The time in seconds (default is 20s) to wait after
84 the switch-heater is turned on before the heater is expected to be heated.
85 :param switch_heater_cooling_delay: The time in seconds (default is 20s) to wait after
86 the switch-heater is turned off before the heater is expected to be cooled down.
87 :param field_range: A numeric value or a tuple of two values to indicate the
88 lowest and highest allowed magnetic fields. If a numeric value is provided
89 the range is expected to be from :code:`-field_range` to :code:`+field_range`.
90 The default range is -7 to +7 Tesla.
91
92 """
93
94 _SWITCH_HEATER_HEATING_DELAY = 20 # Seconds
95 _SWITCH_HEATER_COOLING_DELAY = 20 # Seconds
96
97 _SWITCH_HEATER_SET_VALUES = {
98 False: 0, # Heater off
99 True: 1, # Heater on, with safety checks
100 "Force": 2, # Heater on, without safety checks
101 }
102 _SWITCH_HEATER_GET_VALUES = {
103 0: False, # Heater off, Switch closed, Magnet at zero
104 1: True, # Heater on, Switch open
105 2: False, # Heater off, Switch closed, Magnet at field
106 5: "Heater fault, low heater current", # Heater on but current is low
107 8: "No switch fitted", # No switch fitted
108 }
109
110 def __init__(self,
111 adapter,
112 name="Oxford IPS",
113 clear_buffer=True,
114 switch_heater_heating_delay=None,
115 switch_heater_cooling_delay=None,
116 field_range=None,
117 **kwargs):
118
119 super().__init__(
120 adapter=adapter,
121 name=name,
122 **kwargs
123 )
124
125 if switch_heater_heating_delay is not None:
126 self._SWITCH_HEATER_HEATING_DELAY = switch_heater_heating_delay
127 if switch_heater_cooling_delay is not None:
128 self._SWITCH_HEATER_COOLING_DELAY = switch_heater_cooling_delay
129
130 if field_range is not None:
131 if isinstance(field_range, (float, int)):
132 self.field_setpoint_values = [-field_range, +field_range]
133 elif isinstance(field_range, (list, tuple)):
134 self.field_setpoint_values = field_range
135
136 # Clear the buffer in order to prevent communication problems
137 if clear_buffer:
138 self.adapter.connection.clear()
139
140 version = Instrument.measurement(
141 "V",
142 """ A string property that returns the version of the IPS. """,
143 )
144
145 control_mode = Instrument.control(
146 "X", "C%d",
147 """ A string property that sets the IPS in `local` or `remote` and `locked`
148 or `unlocked`, locking the LOC/REM button. Allowed values are:
149
150 ===== =================
151 value state
152 ===== =================
153 LL local & locked
154 RL remote & locked
155 LU local & unlocked
156 RU remote & unlocked
157 ===== =================
158 """,
159 preprocess_reply=lambda v: v[6],
160 cast=int,
161 validator=strict_discrete_set,
162 values={"LL": 0, "RL": 1, "LU": 2, "RU": 3},
163 map_values=True,
164 )
165
166 current_measured = Instrument.measurement(
167 "R1",
168 """ A floating point property that returns the measured magnet current of
169 the IPS in amps. """,
170 dynamic=True,
171 )
172
173 demand_current = Instrument.measurement(
174 "R0",
175 """ A floating point property that returns the demand magnet current of
176 the IPS in amps. """,
177 dynamic=True,
178 )
179
180 demand_field = Instrument.measurement(
181 "R7",
182 """ A floating point property that returns the demand magnetic field of
183 the IPS in Tesla. """,
184 dynamic=True,
185 )
186
187 persistent_field = Instrument.measurement(
188 "R18",
189 """ A floating point property that returns the persistent magnetic field of
190 the IPS in Tesla. """,
191 dynamic=True,
192 )
193
194 switch_heater_status = Instrument.control(
195 "X", "H%d",
196 """ An integer property that returns the switch heater status of
197 the IPS. Use the :py:attr:`~switch_heater_enabled` property for controlling
198 and reading the switch heater. When using this property, the user
199 is referred to the IPS120-10 manual for the meaning of the integer
200 values. """,
201 preprocess_reply=lambda v: v[8],
202 cast=int,
203 )
204
205 @property
206 def switch_heater_enabled(self):
207 """ A boolean property that controls whether the switch heater
208 is enabled or not. When the switch heater is enabled (:code:`True`), the
209 switch is closed and the switch is open and the current in the
210 magnet can be controlled; when the switch heater is disabled
211 (:code:`False`) the switch is closed and the current in the magnet cannot
212 be controlled.
213
214 When turning on the switch heater with :code:`True`, the switch heater is
215 only activated if the current of the power supply matches the last
216 recorded current in the magnet.
217
218 .. warning::
219 These checks can be omitted by using :code:`"Force"` in stead of
220 :code:`True`. Caution: Not performing these checks can cause serious
221 damage to both the power supply and the magnet.
222
223 After turning on the switch heater it is necessary to wait several
224 seconds for the switch the respond.
225
226 Raises a :class:`.SwitchHeaterError` if the system reports a 'heater fault'
227 or if no switch is fitted on the system upon getting the status.
228 """
229 status_value = self.switch_heater_status
230 status = self._SWITCH_HEATER_GET_VALUES[status_value]
231
232 if isinstance(status, str):
233 raise SwitchHeaterError(
234 "IPS 120-10: switch heater status reported issue with "
235 "switch heater: %s" % status)
236
237 return status
238
239 @switch_heater_enabled.setter
240 def switch_heater_enabled(self, value):
241
242 status_value = self._SWITCH_HEATER_SET_VALUES[value]
243
244 if status_value == 2:
245 log.info("IPS 120-10: Turning on the switch heater without any safety checks.")
246
247 self.switch_heater_status = status_value
248
249 current_setpoint = Instrument.control(
250 "R0", "I%f",
251 """ A floating point property that controls the magnet current set-point of
252 the IPS in ampere. """,
253 validator=truncated_range,
254 values=[0, 120], # Ampere
255 dynamic=True,
256 )
257
258 field_setpoint = Instrument.control(
259 "R8", "J%f",
260 """ A floating point property that controls the magnetic field set-point of
261 the IPS in Tesla. """,
262 validator=truncated_range,
263 values=[-7, 7], # Tesla
264 dynamic=True,
265 )
266
267 sweep_rate = Instrument.control(
268 "R9", "T%f",
269 """ A floating point property that controls the sweep-rate of
270 the IPS in Tesla/minute. """,
271 dynamic=True,
272 )
273
274 activity = Instrument.control(
275 "X", "A%d",
276 """ A string property that controls the activity of the IPS. Valid values
277 are "hold", "to setpoint", "to zero" and "clamp" """,
278 preprocess_reply=lambda v: v[4],
279 cast=int,
280 values={"hold": 0, "to setpoint": 1, "to zero": 2, "clamp": 4},
281 map_values=True,
282 )
283
284 sweep_status = Instrument.measurement(
285 "X",
286 """ A string property that returns the current sweeping mode of the IPS. """,
287 preprocess_reply=lambda v: v[11],
288 cast=int,
289 values={"at rest": 0, "sweeping": 1, "sweep limiting": 2, "sweeping & sweep limiting": 3},
290 map_values=True,
291 )
292
293 @property
294 def field(self):
295 """ Property that returns the current magnetic field value in Tesla.
296 """
297
298 try:
299 heater_on = self.switch_heater_enabled
300 except SwitchHeaterError as e:
301 log.error("IPS 120-10: Switch heater status reported issue: %s" % e)
302 field = self.demand_field
303 else:
304 if heater_on:
305 field = self.demand_field
306 else:
307 field = self.persistent_field
308
309 return field
310
311 def enable_control(self):
312 """ Enable active control of the IPS by setting control to remote and
313 turning off the clamp.
314 """
315 log.debug("start enabling control")
316 self.control_mode = "RU"
317
318 # Turn off clamping if still clamping
319 if self.activity == "clamp":
320 self.activity = "hold"
321
322 # Turn on switch-heater if field at zero
323 if self.field == 0:
324 log.debug("enabling switch heater")
325 self.switch_heater_enabled = True
326
327 def disable_control(self):
328 """ Disable active control of the IPS (if at 0T) by turning off the switch heater,
329 clamping the output and setting control to local.
330 Raise a :class:`.MagnetError` if field not at 0T. """
331 log.debug("start disabling control")
332 if not self.field == 0:
333 raise MagnetError("IPS 120-10: field not at 0T; cannot disable the supply. ")
334
335 log.debug("disabling switch heater")
336 self.switch_heater_enabled = False
337 self.activity = "clamp"
338 self.control_mode = "LU"
339
340 def enable_persistent_mode(self):
341 """ Enable the persistent magnetic field mode.
342 Raise a :class:`.MagnetError` if the magnet is not at rest. """
343 # Check if system idle
344 log.debug("enabling persistent mode")
345 if not self.sweep_status == "at rest":
346 raise MagnetError("IPS 120-10: magnet not at rest; cannot enable persistent mode")
347
348 if not self.switch_heater_enabled:
349 log.debug("magnet already in persistent mode")
350 return # Magnet already in persistent mode
351 else:
352 self.activity = "hold"
353 self.switch_heater_enabled = False
354 log.info("IPS 120-10: Wait for for switch heater delay")
355 sleep(self._SWITCH_HEATER_COOLING_DELAY)
356 self.activity = "to zero"
357 self.wait_for_idle()
358
359 def disable_persistent_mode(self):
360 """ Disable the persistent magnetic field mode.
361 Raise a :class:`.MagnetError` if the magnet is not at rest. """
362 # Check if system idle
363 log.debug("disabling persistent mode")
364 if not self.sweep_status == "at rest":
365 raise MagnetError("IPS 120-10: magnet not at rest; cannot disable persistent mode")
366
367 # Check if the setpoint equals the persistent field
368 if not self.field == self.field_setpoint:
369 log.warning("IPS 120-10: field setpoint and persistent field not identical; "
370 "setting the setpoint to the persistent field.")
371 self.field_setpoint = self.field
372
373 if self.switch_heater_enabled:
374 log.debug("magnet already in demand mode or at 0 field")
375 return # Magnet already in demand mode or at 0 field
376 else:
377 log.debug("set activity to 'to setpoint'")
378 self.activity = "to setpoint"
379 self.wait_for_idle()
380 log.debug("set activity to 'hold'")
381 self.activity = "hold"
382 log.debug("enable switch heater")
383 self.switch_heater_enabled = True
384 log.info("IPS 120-10: Wait for for switch heater delay")
385 sleep(self._SWITCH_HEATER_HEATING_DELAY)
386
387 def wait_for_idle(self, delay=1, max_wait_time=None, should_stop=lambda: False):
388 """ Wait until the system is at rest (i.e. current of field not ramping).
389
390 :param delay: Time in seconds between each query into the state of the instrument.
391 :param max_wait_time: Maximum time in seconds to wait before is at rest. If the system is
392 not at rest within this time a :class:`TimeoutError` is raised. :code:`None` is
393 interpreted as no maximum time.
394 :param should_stop: A function that returns :code:`True` when this function should return
395 early.
396 """
397 log.debug("waiting for magnet to be idle")
398 start_time = time()
399
400 while True:
401 log.debug("sleeping for %d s", delay)
402 sleep(delay)
403
404 log.debug("checking the status of the sweep")
405 status = self.sweep_status
406
407 if status == "at rest":
408 log.debug("status is 'at rest', waiting is done")
409 break
410 if should_stop():
411 log.debug("external function signals to stop waiting")
412 break
413
414 if max_wait_time is not None and time() - start_time > max_wait_time:
415 raise TimeoutError("IPS 120-10: Magnet not idle within max wait time.")
416
417 def set_field(self, field, sweep_rate=None, persistent_mode_control=True):
418 """ Change the applied magnetic field to a new specified magnitude.
419 If allowed (via `persistent_mode_control`) the persistent mode will be turned off
420 if needed and turned on when the magnetic field is reached.
421 When the new field set-point is 0, the set-point of the instrument will not be changed
422 but rather the `to zero` functionality will be used. Also, the persistent mode will not
423 turned on upon reaching the 0T field in this case.
424
425 :param field: The new set-point for the magnetic field in Tesla.
426 :param sweep_rate: A numeric value that controls the rate with which to change
427 the magnetic field in Tesla/minute.
428 :param persistent_mode_control: A boolean that controls whether the persistent mode
429 may be turned off (if needed before sweeping) and on (when the field is reached);
430 if set to :code:`False` but the system is in persistent mode, a :class:`.MagnetError`
431 will be raised and the magnetic field will not be changed.
432
433 """
434
435 # Check if field needs changing
436 if self.field == field:
437 return
438
439 if self.switch_heater_enabled:
440 pass # Magnet in demand mode
441 log.debug("Magnet in demand mode, continuing")
442 else:
443 # Magnet in persistent mode
444 log.debug("Magnet in persistent mode")
445 if persistent_mode_control:
446 log.debug("trying to disable persistent mode")
447 self.disable_persistent_mode()
448 else:
449 raise MagnetError(
450 "IPS 120-10: magnet is in persistent mode but cannot turn off "
451 "persistent mode because persistent_mode_control == False. "
452 )
453
454 if sweep_rate is not None:
455 log.debug("setting the sweep rate to %s", sweep_rate)
456 self.sweep_rate = sweep_rate
457
458 if field == 0:
459 log.debug("setting activity to 'to zero' - running down the field")
460 self.activity = "to zero"
461 else:
462 log.debug("setting activity to 'to setpoint'")
463 self.activity = "to setpoint"
464 log.debug("setting the field_setpoint to %d", field)
465 self.field_setpoint = field
466
467 log.debug("waiting for magnet to be finished")
468 self.wait_for_idle()
469 log.debug("sleeping for additional 10s (whatever the reason)")
470 sleep(10)
471
472 if persistent_mode_control and field != 0:
473 log.debug(
474 "persistent mode control is on, and setpoint_field !=0 - enabling persistent mode"
475 )
476 self.enable_persistent_mode()
477
478 def train_magnet(self, training_scheme):
479 """ Train the magnet after cooling down. Afterwards, set the field
480 back to 0 tesla (at last-used ramp-rate).
481
482 :param training_scheme: The training scheme as a list of tuples; each
483 tuple should consist of a (field [T], ramp-rate [T/min]) pair.
484 """
485
486 for (field, rate) in training_scheme:
487 self.set_field(field, rate, persistent_mode_control=False)
488
489 self.set_field(0)