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/custom.py
ADDED
|
@@ -0,0 +1,326 @@
|
|
|
1
|
+
"""The bench's own measurements (Custom): a script with declarations at its top,
|
|
2
|
+
kept in the bench's library (measurements/ of the program's folder, next to
|
|
3
|
+
stations/) and listed among the procedures as custom.<its file name>.
|
|
4
|
+
|
|
5
|
+
from thzdaq import connect, device, plot, value
|
|
6
|
+
|
|
7
|
+
bias = device("SIS bias", kind="sis_bias") # a slot of the form
|
|
8
|
+
detector = device("Detector", "PowerDetector")
|
|
9
|
+
voltage = value("Bias voltage", "0:7:351", unit="mV") # a parameter
|
|
10
|
+
t_hot, t_cold = value("Hot load", 300, unit="K"), value("Cold load", 77, unit="K")
|
|
11
|
+
pv = plot("P-V", table="pv", x="voltage", y="power", group_by="load")
|
|
12
|
+
|
|
13
|
+
lab = connect()
|
|
14
|
+
with lab.measurement("pv_hot_cold", devices=[bias, detector]) as m:
|
|
15
|
+
...
|
|
16
|
+
|
|
17
|
+
A declaration is named by the name it is assigned to (bias, voltage): the
|
|
18
|
+
slots and parameters of the procedure, as thzdaq run custom.x --device
|
|
19
|
+
bias=sis_bias_2 --set voltage=0:7:101 names them. Declarations come first,
|
|
20
|
+
each assigned to a name, before connect().
|
|
21
|
+
|
|
22
|
+
The daemon learns a file's form by running it described (DESCRIBE_ENV: its
|
|
23
|
+
declarations are written to that file, and connect() ends the script before
|
|
24
|
+
it touches the bench), and runs it with the devices and values chosen
|
|
25
|
+
(INPUTS_ENV, values in SI as the daemon parsed them). Run as it is (python
|
|
26
|
+
x.py), a script takes the defaults, parsed by the daemon.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
import ast
|
|
30
|
+
import re
|
|
31
|
+
from typing import Any, Dict, List, Optional, Tuple, Union
|
|
32
|
+
|
|
33
|
+
import msgspec
|
|
34
|
+
|
|
35
|
+
from thzdaq_api.measurements import PlotInfo, ProcedureInfo
|
|
36
|
+
from thzdaq_api.operation import Operation, Rights
|
|
37
|
+
|
|
38
|
+
GROUP = "custom" # custom.<name>: the group of the bench's own measurements
|
|
39
|
+
LIBRARY = "measurements" # the folder of the program that holds them
|
|
40
|
+
SUFFIX = ".py"
|
|
41
|
+
DESCRIBE_ENV = "THZDAQ_DESCRIBE" # the file a described script writes into
|
|
42
|
+
INPUTS_ENV = "THZDAQ_INPUTS" # the devices and values a run was given (JSON)
|
|
43
|
+
MODULE = "thzdaq" # what a script imports declarations from
|
|
44
|
+
|
|
45
|
+
# Declarations by the function that makes them
|
|
46
|
+
DEVICE, VALUE, PLOT, INSTRUMENT = "device", "value", "plot", "instrument"
|
|
47
|
+
DECLARATIONS = (DEVICE, VALUE, PLOT, INSTRUMENT)
|
|
48
|
+
CONNECT = "connect" # declarations come before it
|
|
49
|
+
|
|
50
|
+
# Kinds of values, by their default (and choices)
|
|
51
|
+
FLOAT, INT, BOOL, CHOICE, SWEEP, TEXT = (
|
|
52
|
+
"float",
|
|
53
|
+
"int",
|
|
54
|
+
"bool",
|
|
55
|
+
"choice",
|
|
56
|
+
"sweep",
|
|
57
|
+
"text",
|
|
58
|
+
)
|
|
59
|
+
FLOAT_LIST, TEXT_LIST = "float_list", "string_list"
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def procedure_name(name: str) -> str:
|
|
63
|
+
"""pv_hot_cold -> custom.pv_hot_cold"""
|
|
64
|
+
return f"{GROUP}.{name}"
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def file_name(procedure: str) -> Optional[str]:
|
|
68
|
+
"""custom.pv_hot_cold -> pv_hot_cold; None for another procedure."""
|
|
69
|
+
group, dot, name = procedure.partition(".")
|
|
70
|
+
return name if group == GROUP and dot and name else None
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class SlotDeclared(msgspec.Struct, frozen=True):
|
|
74
|
+
"""device(title, *capabilities, kind=...): a device chosen in the form."""
|
|
75
|
+
|
|
76
|
+
name: str
|
|
77
|
+
title: str
|
|
78
|
+
capabilities: Tuple[str, ...] = ()
|
|
79
|
+
kind: Optional[str] = None
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
class ValueDeclared(msgspec.Struct, frozen=True):
|
|
83
|
+
"""value(title, default, unit=...): a parameter, its default and limits as
|
|
84
|
+
people type them (in unit; a sweep "start:stop:points")."""
|
|
85
|
+
|
|
86
|
+
name: str
|
|
87
|
+
title: str
|
|
88
|
+
default: Any
|
|
89
|
+
unit: str = ""
|
|
90
|
+
minimum: Optional[float] = None
|
|
91
|
+
maximum: Optional[float] = None
|
|
92
|
+
choices: Tuple[Any, ...] = ()
|
|
93
|
+
help: str = ""
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
class InstrumentDeclared(msgspec.Struct, frozen=True):
|
|
97
|
+
"""instrument(id, driver=..., connection=...): an instrument of the
|
|
98
|
+
profile, put there by the script's first run once a person allows it.
|
|
99
|
+
connection as the script gives it: a line, or the fields of the profile."""
|
|
100
|
+
|
|
101
|
+
name: str
|
|
102
|
+
instrument: str
|
|
103
|
+
driver: str
|
|
104
|
+
connection: Union[str, Dict[str, Any]]
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
class Declarations(msgspec.Struct, frozen=True):
|
|
108
|
+
"""What a script declares at its top, in order."""
|
|
109
|
+
|
|
110
|
+
slots: Tuple[SlotDeclared, ...] = ()
|
|
111
|
+
values: Tuple[ValueDeclared, ...] = ()
|
|
112
|
+
plots: Tuple[PlotInfo, ...] = ()
|
|
113
|
+
instruments: Tuple[InstrumentDeclared, ...] = ()
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
class Given(msgspec.Struct, frozen=True):
|
|
117
|
+
"""A value a script is given: SI as JSON carries it (a sweep {start, stop,
|
|
118
|
+
points}), its SI unit and its kind."""
|
|
119
|
+
|
|
120
|
+
value: Any
|
|
121
|
+
unit: str = ""
|
|
122
|
+
kind: str = FLOAT
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
class Inputs(msgspec.Struct, frozen=True):
|
|
126
|
+
"""What a run of a custom measurement was given: a device per slot, a
|
|
127
|
+
value per parameter, by their names."""
|
|
128
|
+
|
|
129
|
+
devices: Dict[str, str] = {}
|
|
130
|
+
values: Dict[str, Given] = {}
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
class CustomInfo(msgspec.Struct, frozen=True):
|
|
134
|
+
"""A script of the library: its procedure custom.<name>, and why it
|
|
135
|
+
cannot run (not described: its error with the traceback) when it cannot."""
|
|
136
|
+
|
|
137
|
+
name: str # its file's without .py
|
|
138
|
+
procedure: str
|
|
139
|
+
title: str
|
|
140
|
+
path: str
|
|
141
|
+
sha256: str
|
|
142
|
+
error: str = ""
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
class CustomLibrary(msgspec.Struct, frozen=True):
|
|
146
|
+
"""The bench's library: its folder and the scripts in it."""
|
|
147
|
+
|
|
148
|
+
folder: str
|
|
149
|
+
measurements: Tuple[CustomInfo, ...]
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
class CustomText(msgspec.Struct, frozen=True):
|
|
153
|
+
info: CustomInfo
|
|
154
|
+
text: str
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
# Problems a check finds, by what finds them
|
|
158
|
+
SYNTAX, NAMES, DECLARED, BENCH = "syntax", "names", "declared", "bench"
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
class Problem(msgspec.Struct, frozen=True):
|
|
162
|
+
"""What is wrong with a script: where (its line; None for the whole
|
|
163
|
+
script) and what. kind: syntax, names (an undefined or unused name),
|
|
164
|
+
declared (its declarations), bench (a device, quantity or limit of this
|
|
165
|
+
bench)."""
|
|
166
|
+
|
|
167
|
+
line: Optional[int]
|
|
168
|
+
text: str
|
|
169
|
+
kind: str
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
class CustomCheck(msgspec.Struct, frozen=True):
|
|
173
|
+
"""A script checked: its form when it is described, and its problems."""
|
|
174
|
+
|
|
175
|
+
procedure: Optional[ProcedureInfo]
|
|
176
|
+
problems: Tuple[Problem, ...] = ()
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
class ListCustom(Operation[CustomLibrary]):
|
|
180
|
+
"""The bench's own measurements: the scripts of its library (measurements/
|
|
181
|
+
of the program's folder), each with its procedure custom.<name> and why it
|
|
182
|
+
cannot run, if it cannot."""
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
class ReadCustom(Operation[CustomText]):
|
|
186
|
+
"""The text of a script of the library, by its name (script pv_hot_cold
|
|
187
|
+
for custom.pv_hot_cold)."""
|
|
188
|
+
|
|
189
|
+
script: str
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
class CheckCustom(Operation[CustomCheck]):
|
|
193
|
+
"""Check a script of the library (by its name), or a text of it not
|
|
194
|
+
saved yet (text): its syntax, undefined names, its declarations (the form
|
|
195
|
+
it describes) and what it names of this bench: devices, their quantities
|
|
196
|
+
and actions, sweeps beyond the limits of what they set."""
|
|
197
|
+
|
|
198
|
+
script: str
|
|
199
|
+
text: Optional[str] = None
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
class WriteCustom(Operation[CustomCheck]):
|
|
203
|
+
"""Write a script of the library (a new one, or over the one of that
|
|
204
|
+
name: letters, digits and _) and check it as check_custom does. A person
|
|
205
|
+
sees the change first when an agent writes it. Run it with
|
|
206
|
+
start_measurement custom.<script>."""
|
|
207
|
+
|
|
208
|
+
rights = Rights.LIBRARY
|
|
209
|
+
script: str
|
|
210
|
+
text: str
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
class ParseValue(Operation[Given]):
|
|
214
|
+
"""A declared value's default as people type it (in its unit; a sweep
|
|
215
|
+
"start:stop:points"), parsed as a run of the measurement takes it: SI,
|
|
216
|
+
with its SI unit and kind. Invalid ones are refused."""
|
|
217
|
+
|
|
218
|
+
value: ValueDeclared
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
class DeclarationError(ValueError):
|
|
222
|
+
"""Declarations a script cannot be described by: told with the line."""
|
|
223
|
+
|
|
224
|
+
def __init__(self, text: str, line: Optional[int] = None):
|
|
225
|
+
super().__init__(f"line {line}: {text}" if line else text)
|
|
226
|
+
self.line = line
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
# A name of the library: the file name of a script, custom.<name>
|
|
230
|
+
NAME = re.compile(r"[A-Za-z][A-Za-z0-9_]*")
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
def valid_name(name: str) -> bool:
|
|
234
|
+
return NAME.fullmatch(name) is not None
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
def _called(node: ast.AST, names: Dict[str, str]) -> Optional[str]:
|
|
238
|
+
"""The declaration (or connect) a call makes, by the names the script
|
|
239
|
+
imported them as; None for another call."""
|
|
240
|
+
if not isinstance(node, ast.Call):
|
|
241
|
+
return None
|
|
242
|
+
func = node.func
|
|
243
|
+
if isinstance(func, ast.Name):
|
|
244
|
+
return names.get(func.id)
|
|
245
|
+
if (
|
|
246
|
+
isinstance(func, ast.Attribute)
|
|
247
|
+
and isinstance(func.value, ast.Name)
|
|
248
|
+
and names.get(func.value.id) == MODULE
|
|
249
|
+
):
|
|
250
|
+
return func.attr if func.attr in (*DECLARATIONS, CONNECT) else None
|
|
251
|
+
return None
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
def _imported(tree: ast.Module) -> Dict[str, str]:
|
|
255
|
+
"""Names in the script -> the declaration, connect or the module they are."""
|
|
256
|
+
found: Dict[str, str] = {}
|
|
257
|
+
for node in ast.walk(tree):
|
|
258
|
+
if (
|
|
259
|
+
isinstance(node, ast.ImportFrom)
|
|
260
|
+
and node.module
|
|
261
|
+
and (node.module == MODULE or node.module.startswith("thzdaq_api"))
|
|
262
|
+
):
|
|
263
|
+
for alias in node.names:
|
|
264
|
+
if alias.name == "*":
|
|
265
|
+
found.update((name, name) for name in (*DECLARATIONS, CONNECT))
|
|
266
|
+
elif alias.name in (*DECLARATIONS, CONNECT):
|
|
267
|
+
found[alias.asname or alias.name] = alias.name
|
|
268
|
+
elif isinstance(node, ast.Import):
|
|
269
|
+
for alias in node.names:
|
|
270
|
+
if alias.name == MODULE:
|
|
271
|
+
found[alias.asname or alias.name] = MODULE
|
|
272
|
+
return found
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
def declared_names(text: str) -> Tuple[Tuple[str, str], ...]:
|
|
276
|
+
"""(declaration, name) of each declaration a script's text makes, in
|
|
277
|
+
order. DeclarationError for one not assigned to a name, or one after
|
|
278
|
+
connect(); SyntaxError for text that is no Python."""
|
|
279
|
+
tree = ast.parse(text)
|
|
280
|
+
names = _imported(tree)
|
|
281
|
+
found: List[Tuple[str, str]] = []
|
|
282
|
+
connected: Optional[int] = None
|
|
283
|
+
for statement in tree.body:
|
|
284
|
+
targets: List[Tuple[ast.AST, ast.AST]] = []
|
|
285
|
+
if isinstance(statement, ast.Assign) and len(statement.targets) == 1:
|
|
286
|
+
target, assigned = statement.targets[0], statement.value
|
|
287
|
+
if isinstance(target, ast.Tuple) and isinstance(assigned, ast.Tuple):
|
|
288
|
+
targets = list(zip(target.elts, assigned.elts))
|
|
289
|
+
else:
|
|
290
|
+
targets = [(target, assigned)]
|
|
291
|
+
for node in ast.walk(statement):
|
|
292
|
+
made = _called(node, names)
|
|
293
|
+
if made is None:
|
|
294
|
+
continue
|
|
295
|
+
if made == CONNECT:
|
|
296
|
+
connected = connected or node.lineno
|
|
297
|
+
continue
|
|
298
|
+
if connected is not None:
|
|
299
|
+
raise DeclarationError(
|
|
300
|
+
f"{made}(...) after connect() on line {connected}:"
|
|
301
|
+
" declare before connect()",
|
|
302
|
+
node.lineno,
|
|
303
|
+
)
|
|
304
|
+
name = next(
|
|
305
|
+
(t.id for t, v in targets if v is node and isinstance(t, ast.Name)),
|
|
306
|
+
None,
|
|
307
|
+
)
|
|
308
|
+
if name is None:
|
|
309
|
+
raise DeclarationError(
|
|
310
|
+
f"assign {made}(...) to a name at the top of the file:"
|
|
311
|
+
f" x = {made}(...)",
|
|
312
|
+
node.lineno,
|
|
313
|
+
)
|
|
314
|
+
found.append((made, name))
|
|
315
|
+
return tuple(found)
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
def title_of(text: str, name: str) -> Tuple[str, str]:
|
|
319
|
+
"""A script's title and what it does: the first line of its docstring and
|
|
320
|
+
the rest; its file's name and nothing without one."""
|
|
321
|
+
try:
|
|
322
|
+
doc = ast.get_docstring(ast.parse(text)) or ""
|
|
323
|
+
except SyntaxError:
|
|
324
|
+
doc = ""
|
|
325
|
+
title, _, about = doc.partition("\n")
|
|
326
|
+
return title.strip() or name, about.strip()
|
thzdaq_api/daemon.py
ADDED
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
"""The daemon itself: what it is and holds, how it is stopped or restarted."""
|
|
2
|
+
|
|
3
|
+
from enum import Enum
|
|
4
|
+
from typing import Dict, Optional, Tuple
|
|
5
|
+
|
|
6
|
+
import msgspec
|
|
7
|
+
|
|
8
|
+
from thzdaq_api.measurements import RunInfo
|
|
9
|
+
from thzdaq_api.operation import Operation, Rights
|
|
10
|
+
from thzdaq_api.rights import Decision
|
|
11
|
+
from thzdaq_api.scripts import ScriptInfo
|
|
12
|
+
from thzdaq_api.station import ConnectionInfo
|
|
13
|
+
|
|
14
|
+
# Changes with the contract: a client and a daemon of other versions do not talk
|
|
15
|
+
API_VERSION = 1
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class HostInfo(msgspec.Struct, frozen=True):
|
|
19
|
+
"""Where a running daemon serves, written once it does (the host file)."""
|
|
20
|
+
|
|
21
|
+
pid: int
|
|
22
|
+
port: int
|
|
23
|
+
token: str # every request carries it: only who can read the file talks
|
|
24
|
+
api_version: int
|
|
25
|
+
app_version: str
|
|
26
|
+
executable: str # the installation that runs it
|
|
27
|
+
started: str # wall time, ISO
|
|
28
|
+
station: Optional[str] # the profile's file
|
|
29
|
+
simulate: bool
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class Installation(msgspec.Struct, frozen=True):
|
|
33
|
+
"""The build that started last (the install file): a client from PyPI
|
|
34
|
+
without the daemon package starts that build's daemon."""
|
|
35
|
+
|
|
36
|
+
program: str # its ThzDAQ.exe, which runs the daemon with --serve
|
|
37
|
+
app_version: str
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class Health(msgspec.Struct, frozen=True):
|
|
41
|
+
"""What /health answers: enough to know it is the daemon a client expects."""
|
|
42
|
+
|
|
43
|
+
pid: int
|
|
44
|
+
api_version: int
|
|
45
|
+
app_version: str
|
|
46
|
+
simulate: bool
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class ProcessInfo(msgspec.Struct, frozen=True):
|
|
50
|
+
pid: int
|
|
51
|
+
api_version: int
|
|
52
|
+
app_version: str
|
|
53
|
+
executable: str # the installation that runs it
|
|
54
|
+
started: str # wall time, ISO
|
|
55
|
+
port: int
|
|
56
|
+
simulate: bool
|
|
57
|
+
memory: int = 0 # bytes it holds in RAM; 0: not known (a lab in a client)
|
|
58
|
+
threads: int = 0 # 0: not known
|
|
59
|
+
errors: Tuple[str, ...] = () # the last errors of its log, the latest last
|
|
60
|
+
|
|
61
|
+
def usage(self) -> str:
|
|
62
|
+
"""Its memory and threads as people read them; empty when not known."""
|
|
63
|
+
if not self.memory:
|
|
64
|
+
return ""
|
|
65
|
+
return f"{self.memory / 2**20:.0f} MB, {self.threads} threads"
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class ClientInfo(msgspec.Struct, frozen=True):
|
|
69
|
+
"""A client listening to the events: a GUI window, a CLI, an agent."""
|
|
70
|
+
|
|
71
|
+
kind: str # gui, cli, cli:answers, mcp, assistant, script
|
|
72
|
+
pid: int
|
|
73
|
+
origin: str
|
|
74
|
+
since: str # wall time, ISO
|
|
75
|
+
window: str = "" # the id of the main window it is: one ui_* go to
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
class LaneInfo(msgspec.Struct, frozen=True):
|
|
79
|
+
"""The queue of one instrument: what waits and what runs now."""
|
|
80
|
+
|
|
81
|
+
instrument: str
|
|
82
|
+
pending: int
|
|
83
|
+
current: Optional[str] = None # the device the running job talks to
|
|
84
|
+
busy_for: float = 0.0 # seconds the running job has taken
|
|
85
|
+
stuck: bool = False # running for longer than a job should
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
class PollInfo(msgspec.Struct, frozen=True):
|
|
89
|
+
ref: str
|
|
90
|
+
interval: float
|
|
91
|
+
subscribers: int
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
class DaemonStatus(msgspec.Struct, frozen=True):
|
|
95
|
+
process: ProcessInfo
|
|
96
|
+
station: str # the profile's name
|
|
97
|
+
path: Optional[str] # its file
|
|
98
|
+
opened: Tuple[str, ...] # instruments open now
|
|
99
|
+
clients: Tuple[ClientInfo, ...]
|
|
100
|
+
runs: Tuple[RunInfo, ...] # measurements running
|
|
101
|
+
lanes: Tuple[LaneInfo, ...]
|
|
102
|
+
connections: Tuple[ConnectionInfo, ...]
|
|
103
|
+
polls: Tuple[PollInfo, ...]
|
|
104
|
+
seq: int # the last event
|
|
105
|
+
problems: Tuple[str, ...] # stuck lanes, broken connections
|
|
106
|
+
scripts: Tuple[ScriptInfo, ...] = () # scripts running
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
class Heartbeat(msgspec.Struct, frozen=True):
|
|
110
|
+
"""Every couple of seconds on each event stream: the daemon is alive."""
|
|
111
|
+
|
|
112
|
+
seq: int
|
|
113
|
+
clients: int
|
|
114
|
+
runs: int
|
|
115
|
+
problems: Tuple[str, ...] = ()
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
class StopMode(str, Enum):
|
|
119
|
+
GRACEFUL = "graceful" # refused while measurements run
|
|
120
|
+
CANCEL = "cancel" # cancel them (their on_exit runs), go to the safe state
|
|
121
|
+
ABORT = "abort" # as cancel, and break reads that hang first
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
class GetDaemonStatus(Operation[DaemonStatus]):
|
|
125
|
+
"""What the daemon is and holds now: its process, the profile, clients,
|
|
126
|
+
running measurements and scripts, instrument queues, connections, polls
|
|
127
|
+
and problems."""
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
class StopDaemon(Operation[None]):
|
|
131
|
+
"""Stop the daemon. graceful is refused while measurements or scripts run;
|
|
132
|
+
cancel ends them (their on_exit restores what they changed) and sets the
|
|
133
|
+
profile's safe state; abort also breaks reads that hang. Clients lose the
|
|
134
|
+
connection."""
|
|
135
|
+
|
|
136
|
+
rights = Rights.DAEMON
|
|
137
|
+
mode: StopMode = StopMode.GRACEFUL
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
class DaemonSettings(msgspec.Struct, frozen=True):
|
|
141
|
+
"""What the daemon keeps in its daemon.json."""
|
|
142
|
+
|
|
143
|
+
idle_timeout: float # s with no client and no measurement before it ends; 0: never
|
|
144
|
+
# What agents may do by the rights a call needs (rights.AGENTS until changed)
|
|
145
|
+
agents: Dict[Rights, Decision] = {}
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
class GetDaemonSettings(Operation[DaemonSettings]):
|
|
149
|
+
"""The daemon's settings: how long it waits idle before it ends, and what
|
|
150
|
+
agents may do by the rights a call needs (allow, ask, deny)."""
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
class SetDaemonSettings(Operation[DaemonSettings]):
|
|
154
|
+
"""Change the daemon's settings, those given; they are kept for its next
|
|
155
|
+
starts. agents changes what agents may do by rights (allow, ask, deny):
|
|
156
|
+
station and answer stay deny, and only people change it."""
|
|
157
|
+
|
|
158
|
+
rights = Rights.DAEMON
|
|
159
|
+
idle_timeout: Optional[float] = None
|
|
160
|
+
agents: Dict[Rights, Decision] = {}
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
class ReadDaemonLog(Operation[Tuple[str, ...]]):
|
|
164
|
+
"""The last lines of the daemon's log; none when it keeps no log file."""
|
|
165
|
+
|
|
166
|
+
lines: int = 100
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
class ResetLane(Operation[bool]):
|
|
170
|
+
"""An instrument that does not answer holds its queue: break its commands
|
|
171
|
+
and give it a new queue. Calls waiting in the old one fail at once; the one
|
|
172
|
+
that hangs ends when its read is broken. Returns whether it had a queue."""
|
|
173
|
+
|
|
174
|
+
rights = Rights.DAEMON
|
|
175
|
+
instrument: str
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
class RestartDaemon(Operation[None]):
|
|
179
|
+
"""Stop the daemon as stop_daemon does and start it again with the same
|
|
180
|
+
profile; clients reconnect and take a new snapshot."""
|
|
181
|
+
|
|
182
|
+
rights = Rights.DAEMON
|
|
183
|
+
mode: StopMode = StopMode.GRACEFUL
|
thzdaq_api/data.py
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
"""Values of measurement data: numbers that know what they are (Measured), and
|
|
2
|
+
their encoding as JSON in thzdaq-measurement files and in records as run
|
|
3
|
+
events carry them.
|
|
4
|
+
|
|
5
|
+
JSON has no complex numbers and no NaN or infinity: a complex value is
|
|
6
|
+
{"__complex__": [re, im]}, a non-finite float {"__float__": "nan"}.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
import math
|
|
10
|
+
from typing import Any
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class Measured(float):
|
|
14
|
+
"""A number read from a device or swept, in SI units, with its unit, its
|
|
15
|
+
title and where it was read ("<ref>/<key>"; empty when it was not). In
|
|
16
|
+
calculations it is a plain float; a script records it with what it knows."""
|
|
17
|
+
|
|
18
|
+
unit: str
|
|
19
|
+
title: str
|
|
20
|
+
source: str
|
|
21
|
+
|
|
22
|
+
def __new__(cls, value: float, unit: str = "", title: str = "", source: str = ""):
|
|
23
|
+
measured = super().__new__(cls, value)
|
|
24
|
+
measured.unit, measured.title, measured.source = unit, title, source
|
|
25
|
+
return measured
|
|
26
|
+
|
|
27
|
+
def __repr__(self) -> str:
|
|
28
|
+
return f"{float(self)!r} {self.unit}".rstrip()
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def encode_values(value: Any) -> Any:
|
|
32
|
+
if isinstance(value, complex):
|
|
33
|
+
return {"__complex__": [value.real, value.imag]}
|
|
34
|
+
if isinstance(value, float):
|
|
35
|
+
return float(value) if math.isfinite(value) else {"__float__": repr(value)}
|
|
36
|
+
if isinstance(value, dict):
|
|
37
|
+
return {key: encode_values(item) for key, item in value.items()}
|
|
38
|
+
if isinstance(value, (list, tuple)):
|
|
39
|
+
return [encode_values(item) for item in value]
|
|
40
|
+
if hasattr(value, "item") and callable(value.item): # numpy scalars
|
|
41
|
+
return encode_values(value.item())
|
|
42
|
+
return value
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def decode_values(value: Any) -> Any:
|
|
46
|
+
if isinstance(value, dict):
|
|
47
|
+
if set(value) == {"__complex__"}:
|
|
48
|
+
real, imag = value["__complex__"]
|
|
49
|
+
return complex(real, imag)
|
|
50
|
+
if set(value) == {"__float__"}:
|
|
51
|
+
return float(value["__float__"])
|
|
52
|
+
return {key: decode_values(item) for key, item in value.items()}
|
|
53
|
+
if isinstance(value, list):
|
|
54
|
+
return [decode_values(item) for item in value]
|
|
55
|
+
return value
|