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.
Files changed (57) hide show
  1. thzdaq_api/__init__.py +1 -0
  2. thzdaq_api/analysis.py +62 -0
  3. thzdaq_api/approvals.py +87 -0
  4. thzdaq_api/assistant/agents.md +202 -0
  5. thzdaq_api/assistant/assistant.md +23 -0
  6. thzdaq_api/assistant/hints.md +15 -0
  7. thzdaq_api/atomic.py +79 -0
  8. thzdaq_api/catalog.py +131 -0
  9. thzdaq_api/console.py +70 -0
  10. thzdaq_api/custom.py +326 -0
  11. thzdaq_api/daemon.py +183 -0
  12. thzdaq_api/data.py +55 -0
  13. thzdaq_api/declare.py +193 -0
  14. thzdaq_api/declaring.py +125 -0
  15. thzdaq_api/devices.py +307 -0
  16. thzdaq_api/errors.py +47 -0
  17. thzdaq_api/events.py +224 -0
  18. thzdaq_api/examples/hot_cold.py +67 -0
  19. thzdaq_api/examples/hot_cold_grid.py +74 -0
  20. thzdaq_api/examples/iv_analysis.py +34 -0
  21. thzdaq_api/examples/map.py +42 -0
  22. thzdaq_api/examples/monitor.py +35 -0
  23. thzdaq_api/examples/raw_instrument.py +37 -0
  24. thzdaq_api/examples/sweep.py +38 -0
  25. thzdaq_api/examples.py +79 -0
  26. thzdaq_api/guides.py +61 -0
  27. thzdaq_api/host.py +494 -0
  28. thzdaq_api/interpreters.py +422 -0
  29. thzdaq_api/kernel.py +137 -0
  30. thzdaq_api/lab.py +562 -0
  31. thzdaq_api/lanes.py +170 -0
  32. thzdaq_api/leases.py +29 -0
  33. thzdaq_api/lock.py +65 -0
  34. thzdaq_api/measurement_file.py +459 -0
  35. thzdaq_api/measurements.py +433 -0
  36. thzdaq_api/operation.py +52 -0
  37. thzdaq_api/origins.py +86 -0
  38. thzdaq_api/present.py +376 -0
  39. thzdaq_api/procedures.py +124 -0
  40. thzdaq_api/raw.py +272 -0
  41. thzdaq_api/remote.py +267 -0
  42. thzdaq_api/rights.py +81 -0
  43. thzdaq_api/script.py +382 -0
  44. thzdaq_api/scripts.py +133 -0
  45. thzdaq_api/sessions.py +176 -0
  46. thzdaq_api/station.py +192 -0
  47. thzdaq_api/terminal.py +66 -0
  48. thzdaq_api/tools.py +275 -0
  49. thzdaq_api/transport.py +93 -0
  50. thzdaq_api/ui.py +152 -0
  51. thzdaq_api/windows.py +192 -0
  52. thzdaq_api/wire.py +35 -0
  53. thzdaq_api/workspace.py +239 -0
  54. thzdaq_api-0.0.6b3.dist-info/METADATA +30 -0
  55. thzdaq_api-0.0.6b3.dist-info/RECORD +57 -0
  56. thzdaq_api-0.0.6b3.dist-info/WHEEL +4 -0
  57. thzdaq_api-0.0.6b3.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,459 @@
