Debian Codegraph @

pymeasure/experiment/sequencer.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 re
27 from itertools import product
28
29 import numpy as np
30
31 log = logging.getLogger(__name__)
32 log.addHandler(logging.NullHandler())
33
34
35 class SequenceEvaluationError(Exception):
36 """Raised when the evaluation of a sequence string goes wrong."""
37 pass
38
39
40 class SequenceItem(object):
41 """ Class representing a sequence row """
42 column_map = {
43 0: "level",
44 1: "parameter",
45 2: "expression",
46 }
47
48 def __init__(self, level, parameter, expression, parent):
49 self.level = level
50 self.parameter = parameter
51 self.expression = expression
52 self.parent = parent
53
54 def __getitem__(self, idx):
55 if idx in self.column_map:
56 return getattr(self, self.column_map[idx])
57 else:
58 return super().__getitem__(idx)
59
60 def __setitem__(self, idx, value):
61 if idx in self.column_map:
62 return setattr(self, self.column_map[idx], value)
63 else:
64 return super().__setitem__(idx, value)
65
66 def __str__(self):
67 return "{} \"{}\", \"{}\"".format("-" * (self.level + 1), self.parameter, self.expression)
68
69
70 class SequenceHandler:
71 """ It represents a sequence, that is a tree of parameter sweep.
72
73 A sequence can be loaded from a file or created programmatically with :meth:`~.add_node`
74 and :meth:`~.remove_node`
75
76 The internal representation is a nodes tree with each node composed of 3 elements:
77
78 - Level: that is the distance from the root node
79 - Parameter: A string that is the parameter name
80 - Expression: A python expression which describes the list of values to be assumed
81 by the Parameter.
82
83 The syntax of the file is as follow: ::
84
85 - "Parameter1", "(1,2,3)"
86 -- "Parameter2", "(4,5,6)"
87 --- "Parameter3", "(6,7,8)"
88 - "Parameter4", "range(1,3)"
89
90 In this case, the tree is composed of a root node with two children (Parameter1 and Parameter4)
91 Parameter2 is the only child of Parameter1 and Parameter3 is the only child of Parameter2.
92 Parameter4 has no child.
93
94 Data is stored internally as a list where each
95 item matches a row of the sequence file.
96
97 Data can also be saved back to the file object provided.
98 """
99
100 MAXDEPTH = 10
101 SAFE_FUNCTIONS = {
102 'range': range,
103 'sorted': sorted,
104 'list': list,
105 'arange': np.arange,
106 'linspace': np.linspace,
107 'arccos': np.arccos,
108 'arcsin': np.arcsin,
109 'arctan': np.arctan,
110 'arctan2': np.arctan2,
111 'ceil': np.ceil,
112 'cos': np.cos,
113 'cosh': np.cosh,
114 'degrees': np.degrees,
115 'e': np.e,
116 'exp': np.exp,
117 'fabs': np.fabs,
118 'floor': np.floor,
119 'fmod': np.fmod,
120 'frexp': np.frexp,
121 'hypot': np.hypot,
122 'ldexp': np.ldexp,
123 'log': np.log,
124 'log10': np.log10,
125 'modf': np.modf,
126 'pi': np.pi,
127 'power': np.power,
128 'radians': np.radians,
129 'sin': np.sin,
130 'sinh': np.sinh,
131 'sqrt': np.sqrt,
132 'tan': np.tan,
133 'tanh': np.tanh,
134 }
135
136 def __init__(self, valid_inputs=(), file_obj=None):
137 self._sequences = []
138 self.valid_inputs = valid_inputs
139 if file_obj:
140 self.load(file_obj)
141
142 @staticmethod
143 def eval_string(string, name=None, depth=None, log_enabled=True):
144 """
145 Evaluate the given string. The string is evaluated using a list of
146 pre-defined functions that are deemed safe to use, to prevent the
147 execution of malicious code. For this purpose, also any built-in
148 functions or global variables are not available.
149
150 :param string: String to be interpreted.
151 :param name: Name of the to-be-interpreted string, only used for
152 error messages.
153 :param depth: Depth of the to-be-interpreted string, only used
154 for error messages.
155 :param log_enabled: Enable log messages.
156 """
157
158 evaluated_string = None
159 if len(string) > 0:
160 try:
161 evaluated_string = eval(
162 string, {"__builtins__": None}, SequenceHandler.SAFE_FUNCTIONS
163 )
164 except TypeError:
165 if log_enabled:
166 log.error("TypeError, likely a typo in one of the " +
167 "functions for parameter '{}', depth {}".format(
168 name, depth
169 ))
170 raise SequenceEvaluationError("TypeError, likely a typo")
171 except SyntaxError:
172 if log_enabled:
173 log.error("SyntaxError, likely unbalanced brackets " +
174 "for parameter '{}', depth {}".format(name, depth))
175 raise SequenceEvaluationError("SyntaxError, likely unbalanced brackets")
176 except ValueError:
177 if log_enabled:
178 log.error("ValueError, likely wrong function argument " +
179 "for parameter '{}', depth {}".format(name, depth))
180 raise SequenceEvaluationError("ValueError, likely wrong function argument")
181 except Exception as e:
182 raise SequenceEvaluationError(e)
183 else:
184 if log_enabled:
185 log.error("No sequence entered for " +
186 "for parameter '{}', depth {}".format(name, depth))
187 raise SequenceEvaluationError("No sequence entered")
188
189 evaluated_string = np.array(evaluated_string)
190 return evaluated_string
191
192 def _get_idx(self, seq_item):
193 """ Return the index and level of the list whose value correspond to sequence """
194 try:
195 idx = self._sequences.index(seq_item)
196 except ValueError:
197 idx = -1 # Sequence not found, assuming idenx does not exist
198
199 if idx < 0:
200 level = -1
201 else:
202 level = self._sequences[idx].level
203
204 return idx, level
205
206 def add_node(self, name, parent_seq_item=None):
207 """ Add a node under the parent identified by parent_seq_item """
208 parent_idx, level = self._get_idx(parent_seq_item)
209
210 seq_item = SequenceItem(level + 1,
211 name,
212 "",
213 parent_seq_item)
214 # Find position where to insert new row
215 idx = parent_idx + 1
216 while idx < len(self._sequences):
217 if self._sequences[idx].level <= level:
218 break
219 idx += 1
220
221 self._sequences.insert(idx, seq_item)
222 return seq_item, self.get_children_order(seq_item)
223
224 def remove_node(self, seq_item):
225 """ Remove node identified by seq_item """
226 # if node identified by idx has children, we need to remove them first
227 for child_seq_item in self.children(seq_item):
228 self.remove_node(child_seq_item)
229
230 self._sequences.remove(seq_item)
231
232 return seq_item.parent, self.get_children_order(seq_item.parent)
233
234 def children(self, seq_item):
235 """ return a list of children of node identified by seq_item """
236 idx, current_level = self._get_idx(seq_item)
237 child_list = []
238 idx += 1
239 while idx < len(self._sequences):
240 if self._sequences[idx].level == (current_level + 1):
241 child_list.append(self._sequences[idx])
242 if self._sequences[idx].level <= current_level:
243 break
244 idx += 1
245 return child_list
246
247 def get_children(self, seq_item, index):
248 """ Return the children of order index of the node seq_item """
249
250 child_list = self.children(seq_item)
251
252 if index >= len(child_list):
253 child = None
254 else:
255 child = child_list[index]
256 return child
257
258 def get_children_order(self, seq_item):
259 """ Return the children order of the node identified by seq_item
260
261 The children order is the index related to the parent's children list.
262
263 :param seq_item: SequenceItem instance or None
264 """
265
266 if seq_item is None:
267 return -1
268
269 # Get parent's children list
270 children_list = self.children(seq_item.parent)
271
272 return children_list.index(seq_item)
273
274 def get_parent(self, seq_item):
275 """ Return parent of node identified by seq_item """
276
277 return seq_item.parent, self.get_children_order(seq_item.parent)
278
279 def set_data(self, seq_item, row, column, value):
280 """ Set data for node identified by seq_item """
281
282 idx, _ = self._get_idx(seq_item)
283
284 if idx < 0:
285 return False
286
287 self._sequences[idx][column] = value
288 return True
289
290 def load(self, file_obj, append=False):
291 """
292 Read and parse a sequence stored in a file.
293
294 :params file_obj: file object
295 :params append: flag to control whether to append to or replace current sequence
296
297 """
298
299 _sequences = []
300 if append:
301 _sequences += self._sequences
302 current_parent = None
303
304 pattern = re.compile("([-]+) \"(.*?)\", \"(.*?)\"")
305 file_obj.seek(0)
306 for line in file_obj:
307 line = line.strip()
308 match = pattern.search(line)
309
310 if not match:
311 continue
312
313 level = len(match.group(1)) - 1
314
315 if level < 0:
316 continue
317
318 parameter = match.group(2)
319 sequence = match.group(3)
320 parent_level = -1 if current_parent is None else current_parent.level
321 if level == (parent_level + 1):
322 pass
323 elif (level <= parent_level):
324 # Find parent
325 current_parent = current_parent.parent
326 while current_parent is not None:
327 if level == (current_parent.level + 1):
328 break
329 current_parent = current_parent.parent
330 else:
331 raise SequenceEvaluationError("Invalid file format: level missing ?")
332
333 if self.valid_inputs and parameter not in self.valid_inputs:
334 error_message = f'Unexpected parameter name "{parameter:s}", ' + \
335 f'valid parameters name are {self.valid_inputs}'
336 raise SequenceEvaluationError(error_message)
337
338 data = SequenceItem(level,
339 parameter,
340 sequence,
341 current_parent)
342 current_parent = data
343 _sequences.append(data)
344 # No errors, update internal data
345 self._sequences = _sequences
346
347 def save(self, file_obj):
348 """ Save modified sequence to file stream
349
350 :param file_obj: file object
351 """
352
353 file_obj.write("\n".join(str(item) for item in self._sequences))
354
355 def parameters_sequence(self, names_map=None):
356 """
357 Generate a list of parameters from the sequence tree.
358
359 :param names_map: an optional dict to map parameter name
360 :return: A list of dictionaries. Each dictionary represents a parameters setting
361 for running an experiment.
362 """
363
364 sequences = []
365 current_sequence = [[] for i in range(self.MAXDEPTH)]
366 temp_sequence = [[] for i in range(self.MAXDEPTH)]
367
368 idx = 0
369 while (idx < len(self._sequences)):
370 depth, parameter, seq = self._sequences[idx].level, \
371 self._sequences[idx].parameter, \
372 self._sequences[idx].expression
373 values = self.eval_string(seq, parameter, depth)
374 if names_map is not None:
375 parameter = names_map[parameter]
376
377 try:
378 sequence_entry = [{parameter: value} for value in values]
379 except TypeError:
380 log.error(
381 "TypeError, likely no sequence for one of the parameters"
382 )
383 else:
384 current_sequence[depth].extend(sequence_entry)
385
386 idx += 1
387 next_depth = -1 if idx >= len(self._sequences) else self._sequences[idx].level
388
389 for depth_idx in range(depth, next_depth, -1):
390 temp_sequence[depth_idx].extend(current_sequence[depth_idx])
391
392 if depth_idx != 0:
393 sequence_products = list(product(
394 current_sequence[depth_idx - 1],
395 temp_sequence[depth_idx]
396 ))
397
398 for i in range(len(sequence_products)):
399 try:
400 element = sequence_products[i][1]
401 except IndexError:
402 log.error(
403 "IndexError, likely empty nested parameter"
404 )
405 else:
406 if isinstance(element, tuple):
407 sequence_products[i] = (
408 sequence_products[i][0], *element)
409
410 temp_sequence[depth_idx - 1].extend(sequence_products)
411 temp_sequence[depth_idx] = []
412
413 current_sequence[depth_idx] = []
414 current_sequence[depth_idx - 1] = []
415
416 if depth == next_depth:
417 temp_sequence[depth].extend(current_sequence[depth])
418 current_sequence[depth] = []
419
420 sequences = temp_sequence[0]
421
422 for idx in range(len(sequences)):
423 if not isinstance(sequences[idx], tuple):
424 sequences[idx] = (sequences[idx],)
425 return sequences