Debian Codegraph @

pymeasure/experiment/procedure.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 import logging
26 import sys
27 import inspect
28 from copy import deepcopy
29 from importlib.machinery import SourceFileLoader
30 import re
31 from pint import UndefinedUnitError
32
33 from .parameters import Parameter, Measurable, Metadata
34 from pymeasure.units import ureg
35
36 log = logging.getLogger()
37 log.addHandler(logging.NullHandler())
38
39
40 class Procedure:
41 """Provides the base class of a procedure to organize the experiment
42 execution. Procedures should be run by Workers to ensure that
43 asynchronous execution is properly managed.
44
45 .. code-block:: python
46
47 procedure = Procedure()
48 results = Results(procedure, data_filename)
49 worker = Worker(results, port)
50 worker.start()
51
52 Inheriting classes should define the startup, execute, and shutdown
53 methods as needed. The shutdown method is called even with a
54 software exception or abort event during the execute method.
55
56 If keyword arguments are provided, they are added to the object as
57 attributes.
58 """
59
60 DATA_COLUMNS = []
61 MEASURE = {}
62 FINISHED, FAILED, ABORTED, QUEUED, RUNNING = 0, 1, 2, 3, 4
63 STATUS_STRINGS = {
64 FINISHED: 'Finished', FAILED: 'Failed',
65 ABORTED: 'Aborted', QUEUED: 'Queued',
66 RUNNING: 'Running'
67 }
68
69 _parameters = {}
70
71 def __init__(self, **kwargs):
72 self.status = Procedure.QUEUED
73 self._update_parameters()
74 self._update_metadata()
75 for key in kwargs:
76 if key in self._parameters.keys():
77 setattr(self, key, kwargs[key])
78 log.info(f'Setting parameter {key} to {kwargs[key]}')
79 self.gen_measurement()
80
81 @staticmethod
82 def parse_columns(columns):
83 """Get columns with any units in parentheses.
84 For each column, if there are matching parentheses containing text
85 with no spaces, parse the value between the parentheses as a Pint unit. For example,
86 "Source Voltage (V)" will be parsed and matched to :code:`Unit('volt')`.
87 Raises an error if a parsed value is undefined in Pint unit registry.
88 Return a dictionary of matched columns with their units.
89
90 :param columns: List of columns to be parsed.
91 :type record: dict
92 :return: Dictionary of columns with Pint units.
93 """
94 units_pattern = r"\((?P<units>[\w/\(\)\*\t]+)\)"
95 units = {}
96 for column in columns:
97 match = re.search(units_pattern, column)
98 if match:
99 try:
100 units[column] = ureg.Quantity(match.groupdict()['units']).units
101 except UndefinedUnitError:
102 raise ValueError(
103 f"Column \"{column}\" with unit \"{match.groupdict()['units']}\""
104 " is not defined in Pint registry. Check procedure "
105 "DATA_COLUMNS contains valid Pint units.")
106 return units
107
108 def gen_measurement(self):
109 """Create MEASURE and DATA_COLUMNS variables for get_datapoint method."""
110 # TODO: Refactor measurable-s implementation to be consistent with parameters
111
112 self.MEASURE = {}
113 for item, parameter in inspect.getmembers(self.__class__):
114 if isinstance(parameter, Measurable):
115 if parameter.measure:
116 self.MEASURE.update({parameter.name: item})
117
118 if not self.DATA_COLUMNS:
119 self.DATA_COLUMNS = Measurable.DATA_COLUMNS
120
121 # Validate DATA_COLUMNS fit pymeasure column header format
122 self.parse_columns(self.DATA_COLUMNS)
123
124 def get_datapoint(self):
125 data = {key: getattr(self, self.MEASURE[key]).value for key in self.MEASURE}
126 return data
127
128 def measure(self):
129 data = self.get_datapoint()
130 log.debug("Produced numbers: %s" % data)
131 self.emit('results', data)
132
133 def _update_parameters(self):
134 """ Collects all the Parameter objects for the procedure and stores
135 them in a meta dictionary so that the actual values can be set in
136 their stead
137 """
138 if not self._parameters:
139 self._parameters = {}
140 for item, parameter in inspect.getmembers(self.__class__):
141 if isinstance(parameter, Parameter):
142 self._parameters[item] = deepcopy(parameter)
143 if parameter.is_set():
144 setattr(self, item, parameter.value)
145 else:
146 setattr(self, item, None)
147
148 def parameters_are_set(self):
149 """ Returns True if all parameters are set """
150 for name, parameter in self._parameters.items():
151 if getattr(self, name) is None:
152 return False
153 return True
154
155 def check_parameters(self):
156 """ Raises an exception if any parameter is missing before calling
157 the associated function. Ensures that each value can be set and
158 got, which should cast it into the right format. Used as a decorator
159 @check_parameters on the startup method
160 """
161 for name, parameter in self._parameters.items():
162 value = getattr(self, name)
163 if value is None:
164 raise NameError("Missing {} '{}' in {}".format(
165 parameter.__class__, name, self.__class__))
166
167 def parameter_values(self):
168 """ Returns a dictionary of all the Parameter values and grabs any
169 current values that are not in the default definitions
170 """
171 result = {}
172 for name, parameter in self._parameters.items():
173 value = getattr(self, name)
174 if value is not None:
175 parameter.value = value
176 setattr(self, name, parameter.value)
177 result[name] = parameter.value
178 else:
179 result[name] = None
180 return result
181
182 def parameter_objects(self):
183 """ Returns a dictionary of all the Parameter objects and grabs any
184 current values that are not in the default definitions
185 """
186 result = {}
187 for name, parameter in self._parameters.items():
188 value = getattr(self, name)
189 if value is not None:
190 parameter.value = value
191 setattr(self, name, parameter.value)
192 result[name] = parameter
193 return result
194
195 def refresh_parameters(self):
196 """ Enforces that all the parameters are re-cast and updated in the meta
197 dictionary
198 """
199 for name, parameter in self._parameters.items():
200 value = getattr(self, name)
201 parameter.value = value
202 setattr(self, name, parameter.value)
203
204 def set_parameters(self, parameters, except_missing=True):
205 """ Sets a dictionary of parameters and raises an exception if additional
206 parameters are present if except_missing is True
207 """
208 for name, value in parameters.items():
209 if name in self._parameters:
210 self._parameters[name].value = value
211 setattr(self, name, self._parameters[name].value)
212 else:
213 if except_missing:
214 raise NameError("Parameter '{}' does not belong to '{}'".format(
215 name, repr(self)))
216
217 def _update_metadata(self):
218 """ Collects all the Metadata objects for the procedure and stores
219 them in a meta dictionary so that the actual values can be set and used
220 in their stead
221 """
222 self._metadata = {}
223
224 for item, metadata in inspect.getmembers(self.__class__):
225 if isinstance(metadata, Metadata):
226 self._metadata[item] = deepcopy(metadata)
227
228 if metadata.is_set():
229 setattr(self, item, metadata.value)
230 else:
231 setattr(self, item, None)
232
233 def evaluate_metadata(self):
234 """ Evaluates all Metadata objects, fixing their values to the current value
235 """
236 for item, metadata in self._metadata.items():
237 # Evaluate the metadata, fixing its value
238 value = metadata.evaluate(parent=self, new_value=getattr(self, item))
239
240 # Make the value of the metadata easily accessible
241 setattr(self, item, value)
242
243 def metadata_objects(self):
244 """ Returns a dictionary of all the Metadata objects
245 """
246 return self._metadata
247
248 def placeholder_objects(self):
249 """ Collect all eligible placeholders (parameters & metadata) with their value in a dict.
250 """
251 return {**self.parameter_objects(), **self.metadata_objects()}
252
253 @classmethod
254 def placeholder_names(cls):
255 """ Collect the names of all eligible placeholders (parameters & metadata)"""
256 placeholders = []
257 for _, item in inspect.getmembers(cls):
258 if isinstance(item, Metadata) or isinstance(item, Parameter):
259 placeholders.append(item.name)
260
261 return list(set(placeholders))
262
263 def startup(self):
264 """ Executes the commands needed at the start-up of the measurement
265 """
266 pass
267
268 def execute(self):
269 """ Preforms the commands needed for the measurement itself. During
270 execution the shutdown method will always be run following this method.
271 This includes when Exceptions are raised.
272 """
273 pass
274
275 def shutdown(self):
276 """ Executes the commands necessary to shut down the instruments
277 and leave them in a safe state. This method is always run at the end.
278 """
279 pass
280
281 def emit(self, topic, record):
282 raise NotImplementedError('should be monkey patched by a worker')
283
284 def should_stop(self):
285 raise NotImplementedError('should be monkey patched by a worker')
286
287 def get_estimates(self):
288 """ Function that returns estimates that are to be displayed by
289 the EstimatorWidget. Must be reimplemented by subclasses. Should
290 return an int or float representing the duration in seconds, or
291 a list with a tuple for each estimate. The tuple should consists
292 of two strings: the first will be used as the label of the
293 estimate, the second as the displayed estimate.
294 """
295 raise NotImplementedError('Must be reimplemented by subclasses')
296
297 def __str__(self):
298 result = repr(self) + "\n"
299 for parameter in self._parameters.items():
300 result += str(parameter)
301 return result
302
303 def __repr__(self):
304 return "<{}(status={},parameters_are_set={})>".format(
305 self.__class__.__name__, self.STATUS_STRINGS[self.status],
306 self.parameters_are_set()
307 )
308
309
310 class UnknownProcedure(Procedure):
311 """ Handles the case when a :class:`.Procedure` object can not be imported
312 during loading in the :class:`.Results` class
313 """
314
315 def __init__(self, parameters):
316 super().__init__()
317 self._parameters = parameters
318
319 def startup(self):
320 raise NotImplementedError("UnknownProcedure can not be run")
321
322
323 class ProcedureWrapper:
324
325 def __init__(self, procedure):
326 self.procedure = procedure
327
328 def __getstate__(self):
329 # Get all information needed to reconstruct procedure
330 self._parameters = self.procedure.parameter_values()
331 self._class = self.procedure.__class__.__name__
332 module = sys.modules[self.procedure.__module__]
333 self._package = module.__package__
334 self._module = module.__name__
335 self._file = module.__file__
336
337 state = self.__dict__.copy()
338 del state['procedure']
339 return state
340
341 def __setstate__(self, state):
342 self.__dict__.update(state)
343
344 # Restore the procedure
345 module = SourceFileLoader(self._module, self._file).load_module()
346 cls = getattr(module, self._class)
347
348 self.procedure = cls()
349 self.procedure.set_parameters(self._parameters)
350 self.procedure.refresh_parameters()
351
352 del self._parameters
353 del self._class
354 del self._package
355 del self._module
356 del self._file