[Harpy] Parallelisation Strategy

[fsoubelet]

This PR introduces a parallelisation strategy for the harpy harmonic analysis.
Let me preface this by saying: no code that does any of the calculations has been touched.

This is a long PR text, I'll try to split it.

Context

Currently, when performing harmonic analysis for the bunches in a file, harpy runs the analysis serially, bunch after bunch. We have a wall time of ~25-30s for analysing a bunch so this scales roughly as n_bunches * 30 seconds.

The operations within harpy (SVD, some big dot products, FFTs) dispatch hungrily across all available threads via BLAS.

As it turns out for our operations this is not a great idea, and benchmarks show that limiting BLAS to a single thread gives similar results (slightly faster for SVD, slightly slower for dot product, all within 5-10% in any case). This is an opportunity.

What is changed

The parallelisation strategy is changed. Instead of running bunch after bunch and letting BLAS eat up all threads unproductively, the following is done:

• The harpy workload of single bunches sets a hard cap for BLAS to one (1) thread,
• The bunches are now parallelised across workers.

Implementation

1. Most of the new code is in a new omc3.harpy._parallel module, with heuristics to determine the number of workers to dispatch to. This is done based on estimated peak RSS for a given bunch (from the TbT data and from the harpy options), the detected number of available logical cores and RAM, and user input (more on that later).

2. The main function in harpy now calls this heuristic first then dispatches work. It performs the same thing as the current behaviour if n_jobs=1, and starts a ProcessPoolExecutor to parallelise across bunches if n_jobs>1.

3. A CLI flag --n_jobs is provided to give the user (and GUI) control over this strategy. Providing 0 leads to automatic determination as described above. Giving 1 leads to serial processing, which is the current behaviour. Providing N>0 uses uses up to N workers, still bounded by the automatic safety limits (available cores, number of bunches, and RAM budget): an explicit N can only throttle the pool below the automatic choice, but never oversubscribe it.

Some little things:

• Version and CHANGELOG are bumped in preparation for a feature release. Would be nice to have Dispersion error propagation was using wrong values #579 in as well, and maybe some further improvements in the calculation parts of harpy I am reserving for another PR.
• threadpoolctl is added to the dependencies (was already a transitive dependency),
• psutil is added to the dependencies.

Performance Gains

The theoretical gains, assuming we are not limited by the resources of the machine, is a factor of n_bunches at most. In practice there is some overhead due to the dispatch of jobs but it is small.

Previously: a file with n_bunches would do one by one.
Now: a file with n_bunches will start all simultaneously and be done in ~ the same time it takes to complete a single bunch's analysis.

Tests

I have added unit tests for both the parallelisation heuristics, and for comparing serial results vs parallel workers results on the same inputs. The latter is done for lin files but also the .amps[xy] and .freqs[xy] files from the full_spectra output (as full_spectra is our default in the GUI).

Field Tests

I have tested this in the CCC starting workloads from the GUI. Reproducing previous analyses leads to the exact same results, down to the optics analysis downstream.

See below for GUI + harpy parallelisation considerations when we are dealing with multiple files.

Wider parallelisation with GUI

There are two layers to the interplay here. This is assuming the default GUI setting of "Run Per-File Tasks in Parallel".

When selecting multiple files in the BPM panel and starting the Analyse spectra command, the GUI issues a python -m omc3.hole_in_one --harpy [...] command for each file, instantly. This is done via ssh submission to the relevant optics server. What happens next is:

• Currently: All started processes (from GUI, one per file) start at once, and for each file the bunches are done sequentially. With a wall time of ~30s for analysing a bunch each file takes at minimum 30s x n_bunches. Considering BLAS maxes out the threads on the server, with a lot of files (or the newer 5 bunches / beam measurements) this can lead to throttling and additional slowdown on top of the 30s x n_bunches.
• This PR: All started processes (from GUI, one per file) start at once, and each analyses the resources then parallelises across bunches within detected limits (available cores, RAM etc). If the resources are high enough then all bunches run in parallel and we are reduced to the min wall time of ~30s for a given bunch's analysis.

The general outcomes:

• For a single file the gain is nice, since we always fall down to base wall time with our optics server resources: from n_bunches x ~30s -> ~30s.
• For many files the gain can be even more, since the old behaviour can throttle the server and in that case we might see a better speed-up.
• Importantly, when analysing the kick files as they come in we can assume on would always analyse just one file at a time and be done in ~30s every time. This lets analysis stay on top of the measurements considering we can only get a kick every minute (currently, especially with the 5 bunches the analysis falls behind measurements quite quickly).

Benchmarks from the CCC

The python edge environment is currently on this branch. I have reproduced some analyses from earlier in the year and compared the prod version's performance (current omc3) to the edge version (this branch).

All results down to the optics analysis are perfectly identical. Below are some screenshots of the performance gains, for the 5 bunches measurements.

Current omc3 version

	Current omc3	This Branch omc3
Optics Server Usage
Performance Logs
Total Wall Time	120 seconds	31 seconds

Verdict: we now finish all much faster and close to the min wall time for one bunch analysis, and we utilise much less of the machine resources, which means we have room for a lot more parallelisation (more files, more bunches).

Notice also that the new harpy is a little more talkative in the logs :)

Results of the analyses are the exact same, see the final optics for instance:

For more benchmark details see the OMC logbook entries of today, 2026-07-03.

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
omc3
__init__.py
hole_in_one.py
omc3/harpy
_parallel.py
frequency.py
handler.py
omc3/plotting/spectrum
utils.py
Project Total

This report was generated by python-coverage-comment-action