Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

CI Coverage PyPI License

dls_motor_scanning

Tools for characterising the motion performance of EPICS motors.

Four commands are provided:

  • scan drives 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.
  • calibrate fits 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-feedback scans a motor like scan, 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.
  • gui plans, 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. PyQt5 is therefore a dependency, and the tool selects qtagg explicitly rather than letting matplotlib work through its own candidate list, which would fall back to tkagg. If Qt cannot be imported, or DISPLAY is 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 - PV at each target, as mean and 2s for 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:

  1. 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.
  2. 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.
  3. Press Run and confirm. This runs the characterise-feedback command 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.
  4. 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)

Source distribution for dls-motor-scanning 1.0.0b3
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)

Table of built distributions (wheels) for dls-motor-scanning 1.0.0b3
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page