1
+ """The measurement file (thzdaq-measurement v1): what a run produced, as plain
2
+ dicts that go to JSON. The daemon writes it; anyone reads it (read_measurement,
3
+ MeasurementFolder) and exports a table (export_csv).
4
+
5
+ A Measurement holds tables; a table keeps its data column-wise, like the old
6
+ store did ({"voltage": [...], "current": [...]}), and describes every column
7
+ (title, SI unit), so plots and exports know what they show.
8
+
9
+ {
10
+ "format": "thzdaq-measurement", "version": 1,
11
+ "id": 42, "procedure": "sis.current_vs_voltage", "title": "I-V curve",
12
+ "status": "completed", "started": "...", "finished": "...",
13
+ "comment": "", "parameters": {...},
14
+ "devices": {"bias": {"ref": "sis_bias_1", "title": "SIS b1d4", ...}},
15
+ "tables": {"iv": {"title": "I-V", "columns": [{"key": "voltage",
16
+ "title": "Voltage", "unit": "V"}, ...],
17
+ "data": {"voltage": [...], "current": [...]}}},
18
+ "results": {...}, "station": {...}, "metadata": {...},
19
+ "plots": [{"key": "iv", "title": "I-V", "table": "iv", ...}]
20
+ }
21
+
22
+ plots are those it is drawn with (PlotInfo as JSON): those of its procedure
23
+ for the run and those it added while it ran, so the file draws itself however
24
+ the procedure changes later. Files written before have none (null): their
25
+ plots are those of their procedure, found by its name (RENAMED: an older one),
26
+ and those of metadata "plots".
27
+
28
+ While it runs, the file holds its description without records (the data of
29
+ every table empty) and the records are appended next to it, one line each,
30
+ to <id>_<procedure>.jsonl: {"table": "iv", "record": {"voltage": ...}}. At
31
+ its end the whole file is written and the records file removed. A file still
32
+ marked running (its writer gone, or not finished) reads with the records of
33
+ its records file: none of them is lost when the process is killed.
34
+ """
35
+
36
+ import csv
37
+ import json
38
+ import os
39
+ from dataclasses import dataclass, field
40
+ from pathlib import Path
41
+ from typing import Any, Dict, Iterable, Iterator, List, Mapping, Optional, Tuple, Union
42
+
43
+ from thzdaq_api.data import decode_values, encode_values
44
+ from thzdaq_api.atomic import file_access, read_bytes
45
+
46
+ PathLike = Union[str, Path]
47
+
48
+ FORMAT = "thzdaq-measurement"
49
+ FORMAT_VERSION = 1
50
+
51
+ RUNNING = "running"
52
+ COMPLETED = "completed"
53
+ CANCELLED = "cancelled"
54
+ FAILED = "failed"
55
+ INTERRUPTED = "interrupted" # saved as running, but the process is gone
56
+ STATUSES = (RUNNING, COMPLETED, CANCELLED, FAILED, INTERRUPTED)
57
+
58
+ # Metadata of what others did to its devices: a change of a device it sweeps,
59
+ # accepted with share (conflicts), and changes to the devices it only uses
60
+ CONFLICTS = "conflicts"
61
+ INTERACTIONS = "interactions"
62
+ # Metadata of what a person allowed the script that started it in advance
63
+ ALLOWED = "allowed"
64
+ # Metadata: the copy of the bench profile in its workspace (workspace.ProfileCopy)
65
+ PROFILE = "profile"
66
+ # Metadata of files written before plots were kept whole: the plots a run
67
+ # added while it ran (a script's m.plot), as PlotInfo
68
+ PLOTS = "plots"
69
+ # Metadata: the script a session ran, as sessions.ScriptSource (path, sha256, text)
70
+ SCRIPT = "script"
71
+
72
+
73
+ # The records of a running measurement, next to its file: one line each
74
+ RECORDS_SUFFIX = ".jsonl"
75
+ TABLE = "table"
76
+ RECORD = "record"
77
+
78
+ # Numbers given by the store (1, 2, 3, ... per data folder); 0 until numbered.
79
+ # Files of older versions keep their text ids ("20261023-022400-ab12").
80
+ MeasurementId = Union[int, str]
81
+
82
+
83
+ @dataclass(frozen=True)
84
+ class Column:
85
+ key: str
86
+ title: str = ""
87
+ unit: str = "" # SI unit of the stored values
88
+ # The device quantity the values were read from, "<ref>/<key>"
89
+ # (power_meter_1/power); empty for set, swept or computed values
90
+ source: str = ""
91
+
92
+ @property
93
+ def label(self) -> str:
94
+ title = self.title or self.key
95
+ return f"{title}, {self.unit}" if self.unit else title
96
+
97
+ def to_dict(self) -> Dict[str, Any]:
98
+ found = {"key": self.key, "title": self.title, "unit": self.unit}
99
+ return {**found, "source": self.source} if self.source else found
100
+
101
+ @classmethod
102
+ def from_dict(cls, data: Mapping[str, Any]) -> "Column":
103
+ return cls(
104
+ data["key"],
105
+ data.get("title", ""),
106
+ data.get("unit", ""),
107
+ data.get("source", ""),
108
+ )
109
+
110
+
111
+ # Titles and units of the usual record keys; procedures may override per key
112
+ KNOWN_COLUMNS: Dict[str, Column] = {
113
+ c.key: c
114
+ for c in (
115
+ Column("time", "Time", "s"),
116
+ Column("wall_time", "Wall time"),
117
+ Column("voltage", "Voltage", "V"),
118
+ Column("voltage_set", "Voltage setpoint", "V"),
119
+ Column("current", "Current", "A"),
120
+ Column("coil_current", "Coil current", "A"),
121
+ Column("power", "Power", "dBm"),
122
+ Column("frequency", "Frequency", "Hz"),
123
+ Column("frequency_set", "Frequency setpoint", "Hz"),
124
+ Column("angle", "Angle", "deg"),
125
+ Column("temperature", "Temperature", "K"),
126
+ Column("pressure", "Pressure", "Pa"),
127
+ Column("y_factor", "Y-factor", "dB"),
128
+ Column("noise_temperature", "Noise temperature", "K"),
129
+ Column("amplifier_temperature", "Amplifier noise temperature", "K"),
130
+ Column("magnitude_db", "Magnitude", "dB"),
131
+ Column("phase_mean", "Mean phase", "rad"),
132
+ Column("power_difference", "Power difference", "dB"),
133
+ Column("load", "Load"),
134
+ Column("channel", "IF channel"),
135
+ Column("tone", "Test tone"),
136
+ Column("device", "Device"),
137
+ Column("sis1_voltage", "SIS1 voltage", "V"),
138
+ Column("sis1_current", "SIS1 current", "A"),
139
+ Column("sis2_voltage", "SIS2 voltage", "V"),
140
+ Column("sis2_current", "SIS2 current", "A"),
141
+ Column("sis1_voltage_set", "SIS1 voltage setpoint", "V"),
142
+ Column("sis2_voltage_set", "SIS2 voltage setpoint", "V"),
143
+ Column("tn_upper", "Tn upper", "K"),
144
+ Column("tn_lower", "Tn lower", "K"),
145
+ Column("srr_upper", "SRR upper", "dB"),
146
+ Column("srr_lower", "SRR lower", "dB"),
147
+ )
148
+ }
149
+
150
+
151
+ def column_for(key: str, overrides: Optional[Mapping[str, Column]] = None) -> Column:
152
+ if overrides and key in overrides:
153
+ return overrides[key]
154
+ if key in KNOWN_COLUMNS:
155
+ return KNOWN_COLUMNS[key]
156
+ return Column(key, key.replace("_", " ").capitalize())
157
+
158
+
159
+ @dataclass
160
+ class Table:
161
+ """Records of one kind, stored column-wise."""
162
+
163
+ name: str
164
+ title: str = ""
165
+ columns: List[Column] = field(default_factory=list)
166
+ data: Dict[str, List[Any]] = field(default_factory=dict)
167
+
168
+ def __len__(self) -> int:
169
+ return len(next(iter(self.data.values()), []))
170
+
171
+ def column(self, key: str) -> List[Any]:
172
+ return self.data.get(key, [None] * len(self))
173
+
174
+ def __getitem__(self, key: str) -> List[Any]:
175
+ """The values of a column: table["voltage"]."""
176
+ return self.data[key]
177
+
178
+ def get_column(self, key: str) -> Optional[Column]:
179
+ return next((c for c in self.columns if c.key == key), None)
180
+
181
+ def append(
182
+ self,
183
+ record: Mapping[str, Any],
184
+ overrides: Optional[Mapping[str, Column]] = None,
185
+ ) -> None:
186
+ size = len(self)
187
+ for key in record:
188
+ if key not in self.data:
189
+ self.columns.append(column_for(key, overrides))
190
+ self.data[key] = [None] * size
191
+ for key, values in self.data.items():
192
+ values.append(record.get(key))
193
+
194
+ def describe(self, column: Column) -> None:
195
+ """Another title, unit or source for a column it has."""
196
+ self.columns = [column if c.key == column.key else c for c in self.columns]
197
+
198
+ def rows(self) -> Iterator[Dict[str, Any]]:
199
+ keys = list(self.data)
200
+ for values in zip(*(self.data[k] for k in keys)):
201
+ yield dict(zip(keys, values))
202
+
203
+ def to_dict(self, records: bool = True) -> Dict[str, Any]:
204
+ """records=False: its description, every column without values."""
205
+ return {
206
+ "title": self.title,
207
+ "columns": [c.to_dict() for c in self.columns],
208
+ "data": self.data if records else {key: [] for key in self.data},
209
+ }
210
+
211
+ @classmethod
212
+ def from_dict(cls, name: str, data: Mapping[str, Any]) -> "Table":
213
+ return cls(
214
+ name=name,
215
+ title=data.get("title", ""),
216
+ columns=[Column.from_dict(c) for c in data.get("columns", [])],
217
+ data={k: list(v) for k, v in (data.get("data") or {}).items()},
218
+ )
219
+
220
+
221
+ @dataclass
222
+ class DeviceUse:
223
+ """A device a measurement used, as it was configured then."""
224
+
225
+ ref: str
226
+ title: str = ""
227
+ instrument: str = ""
228
+ driver: str = ""
229
+ kind: str = ""
230
+ settings: Dict[str, Any] = field(default_factory=dict)
231
+
232
+ def to_dict(self) -> Dict[str, Any]:
233
+ return dict(self.__dict__)
234
+
235
+ @classmethod
236
+ def from_dict(cls, data: Mapping[str, Any]) -> "DeviceUse":
237
+ known = cls.__dataclass_fields__
238
+ return cls(**{k: v for k, v in data.items() if k in known})
239
+
240
+
241
+ @dataclass
242
+ class Measurement:
243
+ procedure: str
244
+ title: str = ""
245
+ id: MeasurementId = 0
246
+ status: str = RUNNING
247
+ started: str = "" # ISO time, set by whoever starts it (the runner)
248
+ finished: Optional[str] = None
249
+ error: Optional[str] = None
250
+ comment: str = ""
251
+ parameters: Dict[str, Any] = field(default_factory=dict)
252
+ devices: Dict[str, DeviceUse] = field(default_factory=dict) # by procedure slot
253
+ tables: Dict[str, Table] = field(default_factory=dict)
254
+ results: Dict[str, Any] = field(default_factory=dict)
255
+ station: Dict[str, Any] = field(default_factory=dict)
256
+ metadata: Dict[str, Any] = field(default_factory=dict)
257
+ # Its plots as PlotInfo JSON; None in files written before they were kept
258
+ plots: Optional[List[Dict[str, Any]]] = None
259
+
260
+ def table(self, name: str, title: str = "") -> Table:
261
+ if name not in self.tables:
262
+ self.tables[name] = Table(name, title)
263
+ return self.tables[name]
264
+
265
+ def append(
266
+ self,
267
+ table: str,
268
+ record: Mapping[str, Any],
269
+ overrides: Optional[Mapping[str, Column]] = None,
270
+ ) -> None:
271
+ self.table(table).append(record, overrides)
272
+
273
+ def records(self, table: str) -> List[Dict[str, Any]]:
274
+ return list(self.tables[table].rows()) if table in self.tables else []
275
+
276
+ def column(self, table: str, key: str) -> List[Any]:
277
+ return self.tables[table].column(key) if table in self.tables else []
278
+
279
+ @property
280
+ def size(self) -> int:
281
+ return sum(len(t) for t in self.tables.values())
282
+
283
+ def gather(self, records: Iterable[Tuple[str, Mapping[str, Any]]]) -> None:
284
+ """The records a records file appended (table, record), in order, but
285
+ those it has already: the n-th record of a table is skipped when the
286
+ table holds n or more."""
287
+ held = {name: len(table) for name, table in self.tables.items()}
288
+ counted: Dict[str, int] = {}
289
+ for table, record in records:
290
+ counted[table] = counted.get(table, 0) + 1
291
+ if counted[table] > held.get(table, 0):
292
+ self.append(table, record)
293
+
294
+ def finish(self, status: str, at: str, error: Optional[str] = None) -> None:
295
+ """Ended with `status` at the ISO time `at`."""
296
+ if status not in STATUSES:
297
+ raise ValueError(f"Unknown measurement status {status!r}")
298
+ self.status = status
299
+ self.error = error
300
+ self.finished = at
301
+
302
+ def to_dict(self, records: bool = True) -> Dict[str, Any]:
303
+ """records=False: its description, as the file of a running one holds
304
+ it (its records are in the records file)."""
305
+ return {
306
+ "format": FORMAT,
307
+ "version": FORMAT_VERSION,
308
+ "id": self.id,
309
+ "procedure": self.procedure,
310
+ "title": self.title,
311
+ "status": self.status,
312
+ "started": self.started,
313
+ "finished": self.finished,
314
+ "error": self.error,
315
+ "comment": self.comment,
316
+ "parameters": self.parameters,
317
+ "devices": {k: v.to_dict() for k, v in self.devices.items()},
318
+ "tables": {k: v.to_dict(records) for k, v in self.tables.items()},
319
+ "results": self.results,
320
+ "station": self.station,
321
+ "metadata": self.metadata,
322
+ "plots": self.plots,
323
+ }
324
+
325
+ @classmethod
326
+ def from_dict(cls, data: Mapping[str, Any]) -> "Measurement":
327
+ if data.get("format", FORMAT) != FORMAT:
328
+ raise ValueError(f"not a ThzDAQ measurement: {data.get('format')!r}")
329
+ return cls(
330
+ procedure=data["procedure"],
331
+ title=data.get("title", ""),
332
+ id=data.get("id") or 0,
333
+ status=data.get("status", COMPLETED),
334
+ started=data.get("started") or "",
335
+ finished=data.get("finished"),
336
+ error=data.get("error"),
337
+ comment=data.get("comment", ""),
338
+ parameters=dict(data.get("parameters") or {}),
339
+ devices={
340
+ k: DeviceUse.from_dict(v)
341
+ for k, v in (data.get("devices") or {}).items()
342
+ },
343
+ tables={
344
+ k: Table.from_dict(k, v) for k, v in (data.get("tables") or {}).items()
345
+ },
346
+ results=dict(data.get("results") or {}),
347
+ station=dict(data.get("station") or {}),
348
+ metadata=dict(data.get("metadata") or {}),
349
+ plots=data.get("plots"),
350
+ )
351
+
352
+
353
+ def dumps(value: Any, indent: Optional[int] = None) -> str:
354
+ return json.dumps(
355
+ encode_values(value), ensure_ascii=False, allow_nan=False, indent=indent
356
+ )
357
+
358
+
359
+ def loads(text: str) -> Any:
360
+ return decode_values(json.loads(text))
361
+
362
+
363
+ def write_file(path: PathLike, text: str) -> Path:
364
+ """Through a temporary file: a crash leaves the previous complete version."""
365
+ path = Path(path)
366
+ path.parent.mkdir(parents=True, exist_ok=True)
367
+ with file_access(path):
368
+ temporary = path.with_name(path.name + ".tmp")
369
+ temporary.write_text(text, encoding="utf-8")
370
+ os.replace(temporary, path)
371
+ return path
372
+
373
+
374
+ def write_measurement(measurement: Measurement, path: PathLike) -> Path:
375
+ """The whole measurement, records in it (write_file)."""
376
+ return write_file(path, dumps(measurement.to_dict(), indent=1))
377
+
378
+
379
+ def records_path(path: PathLike) -> Path:
380
+ """Where a running measurement appends its records: 000042_monitor_values_vs_time.jsonl
381
+ next to 000042_monitor_values_vs_time.json."""
382
+ return Path(path).with_suffix(RECORDS_SUFFIX)
383
+
384
+
385
+ def record_line(table: str, record: Mapping[str, Any]) -> str:
386
+ """A record as its line in a records file."""
387
+ return dumps({TABLE: table, RECORD: record}) + "\n"
388
+
389
+
390
+ def read_records(path: PathLike) -> Iterator[Tuple[str, Dict[str, Any]]]:
391
+ """The records of a records file, in order: (table, record); none when
392
+ there is none. A line cut short (the last one, by a crash while it was
393
+ written) ends them."""
394
+ try:
395
+ file = open(path, "rb")
396
+ except FileNotFoundError:
397
+ return
398
+ with file:
399
+ for line in file:
400
+ try:
401
+ found = loads(line.decode("utf-8"))
402
+ except ValueError: # JSONDecodeError, UnicodeDecodeError
403
+ return
404
+ yield found[TABLE], found[RECORD]
405
+
406
+
407
+ def read_measurement(path: PathLike) -> Measurement:
408
+ """A measurement file; one still marked running reads as interrupted (its
409
+ writer is gone or has not finished), with the records its records file
410
+ holds. ValueError when it is not one."""
411
+ try:
412
+ data = loads(read_bytes(Path(path)).decode("utf-8"))
413
+ measurement = Measurement.from_dict(data)
414
+ if measurement.status == RUNNING:
415
+ measurement.status = INTERRUPTED
416
+ measurement.gather(read_records(records_path(path)))
417
+ except (OSError, json.JSONDecodeError) as e:
418
+ raise ValueError(f"{path}: {e}") from e
419
+ measurement.metadata["path"] = str(path)
420
+ return measurement
421
+
422
+
423
+ def export_csv(measurement: Measurement, table: str, path: PathLike) -> Path:
424
+ """One table as CSV; the header row carries titles with units."""
425
+ data = measurement.tables[table]
426
+ path = Path(path)
427
+ with open(path, "w", newline="", encoding="utf-8") as file:
428
+ writer = csv.writer(file)
429
+ writer.writerow([c.label for c in data.columns])
430
+ keys = [c.key for c in data.columns]
431
+ for row in data.rows():
432
+ writer.writerow([row.get(key) for key in keys])
433
+ return path
434
+
435
+
436
+ def file_id(path: Path) -> Optional[int]:
437
+ """000042_sis_current_vs_voltage.json -> 42; None for files named otherwise."""
438
+ head = path.name.split("_", 1)[0]
439
+ return int(head) if head.isdigit() else None
440
+
441
+
442
+ class MeasurementFolder:
443
+ """A data folder of measurement files: <root>/<YYYY-MM-DD>/<id>_<procedure>.json"""
444
+
445
+ def __init__(self, root: PathLike):
446
+ self.root = Path(root)
447
+
448
+ def paths(self) -> List[Path]:
449
+ return sorted(self.root.glob("*/*.json"))
450
+
451
+ def load(self, path: PathLike) -> Measurement:
452
+ return read_measurement(path)
453
+
454
+ def __iter__(self) -> Iterator[Measurement]:
455
+ for path in self.paths():
456
+ try:
457
+ yield read_measurement(path)
458
+ except ValueError:
459
+ continue