This release is a pre-release and may not be stable for production use.
dls_motor_scanning
Tools for characterising the motion performance of EPICS motors.
Four commands are provided:
scandrives a motor through a range in fixed steps, recording the position actually reached and the time each move took, then reports the positioning error and move time as statistics, a data file and a plot.calibratefits a 5th order polynomial that converts an unscaled feedback device, such as a potentiometer read as raw ADC counts, into engineering units, and emits it as an EPICS calc record and an Excel formula.characterise-feedbackscans a motor likescan, and reports how far another PV, such as the calibrated calc record, is from the motor readback at every step, and optionally the unidirectional and bidirectional repeatability.guiplans, runs and views scans, automatic calibration and feedback characterisation.
| What | Where |
|---|---|
| Source | https://github.com/DiamondLightSource/dls-motor-scanning |
| PyPI | pip install dls-motor-scanning |
| Docker | docker run ghcr.io/diamondlightsource/dls-motor-scanning:latest |
| Releases | https://github.com/DiamondLightSource/dls-motor-scanning/releases |
Scanning a motor
dls-motor-scanning scan MOTOR START STOP STEP DELAY [options]
START, STOP and STEP are in the motor's engineering units, and DELAY is
the settling time in seconds to wait after each move before reading back. Scan
PS-MO-WIRE-01:Y from 40 to 45 in half-EGU steps, with no settling time:
dls-motor-scanning scan PS-MO-WIRE-01:Y 40 45 0.5 0
The scan direction follows START and STOP, so a reverse scan needs no sign
on the step:
dls-motor-scanning scan PS-MO-WIRE-01:Y 45 40 0.5 0
Each run writes Scan_<motor>_<date>_<start>_<stop>_<step>.txt and .png into
the current directory, and prints a summary of the move times and position
errors.
| Option | Effect |
|---|---|
--extra-pv PV |
Read PV at each step and add it as a column and a third plot panel |
--trigger-pv PV |
Pulse PV high then low after each move, for example to fire a detector |
--trigger-width SECS |
How long the trigger is held high (default 1.0) |
--trigger-post-delay SECS |
How long to wait after the trigger returns low (default 0.0) |
--timestamp |
Add a UTC timestamp column taken from the EPICS timestamp of the readback |
--no-txt |
Do not write the data file |
--no-png |
Do not save the plot |
--no-plot |
Do not open a plot window |
The output file
The data file is space separated, with a header row naming the columns:
Desired Actual MoveTime Timestamp(UTC)
40.5 40.499 1.1394305229187012 2026-08-14T09:15:56.375000Z
41.0 40.9992 1.1742472648620605 2026-08-14T09:15:57.625000Z
Timestamp(UTC) is the timestamp the IOC put on the readback record, not the
time the client received it, which makes it directly comparable with archiver
data. It appears only when --timestamp is given, as does the --extra-pv
column.
Plotting on a remote machine
--plot needs a working display. Over a slow link, or on a headless machine,
prefer:
dls-motor-scanning scan PS-MO-WIRE-01:Y 40 45 0.5 0 --no-plot
which skips the interactive window entirely and just writes the png.
A note on backends. cothread integrates with Qt and not with Tk, and the two segfault if combined.
PyQt5is therefore a dependency, and the tool selectsqtaggexplicitly rather than letting matplotlib work through its own candidate list, which would fall back totkagg. If Qt cannot be imported, orDISPLAYis unset, the interactive plot is skipped with a message instead of taking the process down with it.The png is always rendered under Agg and written to disk before any GUI toolkit is touched, so a display problem can never cost you the saved plot.
Calibrating a feedback device
dls-motor-scanning calibrate DATA_PATH [options]
The usual input is the data file from a scan run with --extra-pv reading the
raw feedback, such as a potentiometer's ADC counts, at every step:
dls-motor-scanning scan BL01I-MO-STAGE-01:X 0 50 1 0.5 --extra-pv BL01I-MO-POT-01:ADC --no-plot
dls-motor-scanning calibrate Scan_BL01I-MO-STAGE-01:X_<date>_0.0_50.0_1.0.txt --egu mm
The extra PV column is fitted against the Actual column, and the calc
record's INPA defaults to the extra PV's name, so no other options are
needed. The fit needs at least six distinct raw readings, and many more across
the full travel give a better one.
A comma separated CSV works too. With exactly two columns, the raw feedback is the integer column if just one of them holds integers, otherwise the first column:
raw,encoder
0,2.0
200,2.5
400,3.0
dls-motor-scanning calibrate pot.csv --raw-input-pv BL01I-MO-POT-01:ADC --excel-cell C2
| Option | Effect |
|---|---|
--raw-column COLUMN |
Column holding the raw feedback, instead of the default above |
--position-column COLUMN |
Column holding the scaled position, instead of Actual |
--raw-input-pv PV |
INPA of the calc record (default: the raw column's name) |
--egu UNITS |
EGU of the calc record (default mm) |
--excel-cell CELL |
Cell the Excel formula reads the raw value from (default A1) |
This prints the largest residual of the fit, the six coefficients, a Builder
records.calc entry with them loaded into fields B to G, and an equivalent
Excel formula referencing --excel-cell. The record's name and record are
left blank for you to fill in.
Characterising feedback
dls-motor-scanning characterise-feedback MOTOR START STOP --compare-pv PV [options]
Once the calc record is loaded, give the full range of the stage and the calibrated PV. The motor readback, ideally from a trusted encoder, is the reference:
dls-motor-scanning characterise-feedback BL01I-MO-STAGE-01:X 0 50 --compare-pv BL01I-MO-POT-01:POS --no-plot
By default this is a single pass from START to STOP in 20 steps, with a
0.5 second settling delay, reporting the signed Actual - PV at each step. It
adds an Actual-Extra column to the data file, a block of statistics to the
summary, and a plot of the PV and the difference against the readback. The mean
is the calibration's offset, the standard deviation its scatter, and the largest
disagreement the worst case across the travel. The stage's own positioning,
demand against readback, says nothing about the calibration, so it isn't
reported or plotted.
Repeatability
Add --repeats N to also measure repeatability. The range is then traversed
there and back N times, so that each target between the two ends is approached
N times moving each way:
dls-motor-scanning characterise-feedback BL01I-MO-STAGE-01:X 0 50 --compare-pv BL01I-MO-POT-01:POS --repeats 5 --no-plot
The readings at each target are grouped by approach direction and reduced to a
mean and sample standard deviation s, then reported in the style of ISO
230-2, each at its worst target:
| Figure | Meaning |
|---|---|
| Unidirectional repeatability R+/R- | 4s of the approaches moving positive / negative |
| Reversal B | Mean moving positive minus mean moving negative: hysteresis or backlash |
| Mean reversal | B averaged over every target |
| Bidirectional repeatability R | max(2s+ + 2s- + abs(B), R+, R-), the spread whichever way a target is approached |
| Bidirectional accuracy A | Lowest mean - 2s to highest mean + 2s, over every target and direction |
These are for Actual - PV, the calibrated device against the readback. The
data file gains Cycle and Direction (+1 or -1) columns, and the outputs
are named CharacteriseFeedback_..._x<N>. The plot has three panels:
RBV - PVat each target, as mean and2sfor each direction, over the band of A. The shape is the calibration's systematic error, the gap between the directions is the reversal.- Each reading minus the mean of its target and direction, coloured by cycle. The spread is the repeatability, and a steady move from cycle to cycle is drift.
- R+, R-, |B| and R at every target, whose worst are the printed figures.
| Option | Effect |
|---|---|
--compare-pv PV |
The PV to compare with the motor readback (required) |
--step EGU |
Step size (default: a 20th of the range) |
--delay SECS |
Settling time after each move (default 0.5) |
--repeats N |
Scan there and back N times (at least 2) and report repeatability |
--timestamp, --no-txt, --no-png, --no-plot |
As for scan |
If --step doesn't divide the range exactly, the last target falls short of
STOP. Avoid a step that is a multiple of a periodic error in the device, such
as a leadscrew's pitch, because every target then lands at the same phase and
the error doesn't show.
The scan and characterise-feedback GUI
dls-motor-scanning gui
This opens a window with Scan and Characterise feedback tabs. It needs a display and PyQt5. In Scan, supplying an Extra PV automatically fits that raw feedback against the measured motor readback after a successful scan. The embedded Calibration page shows the fit, residuals, coefficients, EPICS calc record and Excel formula. It also accepts existing scan files or CSVs. The EGU field can be edited for files whose units are not recorded.
The CLI does the same with scan --extra-pv PV: calibration is printed and,
when text output is enabled, saved as Calibration_Scan_...txt. At least six
distinct finite raw readings are needed; otherwise calibration is skipped with
an explanation and the scan data is retained. Characterise feedback does not recalibrate its
comparison PV. The standalone calibrate command remains available for files.
Generated formulas are never applied to the IOC automatically.
The window grows to fit the parameter form, up to the available screen height; smaller screens retain scrolling. Appearance > System follows the desktop colour preference (the Linux Settings portal, with GNOME settings as a fallback). Widgets and plots share the resulting light/dark palette. Light and Dark are also available for remote sessions where desktop preferences are unavailable. Your appearance selection is remembered.
The former verify command remains a hidden compatibility alias. New feedback
files use CharacteriseFeedback_...; existing Verify_... files still open.
For feedback characterisation:
- Enter the motor PV and press Read motor. This reads the position, soft
limits, EGU, VELO and ACCL. The compare PV defaults to
<motor>:POT. - Set the start, stop, step, repeats and settling delay. With each change, the Plan tab redraws the motor's position against time, the sawtooth it will follow, with a dot at each reading. The number of moves, the estimated time and the finishing time are shown under the form. So are warnings about a range outside the soft limits, or a step that doesn't divide the range.
- Press Run and confirm. This runs the
characterise-feedbackcommand above in a separate process and follows what it prints. Its output is echoed to the terminal too. The Plan tab shows how far it has got: the path done so far in green, a red dot at the latest reading and "Reading N of M" above. The Data tab fills in with every reading. The Results tab redraws every 10 seconds, and the progress bar re-estimates the time left from the pace so far. Stop ends the scan and keeps every reading so far. The motor still finishes the move it was given. - Review the results, then use Save data... to choose a filename and save the readings. GUI scans do not automatically write data, PNGs or calibration reports. Stopped scans can also be reviewed and saved. Use each plot's toolbar to save an image. Readings are held in memory until replaced by another scan/file or the window is closed. CLI saving defaults are unchanged.
Open data file... loads any earlier CharacteriseFeedback_*.txt into the Results,
Summary and Data tabs. It fills in the form too, so the same scan can be run
again. Each plot has a toolbar to zoom, pan and save.
The time estimate models each move as a trapezoid: ACCL seconds to reach VELO, a cruise, and ACCL seconds to stop. It then adds the Overhead per move you enter, for the controller settling and the put completing, which the model doesn't capture. To find it, compare the mean move time from an earlier scan's summary with the trapezoid. For example, a 0.5 mm step at VELO 0.5 and ACCL 0.5 is 1.5 s, but a motorPLC axis measured 4.0 s, so its overhead is 2.5 s.
Development
uv sync
uv run pytest
The scan code reaches EPICS through cothread.catools, which is imported lazily
so the tests, --help and the calibrate command all work without an IOC. The
test suite substitutes a fake Channel Access layer, so a full scan can be
exercised without hardware.
Metadata
Release files for dls-motor-scanning 1.0.0b3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dls_motor_scanning-1.0.0b3.tar.gz | 119.1 kB | Without provenance | Details for dls_motor_scanning-1.0.0b3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dls_motor_scanning-1.0.0b3-py3-none-any.whl | Python 3 | none | any | Details for dls_motor_scanning-1.0.0b3-py3-none-any.whl |
Total release size: 172.3 kB
Release files / dls_motor_scanning-1.0.0b3.tar.gz
| Download URL | dls_motor_scanning-1.0.0b3.tar.gz |
|---|---|
| Size | 119.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a97801eb9acbfc8fc39cc7067b7679f50fd95b5c87e96ee07db22caa4d239803
|
|
BLAKE2b-256 checksum How to use checksums |
dfc138b9535b95c01ffb65d2911a6127127ad4d397ee7b62a3c07b3b9cc5bc6f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / dls_motor_scanning-1.0.0b3-py3-none-any.whl
| Download URL | dls_motor_scanning-1.0.0b3-py3-none-any.whl |
|---|---|
| Size | 53.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b0cdb0d5597030b8fa8e2ed1c0c40fd13f24b93e5630da2be0d5f6f944b2cc46
|
|
BLAKE2b-256 checksum How to use checksums |
377a1e4ec8dddd3e7e2a569113f3c3fa0e021e86ec74ea211c358370dd6a603d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for dls-motor-scanning 1.0.0b3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.