thzdaq-api 0.0.6b3__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- thzdaq_api/__init__.py +1 -0
- thzdaq_api/analysis.py +62 -0
- thzdaq_api/approvals.py +87 -0
- thzdaq_api/assistant/agents.md +202 -0
- thzdaq_api/assistant/assistant.md +23 -0
- thzdaq_api/assistant/hints.md +15 -0
- thzdaq_api/atomic.py +79 -0
- thzdaq_api/catalog.py +131 -0
- thzdaq_api/console.py +70 -0
- thzdaq_api/custom.py +326 -0
- thzdaq_api/daemon.py +183 -0
- thzdaq_api/data.py +55 -0
- thzdaq_api/declare.py +193 -0
- thzdaq_api/declaring.py +125 -0
- thzdaq_api/devices.py +307 -0
- thzdaq_api/errors.py +47 -0
- thzdaq_api/events.py +224 -0
- thzdaq_api/examples/hot_cold.py +67 -0
- thzdaq_api/examples/hot_cold_grid.py +74 -0
- thzdaq_api/examples/iv_analysis.py +34 -0
- thzdaq_api/examples/map.py +42 -0
- thzdaq_api/examples/monitor.py +35 -0
- thzdaq_api/examples/raw_instrument.py +37 -0
- thzdaq_api/examples/sweep.py +38 -0
- thzdaq_api/examples.py +79 -0
- thzdaq_api/guides.py +61 -0
- thzdaq_api/host.py +494 -0
- thzdaq_api/interpreters.py +422 -0
- thzdaq_api/kernel.py +137 -0
- thzdaq_api/lab.py +562 -0
- thzdaq_api/lanes.py +170 -0
- thzdaq_api/leases.py +29 -0
- thzdaq_api/lock.py +65 -0
- thzdaq_api/measurement_file.py +459 -0
- thzdaq_api/measurements.py +433 -0
- thzdaq_api/operation.py +52 -0
- thzdaq_api/origins.py +86 -0
- thzdaq_api/present.py +376 -0
- thzdaq_api/procedures.py +124 -0
- thzdaq_api/raw.py +272 -0
- thzdaq_api/remote.py +267 -0
- thzdaq_api/rights.py +81 -0
- thzdaq_api/script.py +382 -0
- thzdaq_api/scripts.py +133 -0
- thzdaq_api/sessions.py +176 -0
- thzdaq_api/station.py +192 -0
- thzdaq_api/terminal.py +66 -0
- thzdaq_api/tools.py +275 -0
- thzdaq_api/transport.py +93 -0
- thzdaq_api/ui.py +152 -0
- thzdaq_api/windows.py +192 -0
- thzdaq_api/wire.py +35 -0
- thzdaq_api/workspace.py +239 -0
- thzdaq_api-0.0.6b3.dist-info/METADATA +30 -0
- thzdaq_api-0.0.6b3.dist-info/RECORD +57 -0
- thzdaq_api-0.0.6b3.dist-info/WHEEL +4 -0
- thzdaq_api-0.0.6b3.dist-info/licenses/LICENSE +21 -0
thzdaq_api/script.py
ADDED
|
@@ -0,0 +1,382 @@
|
|
|
1
|
+
"""A script's own measurement as the script writes it: the daemon keeps a
|
|
2
|
+
session (thzdaq_api.sessions), a measurement with its file, number and events,
|
|
3
|
+
and the script fills it.
|
|
4
|
+
|
|
5
|
+
with lab.measurement("pv_fine", devices=[bias, pm], exclusive=[bias]) as m:
|
|
6
|
+
m.plot("scan", x="voltage", y="power") # a live plot where it is followed
|
|
7
|
+
m.show() # in a window of its own (or "gui")
|
|
8
|
+
m.restore(bias, "voltage_set") # set back however it ends
|
|
9
|
+
for v in m.sweep("2:3:51", unit="mV"): # each step looks for a cancel
|
|
10
|
+
bias.voltage_set = v
|
|
11
|
+
m.record("scan", voltage=v, power=pm.power)
|
|
12
|
+
m.progress()
|
|
13
|
+
|
|
14
|
+
The daemon does what restore and on_exit name when the session ends, however
|
|
15
|
+
it ends: at the end of the with block; at a cancel (thzdaq cancel <id>, Stop
|
|
16
|
+
in a window), where m.sweep, m.sleep and m.check_cancel raise Cancelled and the
|
|
17
|
+
with block ends the session cancelled and goes on after it; at Ctrl+C
|
|
18
|
+
(interrupted); or when the script dies and falls silent (interrupted too).
|
|
19
|
+
|
|
20
|
+
While the with block runs, a thread tells the daemon the script is alive and
|
|
21
|
+
hears a cancel at once (keep_session).
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
import hashlib
|
|
25
|
+
import queue
|
|
26
|
+
import sys
|
|
27
|
+
import threading
|
|
28
|
+
import traceback
|
|
29
|
+
from pathlib import Path
|
|
30
|
+
from typing import (
|
|
31
|
+
Any,
|
|
32
|
+
Callable,
|
|
33
|
+
Dict,
|
|
34
|
+
Iterable,
|
|
35
|
+
Iterator,
|
|
36
|
+
Optional,
|
|
37
|
+
Set,
|
|
38
|
+
TypeVar,
|
|
39
|
+
Union,
|
|
40
|
+
)
|
|
41
|
+
|
|
42
|
+
from thzdaq_api.approvals import AnswerApproval, Approval
|
|
43
|
+
from thzdaq_api.data import Measured, encode_values
|
|
44
|
+
from thzdaq_api.errors import ErrorCode, LabError
|
|
45
|
+
from thzdaq_api.events import ApprovalAnswered, ApprovalRequested
|
|
46
|
+
from thzdaq_api.measurement_file import (
|
|
47
|
+
CANCELLED,
|
|
48
|
+
COMPLETED,
|
|
49
|
+
FAILED,
|
|
50
|
+
INTERRUPTED,
|
|
51
|
+
RUNNING,
|
|
52
|
+
Column,
|
|
53
|
+
column_for,
|
|
54
|
+
)
|
|
55
|
+
from thzdaq_api.measurements import PlotInfo, RunInfo
|
|
56
|
+
from thzdaq_api.origins import PLOTS
|
|
57
|
+
from thzdaq_api.sessions import (
|
|
58
|
+
KEEP_S,
|
|
59
|
+
AdvanceSession,
|
|
60
|
+
CallOnExit,
|
|
61
|
+
EndSession,
|
|
62
|
+
KeepSession,
|
|
63
|
+
LogSession,
|
|
64
|
+
ParseSweep,
|
|
65
|
+
PlotSession,
|
|
66
|
+
RecordSession,
|
|
67
|
+
RestoreOnExit,
|
|
68
|
+
ScriptSource,
|
|
69
|
+
SessionState,
|
|
70
|
+
StartSession,
|
|
71
|
+
Swept,
|
|
72
|
+
)
|
|
73
|
+
from thzdaq_api.terminal import ALLOW, line, yes
|
|
74
|
+
|
|
75
|
+
# A device as a session names it: its ref, or the bench's object (lab["ref"])
|
|
76
|
+
Device = Union[str, Any]
|
|
77
|
+
# A column described by a script: (title, unit), or a Column
|
|
78
|
+
Described = Union[Column, tuple]
|
|
79
|
+
Typed = Callable[[str, threading.Event], Optional[str]] # a person's line, or None
|
|
80
|
+
# Where a measurement is shown: a window of its plots (plots, True), the main
|
|
81
|
+
# window (gui); False: nowhere
|
|
82
|
+
Where = Union[bool, str]
|
|
83
|
+
Show = Callable[[int, str], None] # the bench's: a measurement in a window
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def place(where: Where) -> str:
|
|
87
|
+
"""Where a measurement is shown, by the name of its window."""
|
|
88
|
+
return PLOTS if where is True else str(where)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
R = TypeVar("R")
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
class Cancelled(Exception):
|
|
95
|
+
"""The measurement was asked to stop: its session ends cancelled."""
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def ref_of(device: Device) -> str:
|
|
99
|
+
return device if isinstance(device, str) else device.ref
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def described(key: str, given: Described) -> Column:
|
|
103
|
+
return given if isinstance(given, Column) else Column(key, *given)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def script_source(
|
|
107
|
+
path: Optional[str], workspace: Optional[Path]
|
|
108
|
+
) -> Optional[ScriptSource]:
|
|
109
|
+
"""The script a process runs, kept with its measurements: its path (within
|
|
110
|
+
the workspace when it is in one), hash and text; None without a file (a
|
|
111
|
+
notebook, the interpreter's prompt)."""
|
|
112
|
+
if path is None:
|
|
113
|
+
return None
|
|
114
|
+
file = Path(path).resolve()
|
|
115
|
+
data = file.read_bytes()
|
|
116
|
+
inside = workspace is not None and file.is_relative_to(workspace)
|
|
117
|
+
shown = file.relative_to(workspace) if inside else file
|
|
118
|
+
text = data.decode("utf-8", errors="replace")
|
|
119
|
+
return ScriptSource(shown.as_posix(), hashlib.sha256(data).hexdigest(), text)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def ending(kind, error, trace) -> tuple:
|
|
123
|
+
"""How a with block ended, as its session ends: status, error, traceback."""
|
|
124
|
+
if kind is None:
|
|
125
|
+
return COMPLETED, None, ""
|
|
126
|
+
if issubclass(kind, Cancelled):
|
|
127
|
+
return CANCELLED, None, ""
|
|
128
|
+
if issubclass(kind, KeyboardInterrupt):
|
|
129
|
+
return INTERRUPTED, "stopped by Ctrl+C", ""
|
|
130
|
+
told = "".join(traceback.format_exception(kind, error, trace))
|
|
131
|
+
return FAILED, f"{kind.__name__}: {error}", told
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
class Session:
|
|
135
|
+
"""A script's measurement while its with block runs (lab.measurement)."""
|
|
136
|
+
|
|
137
|
+
def __init__(
|
|
138
|
+
self,
|
|
139
|
+
lab,
|
|
140
|
+
start: StartSession,
|
|
141
|
+
approve: Callable[[Callable[[], RunInfo]], RunInfo],
|
|
142
|
+
entered: Callable[[Optional["Session"]], None],
|
|
143
|
+
show: Show,
|
|
144
|
+
):
|
|
145
|
+
"""lab: the bench's Lab; approve(call): the start as a person allows
|
|
146
|
+
it; entered(session): the bench's calls belong to it (None: no more);
|
|
147
|
+
show(id, where): the bench's window of a measurement."""
|
|
148
|
+
self.lab = lab
|
|
149
|
+
self._start = start
|
|
150
|
+
self._approve = approve
|
|
151
|
+
self._entered = entered
|
|
152
|
+
self._show = show
|
|
153
|
+
self._shown: Set[str] = set() # where it is on screen already
|
|
154
|
+
self.run: Optional[RunInfo] = None # as it started; as it ended, after
|
|
155
|
+
self.id = 0
|
|
156
|
+
self._columns: Dict[str, Column] = {c.key: c for c in start.columns}
|
|
157
|
+
self._sent: Dict[str, Column] = dict(self._columns)
|
|
158
|
+
self._cancel = threading.Event()
|
|
159
|
+
self._stopped = threading.Event()
|
|
160
|
+
self._status = RUNNING
|
|
161
|
+
self._keeper = threading.Thread(target=self._keep, daemon=True)
|
|
162
|
+
|
|
163
|
+
def __enter__(self) -> "Session":
|
|
164
|
+
self.run = self._approve(lambda: self.lab.call(self._start))
|
|
165
|
+
self.id = self.run.id
|
|
166
|
+
self._keeper.name = f"keep session #{self.id}"
|
|
167
|
+
self._keeper.start()
|
|
168
|
+
self._entered(self)
|
|
169
|
+
return self
|
|
170
|
+
|
|
171
|
+
def __exit__(self, kind, error, trace) -> bool:
|
|
172
|
+
self._entered(None)
|
|
173
|
+
self._stopped.set()
|
|
174
|
+
status, message, told = ending(kind, error, trace)
|
|
175
|
+
try:
|
|
176
|
+
self.run = self.lab.call(EndSession(self.id, status, message, told))
|
|
177
|
+
finally:
|
|
178
|
+
self._keeper.join()
|
|
179
|
+
return kind is not None and issubclass(kind, Cancelled)
|
|
180
|
+
|
|
181
|
+
def _keep(self) -> None:
|
|
182
|
+
while not self._stopped.is_set() and self._status == RUNNING:
|
|
183
|
+
try:
|
|
184
|
+
self._heard(self.lab.call(KeepSession(id=self.id, wait=KEEP_S)))
|
|
185
|
+
except LabError:
|
|
186
|
+
self._cancel.set() # the daemon is gone: stop at the next check
|
|
187
|
+
return
|
|
188
|
+
|
|
189
|
+
def _heard(self, state: SessionState) -> None:
|
|
190
|
+
self._status = state.status
|
|
191
|
+
if state.cancelled or state.status != RUNNING:
|
|
192
|
+
self._cancel.set()
|
|
193
|
+
|
|
194
|
+
# Cancel
|
|
195
|
+
@property
|
|
196
|
+
def cancelled(self) -> bool:
|
|
197
|
+
"""It was asked to stop (or the daemon ended it)."""
|
|
198
|
+
return self._cancel.is_set()
|
|
199
|
+
|
|
200
|
+
def check_cancel(self) -> None:
|
|
201
|
+
if self._cancel.is_set():
|
|
202
|
+
raise Cancelled(f"measurement #{self.id} was asked to stop")
|
|
203
|
+
|
|
204
|
+
def sleep(self, seconds: float) -> None:
|
|
205
|
+
"""Sleep that ends at once with Cancelled when a cancel comes."""
|
|
206
|
+
self._cancel.wait(max(0.0, seconds))
|
|
207
|
+
self.check_cancel()
|
|
208
|
+
|
|
209
|
+
def sweep(
|
|
210
|
+
self, values: Union[str, Swept, Iterable[float]], unit: str = ""
|
|
211
|
+
) -> Iterator[Measured]:
|
|
212
|
+
"""The values of a sweep, typed as people type it ("2:3:51" with unit
|
|
213
|
+
"mV"), declared (value(...) of a sweep) or given (SI); each in SI
|
|
214
|
+
units with its unit, after a look for a cancel."""
|
|
215
|
+
if isinstance(values, Swept):
|
|
216
|
+
values, unit = values.typed(), values.unit
|
|
217
|
+
if isinstance(values, str):
|
|
218
|
+
parsed = self.lab.call(ParseSweep(text=values, unit=unit))
|
|
219
|
+
values, unit = parsed.values, parsed.unit
|
|
220
|
+
for value in values:
|
|
221
|
+
self.check_cancel()
|
|
222
|
+
yield Measured(value, unit)
|
|
223
|
+
|
|
224
|
+
# Data
|
|
225
|
+
def columns(self, **given: Described) -> None:
|
|
226
|
+
"""Titles and units of record keys, (title, unit) or a Column: over what
|
|
227
|
+
a value knows of itself (a device's reading), and for computed values."""
|
|
228
|
+
for key, column in given.items():
|
|
229
|
+
self._columns[key] = described(key, column)
|
|
230
|
+
|
|
231
|
+
def record(self, table: str, /, **values: Any) -> None:
|
|
232
|
+
"""A record of a table: each key a column, values in SI units (a
|
|
233
|
+
reading, a swept value or a number of the script's)."""
|
|
234
|
+
fresh = []
|
|
235
|
+
for key, value in values.items():
|
|
236
|
+
column = self._column(key, value)
|
|
237
|
+
if column is not None and self._sent.get(key) != column:
|
|
238
|
+
fresh.append(column)
|
|
239
|
+
self._sent[key] = column
|
|
240
|
+
row = encode_values(values)
|
|
241
|
+
self._heard(
|
|
242
|
+
self.lab.call(
|
|
243
|
+
RecordSession(
|
|
244
|
+
id=self.id, table=table, rows=(row,), columns=tuple(fresh)
|
|
245
|
+
)
|
|
246
|
+
)
|
|
247
|
+
)
|
|
248
|
+
|
|
249
|
+
def _column(self, key: str, value: Any) -> Optional[Column]:
|
|
250
|
+
if key in self._columns:
|
|
251
|
+
return self._columns[key]
|
|
252
|
+
if isinstance(value, Measured):
|
|
253
|
+
title = value.title or column_for(key).title
|
|
254
|
+
return Column(key, title, value.unit, value.source)
|
|
255
|
+
return None
|
|
256
|
+
|
|
257
|
+
def progress(self, done: Optional[int] = None, total: Optional[int] = None) -> None:
|
|
258
|
+
"""Steps done (one more when not given) of total."""
|
|
259
|
+
self._heard(self.lab.call(AdvanceSession(id=self.id, done=done, total=total)))
|
|
260
|
+
|
|
261
|
+
def log(self, message: str) -> None:
|
|
262
|
+
self.lab.call(LogSession(id=self.id, message=message))
|
|
263
|
+
|
|
264
|
+
def plot(
|
|
265
|
+
self,
|
|
266
|
+
table: str,
|
|
267
|
+
x: str,
|
|
268
|
+
y: str,
|
|
269
|
+
group_by: Iterable[str] = (),
|
|
270
|
+
title: str = "",
|
|
271
|
+
kind: str = "line",
|
|
272
|
+
z: Optional[str] = None,
|
|
273
|
+
show: Where = False,
|
|
274
|
+
into: Optional[str] = None,
|
|
275
|
+
) -> PlotInfo:
|
|
276
|
+
"""A live plot of a table where the measurement is followed, kept in
|
|
277
|
+
its file for Data to draw again; curves by the values of group_by.
|
|
278
|
+
into: a graph of the window (its title) it is drawn into, when there
|
|
279
|
+
is one of the same units; show: the measurement on screen at once
|
|
280
|
+
(see show)."""
|
|
281
|
+
plot = PlotInfo(
|
|
282
|
+
key="", title=title, table=table, x=x, y=y,
|
|
283
|
+
group_by=tuple(group_by), kind=kind, z=z, into=into,
|
|
284
|
+
) # fmt: skip
|
|
285
|
+
drawn = self.lab.call(PlotSession(id=self.id, plot=plot))
|
|
286
|
+
if show:
|
|
287
|
+
self.show(show)
|
|
288
|
+
return drawn
|
|
289
|
+
|
|
290
|
+
def show(self, where: Where = PLOTS) -> None:
|
|
291
|
+
"""Its plots on screen as it runs, once for each place: in a window
|
|
292
|
+
of their own (plots, True), or in the main window (gui), opened in
|
|
293
|
+
the script's workspace unless one is open already."""
|
|
294
|
+
shown = place(where)
|
|
295
|
+
if shown not in self._shown:
|
|
296
|
+
self._show(self.id, shown)
|
|
297
|
+
self._shown.add(shown)
|
|
298
|
+
|
|
299
|
+
# What the daemon does at the end
|
|
300
|
+
def restore(self, device: Device, key: str) -> Any:
|
|
301
|
+
"""Set the quantity back to its value now when the session ends,
|
|
302
|
+
however it ends; returns that value."""
|
|
303
|
+
kept = self.lab.call(RestoreOnExit(id=self.id, ref=ref_of(device), key=key))
|
|
304
|
+
return kept.value
|
|
305
|
+
|
|
306
|
+
def on_exit(self, device: Device, action: str, **arguments: Any) -> None:
|
|
307
|
+
"""Make the device do an action when the session ends (to_cold)."""
|
|
308
|
+
self.lab.call(
|
|
309
|
+
CallOnExit(
|
|
310
|
+
id=self.id, ref=ref_of(device), action=action, arguments=arguments
|
|
311
|
+
)
|
|
312
|
+
)
|
|
313
|
+
|
|
314
|
+
|
|
315
|
+
class AnsweredHere:
|
|
316
|
+
"""While a call waits for a person, the person at this terminal is asked
|
|
317
|
+
too; the first answer, here or in a window, counts."""
|
|
318
|
+
|
|
319
|
+
def __init__(self, person, origin: str, typed: Typed = line):
|
|
320
|
+
"""person: the bench as the person here answers in it (cli:answers);
|
|
321
|
+
origin: whose requests are asked here (the script's)."""
|
|
322
|
+
self.person = person
|
|
323
|
+
self.origin = origin
|
|
324
|
+
self.typed = typed
|
|
325
|
+
|
|
326
|
+
def __call__(self, call: Callable[[], R]) -> R:
|
|
327
|
+
asked: "queue.Queue[Optional[Approval]]" = queue.Queue()
|
|
328
|
+
gone: Dict[int, threading.Event] = {}
|
|
329
|
+
|
|
330
|
+
def heard(event) -> None:
|
|
331
|
+
body = event.body
|
|
332
|
+
if (
|
|
333
|
+
isinstance(body, ApprovalRequested)
|
|
334
|
+
and body.approval.origin == self.origin
|
|
335
|
+
):
|
|
336
|
+
gone.setdefault(body.approval.id, threading.Event())
|
|
337
|
+
asked.put(body.approval)
|
|
338
|
+
elif isinstance(body, ApprovalAnswered):
|
|
339
|
+
gone.setdefault(body.id, threading.Event()).set()
|
|
340
|
+
|
|
341
|
+
outcome: Dict[str, Any] = {}
|
|
342
|
+
|
|
343
|
+
def run() -> None:
|
|
344
|
+
try:
|
|
345
|
+
outcome["result"] = call()
|
|
346
|
+
except LabError as e: # handed to the thread that waits for it
|
|
347
|
+
outcome["error"] = e
|
|
348
|
+
finally:
|
|
349
|
+
for event in list(gone.values()):
|
|
350
|
+
event.set()
|
|
351
|
+
asked.put(None)
|
|
352
|
+
|
|
353
|
+
stop = self.person.subscribe(heard)
|
|
354
|
+
try:
|
|
355
|
+
threading.Thread(target=run, daemon=True).start()
|
|
356
|
+
for approval in iter(asked.get, None):
|
|
357
|
+
self._ask(approval, gone[approval.id])
|
|
358
|
+
finally:
|
|
359
|
+
stop()
|
|
360
|
+
if "error" in outcome:
|
|
361
|
+
raise outcome["error"]
|
|
362
|
+
return outcome["result"]
|
|
363
|
+
|
|
364
|
+
def _ask(self, approval: Approval, gone: threading.Event) -> None:
|
|
365
|
+
print(f"\n{approval.title}: {approval.text}", file=sys.stderr)
|
|
366
|
+
if approval.warning:
|
|
367
|
+
print(f"warning: {approval.warning}", file=sys.stderr)
|
|
368
|
+
typed = self.typed(ALLOW, gone)
|
|
369
|
+
if typed is None:
|
|
370
|
+
return # answered in a window
|
|
371
|
+
confirm = ""
|
|
372
|
+
allowed = yes(typed)
|
|
373
|
+
if allowed and approval.confirm:
|
|
374
|
+
confirm = self.typed(f"type {approval.confirm} to allow it: ", gone) or ""
|
|
375
|
+
try:
|
|
376
|
+
self.person.call(
|
|
377
|
+
AnswerApproval(id=approval.id, allowed=allowed, confirm=confirm)
|
|
378
|
+
)
|
|
379
|
+
except LabError as e:
|
|
380
|
+
if e.code != ErrorCode.NOT_FOUND:
|
|
381
|
+
raise
|
|
382
|
+
print("answered elsewhere first", file=sys.stderr)
|
thzdaq_api/scripts.py
ADDED
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
"""Scripts the daemon runs (thzdaq script start): a file run by an interpreter
|
|
2
|
+
apart from any terminal, so it outlives the one it was started from. Its
|
|
3
|
+
output goes to <workspace>/data/scripts/<id>.log; it finds the daemon that
|
|
4
|
+
started it by THZDAQ_SCRIPT_ID and THZDAQ_SIMULATE, works in its workspace
|
|
5
|
+
(THZDAQ_WORKSPACE) and calls the daemon as script:<name>@<id>.
|
|
6
|
+
|
|
7
|
+
A script has the rights of whoever started it (thzdaq_api.rights): a
|
|
8
|
+
person's changes the bench as the person would in a dock, an agent's asks as
|
|
9
|
+
the agent does. A person may allow their script in advance what it would
|
|
10
|
+
otherwise ask for (allow): set:<ref> its quantities, call:<ref> its actions
|
|
11
|
+
(a jump or a value beyond the warn range), run:<procedure> a procedure,
|
|
12
|
+
raw:<instrument> raw writes to an instrument (lab.raw), which no limit checks;
|
|
13
|
+
a session (lab.measurement) starts without asking when every device it names
|
|
14
|
+
is allowed. A dangerous step is never allowed in advance. share names devices
|
|
15
|
+
its measurements share while another one sweeps them. An agent's allow and
|
|
16
|
+
share allow nothing.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from typing import Optional, Tuple
|
|
20
|
+
|
|
21
|
+
import msgspec
|
|
22
|
+
|
|
23
|
+
from thzdaq_api.operation import Operation, Rights
|
|
24
|
+
from thzdaq_api.procedures import current_name
|
|
25
|
+
|
|
26
|
+
SCRIPTS = "scripts" # the folder of a workspace's data/ that holds their logs
|
|
27
|
+
SCRIPT_ID_ENV = "THZDAQ_SCRIPT_ID" # a script the daemon started: its number
|
|
28
|
+
SIMULATE_ENV = "THZDAQ_SIMULATE" # "1": the daemon that started it simulates
|
|
29
|
+
STOP_S = 5.0 # a stopped script has this long to end after its cancel
|
|
30
|
+
OUTPUT_ENV = {"PYTHONUNBUFFERED": "1", "PYTHONIOENCODING": "utf-8"}
|
|
31
|
+
|
|
32
|
+
# Statuses of a script
|
|
33
|
+
RUNNING = "running"
|
|
34
|
+
EXITED = "exited" # ended by itself (exit_code says how)
|
|
35
|
+
STOPPED = "stopped" # ended by stop_script
|
|
36
|
+
|
|
37
|
+
# What may be allowed in advance: <kind>:<target>
|
|
38
|
+
SET, CALL, RUN, RAW = "set", "call", "run", "raw"
|
|
39
|
+
KINDS = (SET, CALL, RUN, RAW)
|
|
40
|
+
SEPARATOR = ":"
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class Grant(msgspec.Struct, frozen=True):
|
|
44
|
+
"""Allowed in advance: set (quantities) or call (actions) of a device by
|
|
45
|
+
its ref, run a built-in procedure by its name, or raw writes to an
|
|
46
|
+
instrument by its id."""
|
|
47
|
+
|
|
48
|
+
kind: str
|
|
49
|
+
target: str
|
|
50
|
+
|
|
51
|
+
def __str__(self) -> str:
|
|
52
|
+
return f"{self.kind}{SEPARATOR}{self.target}"
|
|
53
|
+
|
|
54
|
+
@classmethod
|
|
55
|
+
def parse(cls, text: str) -> "Grant":
|
|
56
|
+
""" "set:sis_bias_1" -> Grant("set", "sis_bias_1"); a procedure by
|
|
57
|
+
the name it has now; ValueError otherwise."""
|
|
58
|
+
kind, separator, target = text.strip().partition(SEPARATOR)
|
|
59
|
+
if not separator or kind not in KINDS or not target:
|
|
60
|
+
raise ValueError(
|
|
61
|
+
f"{text!r}: allow {', '.join(f'{k}:…' for k in KINDS)}"
|
|
62
|
+
" (set:sis_bias_1, call:chopper_1, run:sis.current_vs_voltage,"
|
|
63
|
+
" raw:signal_generator_1)"
|
|
64
|
+
)
|
|
65
|
+
return cls(kind, current_name(target) if kind == RUN else target)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class ScriptInfo(msgspec.Struct, frozen=True):
|
|
69
|
+
"""A script the daemon runs or ran."""
|
|
70
|
+
|
|
71
|
+
id: int
|
|
72
|
+
name: str # its file's name without the suffix
|
|
73
|
+
path: str
|
|
74
|
+
command: Tuple[str, ...] # what was started
|
|
75
|
+
workspace: str # its working folder; its log is under data/scripts
|
|
76
|
+
log: str
|
|
77
|
+
origin: str # what it calls the daemon as: script:<name>@<id>
|
|
78
|
+
by: str # who started it
|
|
79
|
+
pid: Optional[int]
|
|
80
|
+
status: str # running, exited, stopped
|
|
81
|
+
started: str
|
|
82
|
+
ended: Optional[str] = None
|
|
83
|
+
exit_code: Optional[int] = None
|
|
84
|
+
allow: Tuple[Grant, ...] = ()
|
|
85
|
+
share: Tuple[str, ...] = ()
|
|
86
|
+
# The measurement it was started for: a run of the bench's own (custom.*)
|
|
87
|
+
measurement: Optional[int] = None
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
class ScriptLog(msgspec.Struct, frozen=True):
|
|
91
|
+
"""UTF-8 output with CRLF as LF; next is a byte offset in the original log,
|
|
92
|
+
not the encoded length of text. More follows while the script runs."""
|
|
93
|
+
|
|
94
|
+
text: str
|
|
95
|
+
next: int
|
|
96
|
+
running: bool
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
class StartScript(Operation[ScriptInfo]):
|
|
100
|
+
"""Run a Python script apart from any terminal: python is how a file is run
|
|
101
|
+
([python], or a build's [thzdaq-cli.exe, run-script]), arguments go after
|
|
102
|
+
the file, workspace is its working folder (its log under data/scripts).
|
|
103
|
+
allow: what it may do without asking (set:<ref>, call:<ref>,
|
|
104
|
+
run:<procedure>, raw:<instrument> raw writes; never a dangerous step);
|
|
105
|
+
share: devices it shares while another measurement sweeps them."""
|
|
106
|
+
|
|
107
|
+
rights = Rights.RUN
|
|
108
|
+
path: str
|
|
109
|
+
python: Tuple[str, ...]
|
|
110
|
+
arguments: Tuple[str, ...] = ()
|
|
111
|
+
workspace: Optional[str] = None
|
|
112
|
+
allow: Tuple[Grant, ...] = ()
|
|
113
|
+
share: Tuple[str, ...] = ()
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
class ListScripts(Operation[Tuple[ScriptInfo, ...]]):
|
|
117
|
+
"""Scripts the daemon runs, and those that ended lately."""
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
class ReadScriptLog(Operation[ScriptLog]):
|
|
121
|
+
"""A script's output from byte since (0: from its start), up to a part at a
|
|
122
|
+
time; call again from next while it runs."""
|
|
123
|
+
|
|
124
|
+
id: int
|
|
125
|
+
since: int = 0
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
class StopScript(Operation[ScriptInfo]):
|
|
129
|
+
"""Stop a script: its measurements are cancelled (they restore what they
|
|
130
|
+
changed), and a script that has not ended a few seconds later is ended."""
|
|
131
|
+
|
|
132
|
+
rights = Rights.STOP
|
|
133
|
+
id: int
|
thzdaq_api/sessions.py
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
"""A script's own measurement: a session the daemon keeps while a script drives
|
|
2
|
+
it from outside (lab.measurement, thzdaq_api.script).
|
|
3
|
+
|
|
4
|
+
A session is a measurement like any other: a number, a file, leases on its
|
|
5
|
+
devices, events windows draw from. The script records into it, tells its
|
|
6
|
+
progress and what the daemon restores when it ends, however it ends: by the
|
|
7
|
+
script, by a cancel (thzdaq cancel, Stop in a window), or when the script falls
|
|
8
|
+
silent (it died, its terminal closed), which ends it interrupted.
|
|
9
|
+
|
|
10
|
+
Calls that belong to a session carry its number (session in read_device,
|
|
11
|
+
set_quantity, call_action): the session's leases are their own, and what a
|
|
12
|
+
person allowed when it started (its devices) is not asked again, except a
|
|
13
|
+
dangerous step or another measurement's sweep.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from typing import Any, Dict, Optional, Tuple, Union
|
|
17
|
+
|
|
18
|
+
import msgspec
|
|
19
|
+
|
|
20
|
+
from thzdaq_api.devices import QuantityValue
|
|
21
|
+
from thzdaq_api.measurement_file import Column
|
|
22
|
+
from thzdaq_api.measurements import PlotInfo, RunInfo
|
|
23
|
+
from thzdaq_api.operation import Operation, Rights
|
|
24
|
+
|
|
25
|
+
SILENT_S = 10.0 # a script silent this long is gone: its session is interrupted
|
|
26
|
+
KEEP_S = 2.0 # how long keep_session waits for a cancel before it answers
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class ScriptSource(msgspec.Struct, frozen=True):
|
|
30
|
+
"""The script a session ran, kept with its data to measure the same again."""
|
|
31
|
+
|
|
32
|
+
path: str
|
|
33
|
+
sha256: str
|
|
34
|
+
text: str
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class SessionState(msgspec.Struct, frozen=True):
|
|
38
|
+
"""How a session stands: cancelled is a request to stop (end it cancelled)."""
|
|
39
|
+
|
|
40
|
+
id: int
|
|
41
|
+
status: str # running, or how it ended
|
|
42
|
+
cancelled: bool = False
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class SweepValues(msgspec.Struct, frozen=True):
|
|
46
|
+
values: Tuple[float, ...]
|
|
47
|
+
unit: str # the SI unit of the values
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class Swept(msgspec.Struct, frozen=True):
|
|
51
|
+
"""A sweep a script was given (a form's value): SI start and stop, points,
|
|
52
|
+
the SI unit; m.sweep(it) goes over its values."""
|
|
53
|
+
|
|
54
|
+
start: float
|
|
55
|
+
stop: float
|
|
56
|
+
points: int
|
|
57
|
+
unit: str = ""
|
|
58
|
+
|
|
59
|
+
def typed(self) -> str:
|
|
60
|
+
"""As people type it, in its SI unit: start:stop:points."""
|
|
61
|
+
return f"{self.start!r}:{self.stop!r}:{self.points}"
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class StartSession(Operation[RunInfo]):
|
|
65
|
+
"""Start a script's own measurement (a session) named title: its file,
|
|
66
|
+
number and events as any measurement has. devices it uses (shared), those
|
|
67
|
+
of them it sweeps (exclusive: another's change spoils its data), and those
|
|
68
|
+
it agrees to share while another measurement sweeps them (share). A device
|
|
69
|
+
it uses later without naming it joins then. silent: seconds without a word
|
|
70
|
+
from the script (keep_session) before the session ends interrupted and the
|
|
71
|
+
daemon restores what the script asked to restore. plots: those it fills
|
|
72
|
+
from its start, as plot_session takes them."""
|
|
73
|
+
|
|
74
|
+
rights = Rights.RUN
|
|
75
|
+
title: str
|
|
76
|
+
devices: Tuple[str, ...] = ()
|
|
77
|
+
exclusive: Tuple[str, ...] = ()
|
|
78
|
+
share: Tuple[str, ...] = ()
|
|
79
|
+
parameters: Dict[str, Any] = {}
|
|
80
|
+
comment: str = ""
|
|
81
|
+
workspace: Optional[str] = None
|
|
82
|
+
script: Optional[ScriptSource] = None
|
|
83
|
+
columns: Tuple[Column, ...] = () # titles and units of record keys
|
|
84
|
+
total: Optional[int] = None # steps, when known
|
|
85
|
+
silent: float = SILENT_S
|
|
86
|
+
plots: Tuple[PlotInfo, ...] = () # those it fills from its start (declared)
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
class KeepSession(Operation[SessionState]):
|
|
90
|
+
"""The script of a session is alive: the daemon keeps the session. Waits up
|
|
91
|
+
to wait seconds (at most 5) for a cancel and answers at once when one comes."""
|
|
92
|
+
|
|
93
|
+
id: int
|
|
94
|
+
wait: float = 0.0
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
class RecordSession(Operation[SessionState]):
|
|
98
|
+
"""Records of a session's table, values encoded as in measurement files
|
|
99
|
+
(thzdaq_api.data); columns describe keys (title, unit, source) the session
|
|
100
|
+
does not know yet or describes anew."""
|
|
101
|
+
|
|
102
|
+
rights = Rights.RUN
|
|
103
|
+
id: int
|
|
104
|
+
table: str
|
|
105
|
+
rows: Tuple[Dict[str, Any], ...]
|
|
106
|
+
columns: Tuple[Column, ...] = ()
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
class AdvanceSession(Operation[SessionState]):
|
|
110
|
+
"""Progress of a session: done steps (one more when not given) of total."""
|
|
111
|
+
|
|
112
|
+
rights = Rights.RUN
|
|
113
|
+
id: int
|
|
114
|
+
done: Optional[int] = None
|
|
115
|
+
total: Optional[int] = None
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
class LogSession(Operation[None]):
|
|
119
|
+
"""A line of a session's log, shown where the measurement is followed."""
|
|
120
|
+
|
|
121
|
+
rights = Rights.RUN
|
|
122
|
+
id: int
|
|
123
|
+
message: str
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
class PlotSession(Operation[PlotInfo]):
|
|
127
|
+
"""A plot of a session's records, drawn from now on and kept in its file;
|
|
128
|
+
labels left empty take the columns' titles and units. Returns it as drawn."""
|
|
129
|
+
|
|
130
|
+
rights = Rights.RUN
|
|
131
|
+
id: int
|
|
132
|
+
plot: PlotInfo
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
class RestoreOnExit(Operation[QuantityValue]):
|
|
136
|
+
"""When the session ends, however it ends, the daemon sets this quantity of
|
|
137
|
+
a device back to the value it has now (returned), in steps where the bench
|
|
138
|
+
limits ask for them."""
|
|
139
|
+
|
|
140
|
+
rights = Rights.SET
|
|
141
|
+
id: int
|
|
142
|
+
ref: str
|
|
143
|
+
key: str
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
class CallOnExit(Operation[None]):
|
|
147
|
+
"""When the session ends, however it ends, the daemon makes a device do an
|
|
148
|
+
action (to_cold); arguments as call_action takes them."""
|
|
149
|
+
|
|
150
|
+
rights = Rights.SET
|
|
151
|
+
id: int
|
|
152
|
+
ref: str
|
|
153
|
+
action: str
|
|
154
|
+
arguments: Dict[str, Union[bool, int, float, str]] = msgspec.field(
|
|
155
|
+
default_factory=dict
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
class EndSession(Operation[RunInfo]):
|
|
160
|
+
"""End a session as the script ended: completed, cancelled (it was asked
|
|
161
|
+
to), failed (error and traceback say why) or interrupted (stopped by hand).
|
|
162
|
+
The daemon restores what it was asked to, then the measurement ends."""
|
|
163
|
+
|
|
164
|
+
rights = Rights.STOP
|
|
165
|
+
id: int
|
|
166
|
+
status: str = "completed"
|
|
167
|
+
error: Optional[str] = None
|
|
168
|
+
traceback: str = ""
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
class ParseSweep(Operation[SweepValues]):
|
|
172
|
+
"""The values of a sweep typed as people type it, start:stop:points in a
|
|
173
|
+
unit ("2:3:51" in mV), as SI values with their SI unit."""
|
|
174
|
+
|
|
175
|
+
text: str
|
|
176
|
+
unit: str = ""
|