diff --git a/docs/adaptive_scans.md b/docs/adaptive_scans.md index 0ef14b8..49738c1 100644 --- a/docs/adaptive_scans.md +++ b/docs/adaptive_scans.md @@ -224,3 +224,11 @@ are not affected, apart from three small changes that apply to every scan: queued. For a fixed scan that is the same number as before; - `CounterValue` and `BsStreamCounter` gained a `step_feedback()` method. Nothing calls it unless an adaptive scan does. + +```{admonition} Did you know? +:class: tip + +`%ei how do I run an adaptive scan on the delay?` answers with your +session's device names, from these docs and the scans people actually ran +({doc}`ask_eco`). +``` diff --git a/docs/api.rst b/docs/api.rst index 3588473..0baea61 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -80,6 +80,15 @@ Delta Tau / PowerBrick configs .. automodule:: eco.motion.deltatau_config.verify :members: +.. automodule:: eco.motion.deltatau_config.module_ioc + :members: + +PowerBrick parameters +--------------------- + +.. automodule:: eco.devices_general.powerbrick + :members: PowerBrickChannelPars, unlock, lock, gateway_open, axis_from_out, is_powerbrick_motor, ioc_host + Direct motor drivers (EPICS-independent) ---------------------------------------- @@ -88,3 +97,26 @@ Direct motor drivers (EPICS-independent) .. automodule:: eco.devices_general.schneider_mcode :members: + +Simulated scan targets +---------------------- + +.. automodule:: eco.devices_general.simulated_signals + :members: SimulatedSignals, SimAxis, SimDetector, SimBeam + +Ask eco +------- + +.. autofunction:: eco.ei.ask + +.. autofunction:: eco.ei.assistant + +.. autofunction:: eco.ei.time_window + +.. autofunction:: eco.ei.load_config + +.. automodule:: eco.logs_elog + :members: Reader, update, ca_bundle, parse_export + +.. automodule:: eco.ei_wait + :members: pick, Waiting, in_terminal diff --git a/docs/ask_eco.md b/docs/ask_eco.md index c04024e..9f1b12a 100644 --- a/docs/ask_eco.md +++ b/docs/ask_eco.md @@ -311,3 +311,12 @@ adding a key, `%ei --key` picks it up without restarting. log excerpts (SciLog posts and elog entries included), and the list of namespace names go to the model server. The server is PSI's own, but think before indexing notes you would not paste into it yourself. + +```{admonition} Did you know? +:class: tip + +`%ei what happened to the machine since yesterday?` goes through the +machine's elog entries of that span, in order, each linked to its entry. +And now and then something other than the spinner keeps you company while +the model thinks. +``` diff --git a/docs/command_history.md b/docs/command_history.md index e70145e..3504b07 100644 --- a/docs/command_history.md +++ b/docs/command_history.md @@ -112,3 +112,10 @@ from eco import ipymagic ipymagic.start(bernina) ipymagic.stop() ``` + +```{admonition} Did you know? +:class: tip + +`%ei --open N` shows a command an answer cites among the commands typed +before and after it, with what came back ({doc}`ask_eco`). +``` diff --git a/docs/did_you_know/2026-10-30-ei-notes-from-pictures.md b/docs/did_you_know/2026-10-30-ei-notes-from-pictures.md new file mode 100644 index 0000000..c73890a --- /dev/null +++ b/docs/did_you_know/2026-10-30-ei-notes-from-pictures.md @@ -0,0 +1,20 @@ +--- +added: 2026-10-30 +tags: [help, logbook] +details: ask_eco +--- + +# Photograph the shift notes, and %ei finds them later + +With a model connected, `%ei --scan` reads photos, scanned PDFs and +whiteboard pictures once, handwriting included, and adds the text to what +`%ei` searches, dated by the date written on the note. `%ei --webcam` takes +the picture for you, and `%ei --scan-image img` reads a camera frame from the +session. + +```python +%ei --scan ~/photos/shift_2026-10-14/ +%ei what did we write about the tapedrive trigger? +``` + +More: {doc}`../ask_eco` diff --git a/docs/did_you_know/2026-10-30-item-menu.md b/docs/did_you_know/2026-10-30-item-menu.md new file mode 100644 index 0000000..bf42deb --- /dev/null +++ b/docs/did_you_know/2026-10-30-item-menu.md @@ -0,0 +1,21 @@ +--- +added: 2026-10-30 +tags: [ui, widgets] +details: widget_views +--- + +# Every row of a property grid has a ⋯ menu + +Each Adjustable, Detector or sub-assembly row of a property grid (eco +desktop, `.widget()`, Jupyter) ends in **⋯** (in Qt also a right-click on the +name). It offers what that item supports: its other views, a live strip +chart, the archiver history from 10 minutes to 7 days, indicator gadgets, its +memories, details (channels, unit, limits), and in Qt copying the name or PV +names and **Find IOC**. The setpoint entry now sits right next to the +readback. + +```python +mono.widget() # then ⋯ on the theta row -> archiver history -> 1 day +``` + +More: {doc}`../widget_views` diff --git a/docs/did_you_know/2026-10-30-recspace.md b/docs/did_you_know/2026-10-30-recspace.md new file mode 100644 index 0000000..994b07b --- /dev/null +++ b/docs/did_you_know/2026-10-30-recspace.md @@ -0,0 +1,25 @@ +--- +added: 2026-10-30 +tags: [diffraction, recspace] +details: recspace +--- + +# Keep a second reflection in Bragg while you move in hkl + +`recspace` (on `xrd`, `gps`, `rob` and in the namespace) is the +hklforge-based successor of the `diffcalc` objects, with the same interface. +It returns every solution exactly, can keep a second reflection in Bragg +condition while `hkl` moves, and shows a clickable 3D view of each solution. +It runs alongside `diffcalc` with its own files, so trying it changes +nothing there. + +```python +rs = xrd.recspace +rs.constraints.chi(None) +rs.constraints.h2([2, 2, 0]) # keep (220) in Bragg too +rs.si.hkl.mv([1, 1, 1]) # (111) and (220) both in Bragg +``` + +`rs.set_constraints()` lists the stored Bernina setups. + +More: {doc}`../recspace` diff --git a/docs/did_you_know/2026-10-31-ei-scilog.md b/docs/did_you_know/2026-10-31-ei-scilog.md new file mode 100644 index 0000000..0ec6b27 --- /dev/null +++ b/docs/did_you_know/2026-10-31-ei-scilog.md @@ -0,0 +1,20 @@ +--- +added: 2026-10-31 +tags: [help, logbook, scilog] +details: ask_eco +--- + +# %ei knows what was written in SciLog + +`%ei` searches Bernina's SciLog logbooks along with the command history +and the docs, indexed locally before the first question (~20 s once, then +less than a second). With a personal token it reads every logbook your PSI +groups can read; without one, and always on gac-bernina, it reads as the +beamline account. Either way it reads only what that account can read *now*. + +```python +%ei --scilog-token # who reads SciLog here +%ei what trigger settings did we use for the tapedrive? +``` + +More: {doc}`../ask_eco` diff --git a/docs/did_you_know/2026-11-02-adaptive-scans.md b/docs/did_you_know/2026-11-02-adaptive-scans.md new file mode 100644 index 0000000..706c360 --- /dev/null +++ b/docs/did_you_know/2026-11-02-adaptive-scans.md @@ -0,0 +1,19 @@ +--- +added: 2026-11-02 +tags: [scans] +details: adaptive_scans +--- + +# Let the scan decide where to measure next + +`scans.adaptive_scan` starts with a coarse survey and then puts the +next points where the live data say they help most: on the flanks of a peak, +along an edge, across an oscillation. It is an ordinary step scan recorded by +the DAQ; only the choice of the next point is made while it runs. + +```python +scans.adaptive_scan([sim.peak.x, -2, 3, 0.02], N_pulses=0.2, + feedback=sim.peak.signal, max_points=40) +``` + +More: {doc}`../adaptive_scans` diff --git a/docs/did_you_know/2026-11-02-detectors-as-counters.md b/docs/did_you_know/2026-11-02-detectors-as-counters.md new file mode 100644 index 0000000..ebffc1f --- /dev/null +++ b/docs/did_you_know/2026-11-02-detectors-as-counters.md @@ -0,0 +1,19 @@ +--- +added: 2026-11-02 +tags: [scans, counters] +details: scanning +--- + +# Give a scan detectors, not counters + +`counters=` takes detectors directly: a bs detector gets its live bs +counter, kept on the detector and reused by every scan, and all other +detectors share one EPICS monitor counter. The first counter sets the +exposure, and the others collect for exactly its window: the same pulses, or +the same time. + +```python +scans.ascan(mot, 0, 1, 20, 100, counters=[daq, mon_opt.intensity, diode]) +``` + +More: {doc}`../scanning` diff --git a/docs/did_you_know/2026-11-02-eco-web-camera.md b/docs/did_you_know/2026-11-02-eco-web-camera.md new file mode 100644 index 0000000..52bcd24 --- /dev/null +++ b/docs/did_you_know/2026-11-02-eco-web-camera.md @@ -0,0 +1,14 @@ +--- +added: 2026-11-02 +tags: [ui, web, cameras] +details: web_app +--- + +# Steer cam_west from your phone + +In the web app, a network PTZ camera (`cam_west` and co.) has a live +view: switch on **Control**, then tap to center, drag a box to zoom, or use +zoom ±, wide and home. All viewers share one connection to the camera, and a +slow tunnel drops frames instead of lagging behind. + +More: {doc}`../web_app` diff --git a/docs/did_you_know/2026-11-02-eco-web.md b/docs/did_you_know/2026-11-02-eco-web.md new file mode 100644 index 0000000..39ed234 --- /dev/null +++ b/docs/did_you_know/2026-11-02-eco-web.md @@ -0,0 +1,20 @@ +--- +added: 2026-11-02 +tags: [ui, web, phone] +details: web_app +--- + +# eco on your phone + +`eco web` serves the running session to a browser, made for phones and +tablets: the namespace, live values, moves, tweak and jog, pinned strip +charts, schematic panels, task queues and the cameras. It is the same session +as the terminal, read-only unless started with writes, and reached through +an SSH tunnel. + +```python +eco.start_web() # from a running session; prints the link +eco.start_web(writes=True) # moves allowed from the browser +``` + +More: {doc}`../web_app` diff --git a/docs/did_you_know/2026-11-02-ei-machine-elog.md b/docs/did_you_know/2026-11-02-ei-machine-elog.md new file mode 100644 index 0000000..69a9259 --- /dev/null +++ b/docs/did_you_know/2026-11-02-ei-machine-elog.md @@ -0,0 +1,19 @@ +--- +added: 2026-11-02 +tags: [help, logbook, machine] +details: ask_eco +--- + +# Ask what happened to the machine since yesterday + +`%ei` also reads the machine's elog (SwissFEL commissioning and +Diagnostics on elog-gfa.psi.ch). A question that names a time span ("last +day", "since Monday", "last night") gets that span's logbook entries in order, +and the answer goes through them with times, each linked to its entry. + +```python +%ei what happened to the machine over the last day or so? +%ei any Athos problems since Friday? +``` + +More: {doc}`../ask_eco` diff --git a/docs/did_you_know/2026-11-02-ei-sources.md b/docs/did_you_know/2026-11-02-ei-sources.md new file mode 100644 index 0000000..2928e30 --- /dev/null +++ b/docs/did_you_know/2026-11-02-ei-sources.md @@ -0,0 +1,20 @@ +--- +added: 2026-11-02 +tags: [help, history] +details: ask_eco +--- + +# Jump from an answer to where it came from + +Every `%ei` answer ends with its numbered sources, each with its +location: file and line of a command or doc section, the elog entry, the +SciLog logbook. In gnome-terminal they are links (Ctrl+click). +`%ei --open N` shows source N in its context: the commands typed before and +after it with what came back, or a logbook post between its neighbours. + +```python +%ei how did we align the mono last time? +%ei --open 2 +``` + +More: {doc}`../ask_eco` diff --git a/docs/did_you_know/2026-11-02-ei-wait-animations.md b/docs/did_you_know/2026-11-02-ei-wait-animations.md new file mode 100644 index 0000000..4062e05 --- /dev/null +++ b/docs/did_you_know/2026-11-02-ei-wait-animations.md @@ -0,0 +1,20 @@ +--- +added: 2026-11-02 +tags: [help, fun] +details: ask_eco +--- + +# Sometimes a chicken keeps you company while %ei thinks + +While the model is working on an answer, the terminal shows a spinner +with the seconds waited. About one question in four gets a small animation +instead, chosen at random, and there are five. Which ones? Ask a few +questions and see. + +```python +%ei which came first, the chicken or the egg? +``` + +`"wait_animations"` in `~/.eco/ei.json` sets how often (0 for never). + +More: {doc}`../ask_eco` diff --git a/docs/did_you_know/2026-11-02-module-ioc.md b/docs/did_you_know/2026-11-02-module-ioc.md new file mode 100644 index 0000000..0364482 --- /dev/null +++ b/docs/did_you_know/2026-11-02-module-ioc.md @@ -0,0 +1,19 @@ +--- +added: 2026-11-02 +tags: [motors, diffractometer, powerbrick] +details: powerbrick_parameters +--- + +# Load the Kappa onto the diffractometer from eco + +`xrd.module_ioc` and `gps.module_ioc` load the Kappa or the SampleStage +configuration onto the diffractometer's module PowerBrick, with the controls +group's own script. eco asks for confirmation, refuses while a module motor +moves, and checks afterwards that the motor records came up. + +```python +xrd.module_ioc # which configuration is loaded +xrd.module_ioc.load("kappa") +``` + +More: {doc}`../powerbrick_parameters` diff --git a/docs/did_you_know/2026-11-02-powerbrick-parameters.md b/docs/did_you_know/2026-11-02-powerbrick-parameters.md new file mode 100644 index 0000000..0d9ff4b --- /dev/null +++ b/docs/did_you_know/2026-11-02-powerbrick-parameters.md @@ -0,0 +1,20 @@ +--- +added: 2026-11-02 +tags: [motors, powerbrick] +details: powerbrick_parameters +--- + +# See the PowerBrick's own view of a motor + +Motors driven by a PowerBrick now have `cnf_pb`: the controller's +parameters for that axis (amplifier fault, following error, closed loop, +in-position band, ...), read in one batched request per controller and only +when first needed. Controllers behind sf-gw stay locked (🔑) until you log in +with your own account. + +```python +mono.theta.cnf_pb +kbver.bend1.cnf_pb.unlock() +``` + +More: {doc}`../powerbrick_parameters` diff --git a/docs/did_you_know/2026-11-02-scan-timing.md b/docs/did_you_know/2026-11-02-scan-timing.md new file mode 100644 index 0000000..19e0a15 --- /dev/null +++ b/docs/did_you_know/2026-11-02-scan-timing.md @@ -0,0 +1,19 @@ +--- +added: 2026-11-02 +tags: [scans] +details: scanning +--- + +# Every scan tells you where its time went + +Each step line ends with the share of time spent acquiring, moving, +settling and in callbacks, and the scan ends with a summary. If less than +half of the time is spent acquiring, eco says once what takes the rest. + +``` +Step 12 of 40 x @ 0.620 ; Ctrs daq done. | acq 61% move 30% settle 0% cb 9% +``` + +The numbers are in `scan.timing`. + +More: {doc}`../scanning` diff --git a/docs/did_you_know/2026-11-02-simulated-targets.md b/docs/did_you_know/2026-11-02-simulated-targets.md new file mode 100644 index 0000000..3ca4c11 --- /dev/null +++ b/docs/did_you_know/2026-11-02-simulated-targets.md @@ -0,0 +1,19 @@ +--- +added: 2026-11-02 +tags: [scans, testing] +details: simulated_targets +--- + +# Practise scans on a peak that isn't there + +`sim` in the namespace has simulated peaks, edges, a 2-D peak and +pump-probe oscillations, with motors and detectors that behave like a +stepper, a piezo, a diode or a lock-in: settling, backlash, lag, noise, +drift. Move the peak while the scan runs to see how it copes. + +```python +scans.ascan(sim.peak.x, -2, 2, 40, 0.2, counters=[sim.peak.signal]) +sim.peak.center.mv(1.2) +``` + +More: {doc}`../simulated_targets` diff --git a/docs/index.rst b/docs/index.rst index d901ee1..3b800fe 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,6 +31,13 @@ scientific Python libraries. Short tips on recent features: one call, what it gains you, and where to read more. + .. grid-item-card:: :octicon:`sparkle-fill` What's new + :link: whats_new + :link-type: doc + + Recent changes and new features, and what to watch out for when + you update. + .. grid-item-card:: :octicon:`light-bulb` Concepts :link: concepts :link-type: doc @@ -45,6 +52,27 @@ scientific Python libraries. Queue scans and commands with ``%queue``: each one test-run when queued, run one after another while the prompt stays free. + .. grid-item-card:: :octicon:`comment-discussion` Ask eco + :link: ask_eco + :link-type: doc + + ``%ei how do I ...?`` answers from the docs, the command history, + SciLog and the machine elog, with your session's devices. + + .. grid-item-card:: :octicon:`goal` Adaptive scans + :link: adaptive_scans + :link-type: doc + + Scans that put the next points where the live data say they help + most. Try them on the simulated targets in ``sim``. + + .. grid-item-card:: :octicon:`device-mobile` eco on a phone + :link: web_app + :link-type: doc + + ``eco web``: the running session in a browser, with live values, + moves, queues and the cameras. + .. grid-item-card:: :octicon:`pulse` Listening monitor :link: examples/listening_monitor :link-type: doc @@ -78,6 +106,13 @@ scientific Python libraries. Servo parameters, their auto-assigned ratios, and how to tune them. + .. grid-item-card:: :octicon:`key` PowerBrick parameters + :link: powerbrick_parameters + :link-type: doc + + The controller's own view of a motor (``cnf_pb``), and loading the + Kappa or SampleStage onto the diffractometer. + .. grid-item-card:: :octicon:`plug` Direct motor drivers :link: examples/direct_motor_drivers :link-type: doc @@ -101,6 +136,13 @@ scientific Python libraries. viewer widgets, aligned left/center/right, on either front end. +.. admonition:: Did you know? + :class: tip + + ``%ei what happened to the machine since yesterday?`` reads the SwissFEL + commissioning elog for you and answers with the entries in order. More + tips like this: :doc:`did_you_know/index`, or ``features()`` in a session. + .. toctree:: :maxdepth: 2 :caption: Getting started @@ -108,6 +150,7 @@ scientific Python libraries. installation launching + whats_new concepts did_you_know/index @@ -118,6 +161,7 @@ scientific Python libraries. scanning adaptive_scans + simulated_targets queues tweak command_history @@ -144,6 +188,7 @@ scientific Python libraries. :hidden: deltatau_servo + powerbrick_parameters channel_access .. toctree:: diff --git a/docs/launching.md b/docs/launching.md index d8f439a..5257bb3 100644 --- a/docs/launching.md +++ b/docs/launching.md @@ -101,6 +101,13 @@ timeline (see {doc}`command_history`). in one spot, the same as dropping one panel's title bar on another's. Drag a tab off the tab bar to split it out again. +```{admonition} Did you know? +:class: tip + +`features()` in a session opens a small window with a random tip on a +recent feature, and {doc}`whats_new` lists what changed lately. +``` + ## See also - {doc}`command_history`: every one of these consoles logs its input and diff --git a/docs/powerbrick_parameters.md b/docs/powerbrick_parameters.md new file mode 100644 index 0000000..2166747 --- /dev/null +++ b/docs/powerbrick_parameters.md @@ -0,0 +1,102 @@ +# PowerBrick parameters and module loading + +Most Bernina motors are driven by Delta Tau PowerBrick controllers. The +EPICS motor record shows position, limits and speed. The controller has much +more: amplifier and following-error faults, closed-loop state, the in-position +band, encoder loss. eco shows those controller parameters next to the motor +record, as `cnf_pb`, and can load the diffractometers' exchangeable modules +(Kappa, SampleStage) onto their PowerBrick. + +## The parameters of a motor: `cnf_pb` + +```python +mono.theta.cnf_pb # status of the axis on its controller +mono.theta.cnf_pb.Motor_AmpFault() # one parameter (read) +mono.theta.cnf_pb.Motor_InPosBand.mv(0.5) # a writable one (gpascii Motor[n].InPosBand) +``` + +The names are the controller's gpascii names, with the axis number left out +and `.` written as `_`: `Motor[6].AmpFault` becomes `Motor_AmpFault`. They +appear in the motor's status like every other component. + +Which motors have it: a motor record built with `pb_conf="auto"` gets +`cnf_pb` only if the record is really driven by a PowerBrick. That is the +case if it is served by a `*-CPPM-*` IOC, or, behind the channel-access +gateway, if its OUT link names the PPMAC port. The motor records of the mono, +the offset mirrors, the slits, the KB mirrors, the spectrometer and the +diffractometers' flight-tube slits use `pb_conf="auto"`. Motors on other +controllers (MForce, ...) simply have no `cnf_pb`. + +What happens behind it: + +- **Nothing on startup.** Building `cnf_pb` contacts nothing. The first read, + normally the first `status()`, finds the controller and the axis and opens + the SSH session to the controller. +- **The axis is the one the IOC drives**: it is read from the motor record's + OUT link (`@asyn(PPMAC1,6)` → axis 6), not from a hardcoded table. +- **The controller** is the record's channel-access server, or, when channel + access only shows a gateway, the IOC host from iocinfo.psi.ch. +- **One request per controller.** All parameters of all axes of a controller + are read in one batched request and kept for 1 s, so a `status()` of a + device with ten PowerBrick motors costs one round trip per controller. + A write clears that cache. +- **An offline record fails fast**: after a failed lookup, reads fail at once + for 30 s instead of waiting each time. + +## Controllers behind sf-gw: locked until you log in + +Some controllers (the KB mirrors' `SAROP21-CPPM-*`, on the machine network) +can only be reached through the `sf-gw` jump host. Their parameters are for +development, so eco does not read them by default: their status shows a +🔑 key and nothing else. + +```python +kbver.bend1.cnf_pb # 🔑 locked (sf-gw), .unlock() +kbver.bend1.cnf_pb.unlock() # log into sf-gw with *your* account +kbver.bend1.cnf_pb.lock() # close it again +``` + +`unlock()` logs into sf-gw as you. ssh asks for the password itself, so eco +never sees it, and with a Kerberos ticket it doesn't ask at all. On the shared +gac-bernina account it asks for your PSI account name first. The login stays +open as a private connection through which the PowerBrick sessions are +tunnelled, and it closes with `lock()`, at the end of the session, or an hour +after its last use. One `unlock()` opens every controller behind sf-gw. + +## Loading a module onto the diffractometer's PowerBrick + +The Kappa and the SampleStage are run by one dedicated PowerBrick per +diffractometer (`SARES21-CPPM-XRD1` for `xrd`, `SARES22-CPPM-GPS1` for `gps`). +It boots without a motor configuration on purpose, since a wrong one can +destroy motors. `module_ioc` loads one: + +```python +xrd.module_ioc # host, and which configuration is loaded +xrd.module_ioc.load("kappa") # asks for confirmation, copies, restarts the IOC (~30 s) +xrd.module_ioc.load("stage") +xrd.module_ioc.list_motors() # motor records of the running IOC +xrd.module_ioc.open_loop(xrd.eta_kap, xrd.kappa) # these motors without encoder +``` + +It runs the controls group's own `ConfigMotorIOC.py`, so hosts, +configurations and the open-loop table stay the ones the controls group +maintains. eco adds: + +- a confirmation with the script's safety password before anything is changed; +- eco's write gates for the module's motors (access control, task-queue + claims); +- a refusal while one of the module's motors is moving; +- a check over channel access afterwards that the configuration's motor + records came up. + +See also: {doc}`deltatau_servo` for the servo parameters and +{doc}`examples/deltatau_config` for reading, editing and applying whole +controller configurations. + +```{admonition} Did you know? +:class: tip + +Once a controller's parameters have been read, the whole controller is +read in one request: a `status()` of the mono costs one round trip, not one +per motor. +``` diff --git a/docs/queues.md b/docs/queues.md index b5f0a38..099b7b3 100644 --- a/docs/queues.md +++ b/docs/queues.md @@ -164,3 +164,10 @@ when the queue is muted. motor already moving keeps moving, as after Ctrl-C. - Claims cover moves that go through eco (every `mv`/`set_target_value`). A `caput` from outside eco is not stopped. + +```{admonition} Did you know? +:class: tip + +The web app shows the queues too: what runs and what waits, the +progress of a scan, its output, and pause/resume/stop ({doc}`web_app`). +``` diff --git a/docs/recspace.md b/docs/recspace.md index 4d7d4bf..1dc5b26 100644 --- a/docs/recspace.md +++ b/docs/recspace.md @@ -272,3 +272,10 @@ hexagonal, monoclinic, triclinic). Result on those (2026-10-30, 1600 cases): reflections in Bragg to 2.4e-14 (relative). - Time per solve: diffcalc 1.5 ms, `recspace` 3.1 ms (mostly numpy overhead on 3-vectors inside hklforge; fast enough for interactive use). + +```{admonition} Did you know? +:class: tip + +`xrd.recspace.set_constraints()` without arguments lists the stored +Bernina setups; one name sets all of a setup's constraints at once. +``` diff --git a/docs/scanning.md b/docs/scanning.md index e707e5e..052e3a5 100644 --- a/docs/scanning.md +++ b/docs/scanning.md @@ -161,6 +161,14 @@ less than half of the time goes into acquiring, a warning names where it goes, once per scan. Thresholds: `eco.acquisition.scan_timing`. The numbers are in `scan.timing`. +```{admonition} Did you know? +:class: tip + +You can try any of these scans without a beamline: `sim.peak.x` and +`sim.peak.signal` are a motor and a detector with a peak between them +({doc}`simulated_targets`). Move `sim.peak.center` while the scan runs. +``` + ## See also - {doc}`adaptive_scans`: scans that choose their next points from the live diff --git a/docs/simulated_targets.md b/docs/simulated_targets.md new file mode 100644 index 0000000..f61a42f --- /dev/null +++ b/docs/simulated_targets.md @@ -0,0 +1,87 @@ +# Simulated scan targets: `sim` + +To try a scan, develop a scan feature or test an adaptive scan, you need +something to scan that gives a known answer. `sim` in the bernina namespace +holds in-memory motors and detectors with a signal behind them: no EPICS, no +beam, no hardware. Its motors and detectors behave like real ones, with move +overhead, settling, backlash, readback noise, slow update rates, lag and drift. +Children are built on first use, like everything else in the namespace. + +```python +sim.peak.signal.scans.ascan(sim.peak.x, -2, 2, 41, 0.2) # 41 points, 0.2 s each +scans.ascan(sim.peak.x, -2, 2, 40, 0.2, counters=[sim.peak.signal]) # the same, through scans +``` + +The second form works because scans take detectors as counters (see +{doc}`scanning`): `counters=` replaces the default counters, so the DAQ is +not involved. + +## The signals + +| Component | Axis | Signal | +|---|---|---| +| `sim.step` | `x` | an edge (error function): position and width | +| `sim.peak` | `x` | a Gaussian peak on a background | +| `sim.gradient` | `x` | mostly linear, slightly curved | +| `sim.peak2d` | `x`, `y` | a tilted, asymmetric 2-D Gaussian | +| `sim.oscillation` | `delay` | pump-probe: a step at t0 plus one damped oscillation | +| `sim.oscillations` | `delay` | the same with three overlaid modes | + +Each one has its axes and a `signal` detector. A shared `sim.beam` multiplies +every signal by the same shot-to-shot intensity, which `sim.beam.i0` reads, +so normalising `signal / i0` works as on real data. + +The signal's parameters (`sim.peak.center`, `.fwhm`, `.amplitude`, +`.background`, ...) are ordinary adjustables, read when each value is +produced. Move them while a scan runs to see how a scan (or an adaptive +strategy) copes with a peak that moves: + +```python +sim.peak.center.mv(1.2) +sim.peak.truth([0.5, 1.0, 1.2]) # the noise-free model at these positions +``` + +## Behaving like a real device + +Axes and detectors carry timing and noise parameters, with presets for typical +devices: + +| Axis presets | Detector presets | +|---|---| +| `ideal`, `stepper`, `piezo`, `delay_stage`, `goniometer`, `electronic_delay` | `ideal`, `diode`, `epics_slow`, `electrometer`, `lockin`, `camera_roi`, `thermal` | + +```python +sim.peak.x.apply_preset("stepper") # one axis +sim.peak.signal.apply_preset("electrometer") # one detector +sim.peak.apply_presets(axis="piezo", detector="lockin") +``` + +or for everything at once, when building your own: + +```python +from eco.devices_general.simulated_signals import SimulatedSignals +sim2 = SimulatedSignals(axis="stepper", detector="diode", delay_axis="delay_stage") +``` + +Axis parameters: `overhead` (latency before motion starts), `speed`, +`settle_time`, `backlash` (on reversal the load stays put until the play is +taken up; the readback shows the motor side), `readback_noise`, and `jitter` +(of the physical position, as for pump-probe timing jitter). + +Detector parameters: `update_rate` (values per second, held in between), +`response_time` (a first-order low-pass, as for an electrometer or lock-in), +`dead_time` (the value describes the state that long ago), `read_latency` +(each read blocks), `noise`, `noise_rel` (relative, shot-noise-like) and +`drift` (signal units per hour). + +The noise is reproducible within a detector tick: reading twice in the same +tick gives the same value, as for a real record that has not updated yet. + +See also: {doc}`adaptive_scans`, which uses `sim` for its examples. + +```{admonition} Did you know? +:class: tip + +`sim.peak.truth(x)` is the noise-free model: compare it with what a +scan or an adaptive strategy found ({doc}`adaptive_scans`). +``` diff --git a/docs/web_app.md b/docs/web_app.md index 8a65c82..876bc15 100644 --- a/docs/web_app.md +++ b/docs/web_app.md @@ -93,3 +93,11 @@ on a worker thread: the write-access gate, a running queue's claims jog writes the motor record's jog fields directly, so the web app checks the access gate and queue claims itself before it starts one. Writes are off unless asked for, and the session logs each one with the client that sent it. + +```{admonition} Did you know? +:class: tip + +The same ⋯ menu exists in the desktop and Jupyter property grids, with +the archiver history of the item from 10 minutes to 7 days +({doc}`widget_views`). +``` diff --git a/docs/whats_new.md b/docs/whats_new.md new file mode 100644 index 0000000..a59bd5c --- /dev/null +++ b/docs/whats_new.md @@ -0,0 +1,116 @@ +# What's new + +What changed in eco recently, newest first, with what to watch out for when +you update. For one feature at a time, with the main call, see +{doc}`did_you_know/index`, or `features()` in a session. + +## Updating a checkout + +```bash +git pull # in your checkout +pip install -e . --no-deps # only if you install it; new dependencies below +``` + +```{admonition} Upgrade notes for 25 October to 2 November 2026 +:class: important + +- **New dependency: `hklforge`** (core, for `recspace`). It is in the + Bernina Python environments; a separate installation needs + `pip install hklforge`. +- **New optional extra `eco-suite[web]`** (tornado) for `eco web`. Without + it everything else works. +- **Adaptive scans need escape-fel 0.2.17 or newer.** Nothing else changes + with an older escape. +- **`N_pulses` is now the exposure of the first counter.** The other + counters of a scan follow its window (same pulses, same time) instead of + each acquiring `N_pulses` on their own. With the default counters (the DAQ + alone) nothing changes. See {doc}`scanning`. +- **A bs-stream counter bins only during its scans.** Before, it kept binning + every shot between scans. Its per-scan data now live on the scan, so one + counter can serve concurrent scans. +- **`recspace` works in the SwissFEL/Bernina frame** (z+ along the beam, y+ + up). Crystals stored before are turned once when they are first loaded, and + directions are given as the crystal lies with all angles at 0. `diffcalc` + is not affected. +- **`%ei` indexes SciLog and the machine elog before its first question**: + about 20 s and 30 s, once per account; the index in `~/.eco` grows by about + 50 MB. `"scilog_default": null` and `"elog_logbooks": []` in + `~/.eco/ei.json` switch them off. +- **Status of PowerBrick motors** gains a `cnf_pb` entry, read only when + shown; motors behind sf-gw show a 🔑 key instead. +``` + +## 2 November 2026 + +**Asking eco (`%ei`)** — {doc}`ask_eco` + +- The machine's elog: SwissFEL commissioning and Diagnostics are searched, + and questions about a time span ("what happened since yesterday?") get that + span's logbook entries in order. +- SciLog is searched by default: Bernina's logbooks, as you with a personal + token or as the beamline account, only what that account can read now. +- Every answer lists its sources with their locations, clickable in the + terminal; `%ei --open N` shows one in its context. +- Better ranking: items containing more of the question come first. +- A spinner while the model thinks, and now and then something else. + +**Scans** — {doc}`scanning`, {doc}`adaptive_scans` + +- Adaptive scans: `scans.adaptive_scan(...)` chooses the next points from + the live data. +- Every scan shows where its time goes (acquire, move, settle, callbacks). +- Detectors as counters: `counters=[daq, mon_opt.intensity, diode]`. +- The first counter sets the exposure; the others follow its window. +- Simulated scan targets: `sim`, with realistic motor and detector behaviour + ({doc}`simulated_targets`). + +**eco web** — {doc}`web_app` + +- A front-end for phones and tablets: `eco web -s bernina`, + `eco.start_web()`. Motor records with jog, task queues with progress and + controls, and the live view of the PTZ cameras. + +**Motors and diffractometers** + +- PowerBrick parameters (`cnf_pb`) on every PowerBrick-driven motor record + of mono, mirrors, slits, KB and spectrometer; controllers behind sf-gw open + with your own login ({doc}`powerbrick_parameters`). +- `xrd.module_ioc` / `gps.module_ioc` load the Kappa or SampleStage onto the + module PowerBrick ({doc}`powerbrick_parameters`). +- `recspace`: the Bernina frame, crystal setup by directions at all angles 0, + and `set_constraints()` with the stored Bernina setups ({doc}`recspace`). + +## 30 and 31 October 2026 + +- `%ei`, ask eco: answers from the docs, eco's API, the command history, + escape and your namespace; works without a model key as a search; notes + from photos, PDFs and a webcam ({doc}`ask_eco`). +- `recspace`, the hklforge-based successor of the `diffcalc` objects, runs + alongside them ({doc}`recspace`). +- Property grids: the setpoint next to the readback, and a **⋯** menu on + every row with strip charts, archiver history, gadgets, memories and + details ({doc}`widget_views`). +- Scan launcher: `scans.launcher()`, also **Tools → Scan Launcher** in eco + desktop ({doc}`queues`). +- Log viewer: opens at once also on long histories (last 30 days by + default), in its own process from eco desktop ({doc}`command_history`). +- eco desktop no longer crashes when its window is destroyed. + +## 25 October 2026 + +- Qt windows stay live while a command runs: camera viewers, plots and eco + desktop keep updating during `umv`, scans and `sleep` ({doc}`live_gui`). +- Named task queues and the `%queue` magic, with every task test-run when + it is queued ({doc}`queues`). +- Property grids never block: moves and reads run off the GUI thread + ({doc}`widget_views`). +- `features()` and `docs()` in the session; "Did you know?" tips. +- Archiver: long time ranges are binned on the server (`max_bins`). +- Stream plots open in named windows that refresh in place. + +```{admonition} Did you know? +:class: tip + +`features()` opens a small window with a random tip like the ones linked +above, and **Next** gives another. Without a display it prints one. +``` diff --git a/docs/widget_views.md b/docs/widget_views.md index f0ddd75..7796449 100644 --- a/docs/widget_views.md +++ b/docs/widget_views.md @@ -174,3 +174,10 @@ into `eco.widgets.display_qt`'s property grid. Reach for this one if the simple pair's two approximations (no needle, no rolling line) actually matter for a given panel; otherwise the matched simple pair above is the current default recommendation for new work, on either backend. + +```{admonition} Did you know? +:class: tip + +`eco.start_web()` shows the same rows on your phone, with live values, +moves and pinned strip charts ({doc}`web_app`). +```