| 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 |