Upgrade and major bug fix to the beam loading module #1025

lcarver · 2025-12-05T15:00:02Z

There has been a major bug present in the beam loading module since it was first written. To summarise, the beam induced voltage used in the cavity feedback was taken at the wrong point. For a single harmonic system, (like the work published in IPAC : https://inspirehep.net/files/cc5691837fadff23276bd1022058a71e ) the passmethod was working as expected and this bug was not visible, however when a harmonic cavity was present, the phase of the beam induced voltage became incorrect, causing unstable results. This was not the correct behaviour.

This PR completely remodels the computation to compute the beam induced voltage identically to mbtrack.

This PR is a work in progress. Still to do:

In the PassMethod I need the full fill pattern and the total number of buckets for the main RF as I also want to record the vbeam for the empty buckets. At the moment all I can pass is bunch_spos and bunch_currents which have length of nbunch. For now I do a dirty reconstruction of the fill pattern and I compute the ring harmonic number from the RF frequency, but needs to be cleaned up.
~~Benchmark uniform, 16b and asymmetric fill pattern with MBTRACK. Check with multiple slices per bunch and 1 slice per bunch.~~
~~Check the passive cavity cases including the passive cavity feedback.~~
~~Check buffers and windowing.~~
~~Documentation.~~
~~Update examples.~~

Other relevant major changes:

BLMode.WAKE has been removed in its entirety, it was not useful, slow and not needed. The tests have been updated and the default and now only method is PHASOR.

Vgen was an array of two [Vgen, psi], now it is an array of four [Vgen, thetag, psi, Vgr]. This has been updated everywhere, but breaks a bit some old scripts.

The ring harmonic number and the filling pattern are now passed to the passmethod through the ring param.

…ck uniform bug

…ssues

lcarver · 2026-01-19T10:08:15Z

Comparing MBTRACK and PyAT for uniform filling, Nslice=200 per bunch (in pyat, Nslices=1001 but fixed in mbtrack), Nparts_per_bunch=100k, Single mode only.

The FBOff case agrees very well, this shows that the vbeam kick is correctly computed and applied to the slices.
The dynamic behaviour of the FBWeak and FBStrong cases agree nicely. There is an offset present in both cases, which is very small (0.2ps!), but nonetheless it is there. There are a few differences between PyAT and MBTRACK that can account for this. The first is that MBTRACK uses Fixed Slicing (Nslices=1001 over the range +- 50sigma, where sigma=3mm. This gives a bin width of 0.01ps in mbtrack, compared to PyAT which uses dynamic slicing. Also in MBTRACK they track a frozen beam distribution to initialise the generator voltage settings, this means the start point is not quite identical. I don't rule out some small difference in the implementation that I am not yet aware of, but it is very close and the dynamic behaviour is the same.

lcarver · 2026-01-20T13:31:30Z

Below: Main cavity + 4HC, 200mA uniform mode, ~100k particles per bunch in pyat, ~50k particles per bunch in mbtrack, 200 slices per bunch in pyat, 1001 slices from +- 50*3mm in mbtrack, strong feedback (Vgain=1, PhaseGain=0.001 on main, PhaseGain=0.01 on 4HC)

Below is TBL for 7/8 filling, starting with bucket 0 filled.

Below is TBL for 7/8 filling, starting with bucket 0 empty.

~~Starting with bucket 0 empty seems to cause a problem in the loop. I will check.~~
TBL case now agrees beautifully.

Below:
16b, the reduced bunch length comes from the short range wake of the cavities.

All good!

I do not plan to test 16b mode with a short range wakefield, I will save it for a later date as I do not currently know how to do it in MBTRACK. So it will take some more time. However, I know the individual components work (SR wake alone, and beam loading alone) I just need to verify the case with both together.

lcarver · 2026-01-20T15:33:18Z

Fully ready for review and merging.

atintegrators/atimplib.c

docs/p/howto/Collective.rst

pyat/at.c

pyat/at/collective/beam_loading.py

docs/p/howto/Collective.rst

swhite2401 · 2026-01-21T07:33:42Z

Very nice, only few minor comments!
I trust you on the physics / formulas, benchmarking looks good.

lfarv · 2026-01-21T13:07:13Z

@lcarver : Nice job, and thanks @swhite2401 for reviewing. I trust you both.
I suggest running ruff: it suggests a number of code improvements, and also mypy for typing errors (there are also quite some…).
But none of those will change the behaviour nor the results, so it's ok for me as it is.

lcarver · 2026-01-21T14:16:45Z

I fixed the TBL case and made the changes suggest by @swhite2401. Please read the docs again, if you think it is not clear, feel free to make changes yourself.

Given that I found a bug in the TBL case, I plan to check a quick 16b case too to make sure I haven't missed anything.

lcarver · 2026-01-21T14:54:40Z

@lcarver : Nice job, and thanks @swhite2401 for reviewing. I trust you both. I suggest running ruff: it suggests a number of code improvements, and also mypy for typing errors (there are also quite some…). But none of those will change the behaviour nor the results, so it's ok for me as it is.

ruff was nice, and i used it. mypy has made many many suggestions and many of them I do not understand. I'm sorry, I am not so knowledgable on the type formatting.

lfarv · 2026-01-21T15:40:59Z

@lcarver : Agreed, forget typing !

But running ruff with the configuration I propose in #1048 still gives many more suggestions:

(pyat) laurent@garou at % ruff check pyat/at/collective/beam_loading.py 
pyat/at/collective/beam_loading.py:5:1: UP035 [*] Import from `collections.abc` instead: `Sequence`
pyat/at/collective/beam_loading.py:40:1: W293 Blank line contains whitespace
pyat/at/collective/beam_loading.py:51:14: UP007 [*] Use `X | Y` for type annotations
pyat/at/collective/beam_loading.py:52:13: UP007 [*] Use `X | Y` for type annotations
pyat/at/collective/beam_loading.py:54:11: UP045 [*] Use `X | None` for type annotations
pyat/at/collective/beam_loading.py:57:5: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:83:26: B905 `zip()` without an explicit `strict=` parameter
pyat/at/collective/beam_loading.py:93:24: B905 `zip()` without an explicit `strict=` parameter
pyat/at/collective/beam_loading.py:103:59: UP045 [*] Use `X | None` for type annotations
pyat/at/collective/beam_loading.py:104:5: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:120:26: B905 `zip()` without an explicit `strict=` parameter
pyat/at/collective/beam_loading.py:150:5: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:185:17: UP045 [*] Use `X | None` for type annotations
pyat/at/collective/beam_loading.py:186:21: UP045 [*] Use `X | None` for type annotations
pyat/at/collective/beam_loading.py:187:17: UP045 [*] Use `X | None` for type annotations
pyat/at/collective/beam_loading.py:188:21: UP045 [*] Use `X | None` for type annotations
pyat/at/collective/beam_loading.py:191:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:261:17: ISC003 [*] Explicitly concatenated string should be implicitly concatenated
pyat/at/collective/beam_loading.py:283:21: ISC003 [*] Explicitly concatenated string should be implicitly concatenated
pyat/at/collective/beam_loading.py:292:17: ISC003 [*] Explicitly concatenated string should be implicitly concatenated
pyat/at/collective/beam_loading.py:318:14: UP008 Use `super()` instead of `super(__class__, self)`
pyat/at/collective/beam_loading.py:376:21: ISC003 [*] Explicitly concatenated string should be implicitly concatenated
pyat/at/collective/beam_loading.py:379:17: B028 No explicit `stacklevel` keyword argument found
pyat/at/collective/beam_loading.py:385:14: PLR1714 Consider merging multiple comparisons: `self._cavitymode in {2, 3}`.
pyat/at/collective/beam_loading.py:421:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:426:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:431:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:436:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:446:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:456:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:461:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:473:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:478:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:483:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:488:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:501:21: UP045 [*] Use `X | None` for type annotations
pyat/at/collective/beam_loading.py:502:21: UP045 [*] Use `X | None` for type annotations
pyat/at/collective/beam_loading.py:505:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:536:17: B028 No explicit `stacklevel` keyword argument found
pyat/at/collective/beam_loading.py:551:9: D415 First line should end with a period, question mark, or exclamation point
pyat/at/collective/beam_loading.py:554:15: C402 Unnecessary generator (rewrite as a dict comprehension)
pyat/at/collective/beam_loading.py:555:16: UP030 Use implicit references for positional format fields
pyat/at/collective/beam_loading.py:555:16: UP032 [*] Use f-string instead of `format` call
Found 43 errors.
[*] 16 fixable with the `--fix` option (27 hidden fixes can be enabled with the `--unsafe-fixes` option).

lcarver · 2026-01-23T08:19:09Z

I ignore the following ones:

cluster-access-03:/machfs/carver/pyat_dev/at % ruff check pyat/at/collective/beam_loading.py 
pyat/at/collective/beam_loading.py:5:1: UP035 [*] Import from `collections.abc` instead: `Sequence`
pyat/at/collective/beam_loading.py:283:21: EM101 Exception must not use a string literal, assign to variable first
pyat/at/collective/beam_loading.py:292:17: EM101 Exception must not use a string literal, assign to variable first
pyat/at/collective/beam_loading.py:310:30: EM101 Exception must not use a string literal, assign to variable first
pyat/at/collective/beam_loading.py:319:14: UP008 Use `super()` instead of `super(__class__, self)`
pyat/at/collective/beam_loading.py:377:21: ISC003 [*] Explicitly concatenated string should be implicitly concatenated
pyat/at/collective/beam_loading.py:380:17: B028 No explicit `stacklevel` keyword argument found
pyat/at/collective/beam_loading.py:537:17: B028 No explicit `stacklevel` keyword argument found
pyat/at/collective/beam_loading.py:555:15: C402 Unnecessary generator (rewrite as a dict comprehension)
pyat/at/collective/beam_loading.py:556:16: UP030 Use implicit references for positional format fields
pyat/at/collective/beam_loading.py:556:16: UP032 [*] Use f-string instead of `format` call

lcarver · 2026-01-23T12:21:22Z

OK to merge?

docs/p/howto/Collective.rst

lfarv · 2026-01-23T13:57:07Z

ignore the following ones:

Ok for me. But if you look at the documentation for those messages, you will see that the suggestions are really beneficial !

lcarver · 2026-01-23T14:08:53Z

ignore the following ones:

Ok for me. But if you look at the documentation for those messages, you will see that the suggestions are really beneficial !

I needed convincing by Simon, a few of them to be seemed arbitrary but I have been convinced. I put all of the suggestions in.

lcarver · 2026-01-23T14:11:55Z

all implemented

Lee Carver added 7 commits September 18, 2025 16:08

Initial stashing to implement mbtrack1 feedback loop into pyat to che…

646e94f

…ck uniform bug

Stash

95ac7b8

stash

57f5677

stash

5e44085

conflict

2189aee

Merge branch 'master' into modify_beamloading

43d7cb1

Attained first working version

92494ce

lcarver added WIP work in progress Python For python AT code bug fix C For C code / pass methods labels Dec 5, 2025

lcarver requested review from lfarv and swhite2401 and removed request for lfarv December 5, 2025 15:00

Lee Carver and others added 15 commits December 5, 2025 16:03

Remove BLMode from tests

0f42683

Fix dirty fill pattern computation

7c7c88b

seg fault?

82ead9b

no

7fa1c9b

Remove some hard coded thigns

da49893

test M

35e11f1

Change mean of phase and amp to mean of real and imaginary to avoid i…

3e4b854

…ssues

Change rad on to enable 6d

aad1ecb

Add harmonic_number and fillpattern to ringparams

609d00b

whitespace

128ebe8

Fix mex

489bcd6

update example and clean up

17992f0

modernise

98e8817

update test_track_beamloading

855b7f5

test

514364c

swhite2401 reviewed Jan 21, 2026

View reviewed changes

Lee Carver added 2 commits January 21, 2026 13:52

bug fix for TBL. Include bunch_spos[0] in dt computation for islice=0

cdcc6a7

Change M to ring_harmn

b8a55c7

Lee Carver added 5 commits January 21, 2026 14:39

run black on beam_loading.py

459862f

add docstrong for FeedbackMode

d0d64b0

numpy to np

b195602

change fillpattern to (double[1]){1.0}

9694e6d

doc

48d8a00

ruff suggestion to remove unused variable. Not bad!

8042ad6

Lee Carver added 2 commits January 23, 2026 09:19

ruff check

0994af8

missed one

b463add

swhite2401 reviewed Jan 23, 2026

View reviewed changes

docs/p/howto/Collective.rst Outdated Show resolved Hide resolved

Lee Carver added 2 commits January 23, 2026 15:06

Do all ruff commands

adf14e7

fix typo

700703b

docs

209409e

swhite2401 approved these changes Jan 23, 2026

View reviewed changes

lcarver merged commit 0c4a00c into master Jan 23, 2026
23 checks passed

Upgrade and major bug fix to the beam loading module #1025

Upgrade and major bug fix to the beam loading module #1025

Uh oh!

Conversation

lcarver commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lcarver commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lcarver commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lcarver commented Jan 20, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

swhite2401 commented Jan 21, 2026

Uh oh!

lfarv commented Jan 21, 2026

Uh oh!

lcarver commented Jan 21, 2026

Uh oh!

lcarver commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lfarv commented Jan 21, 2026

Uh oh!

lcarver commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lcarver commented Jan 23, 2026

Uh oh!

Uh oh!

lfarv commented Jan 23, 2026

Uh oh!

lcarver commented Jan 23, 2026

Uh oh!

lcarver commented Jan 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lcarver commented Dec 5, 2025 •

edited

Loading

lcarver commented Jan 19, 2026 •

edited

Loading

lcarver commented Jan 20, 2026 •

edited

Loading

lcarver commented Jan 21, 2026 •

edited

Loading

lcarver commented Jan 23, 2026 •

edited

Loading