Add the option for particle RF phase-wrapping by cemitch99 · Pull Request #1380 · BLAST-ImpactX/impactx

cemitch99 · 2026-04-02T18:13:33Z

This PR adds the capability of applying particle boundary conditions, related to the RF bucket (for example, wrapping particles modulo 2pi in RF phase).

add bucket length to particle container
add user-facing input options for bucket length
add function applying periodic particle boundary conditions
add functionality for alternative boundary options (e.g. reflection)
add Python bindings
add user-facing example (periodic bc)
add Python unit tests
update documentation

Longitudinal particle boundary condition options to target:

open/off (no action)
periodic (phase wrapping)
cut (particle lost)
reflection (particle bounces back with reversed momentum)

for more information, see https://pre-commit.ci

ax3l · 2026-04-14T23:52:34Z

        std::list<std::unordered_map<std::string, amrex::ParticleReal> > m_beam_moments;

+        //! the RF bucket length for particles in the particle container
+        amrex::ParticleReal m_bucket_length;


I would store this as std::optional so it is clear when this is thought to be undefined/None:

Suggested change

amrex::ParticleReal m_bucket_length;

std::optional<amrex::ParticleReal> m_bucket_length;

Maybe even store like store_beam_moments as a public member and document that instead.

memo to myself: do at the end

ax3l · 2026-04-14T23:53:52Z

+        amrex::ParmParse pp_algo("algo");
+        std::string particle_bc = "open";
+        pp_algo.queryAdd("particle_bc", particle_bc);
+        int particle_bc_int;


Good case for an enum, in our case we can use AMREX_ENUM that supports string conversion.

Yes, thanks; I will revisit here.

ax3l · 2026-04-14T23:55:19Z

+        } else if (particle_bc == "reflecting") {
+            particle_bc_int = 3;
+        } else {
+            particle_bc_int = 0;


Logic bug: else seems to imply open, but open already returned above.

Usability: we should throw an error if an unknown other BC is set than the ones we know/handle. (This does not prevent handling no input as open by default.)

Agreed; will replace this line with an error message.

ax3l · 2026-04-14T23:57:45Z

+                // Gather particles and apply boundary condition
+                amrex::ParallelFor(np, [=] AMREX_GPU_DEVICE (int i)
+                {
+                    // Access SoA Real data
+                    amrex::ParticleReal & AMREX_RESTRICT t = part_t[i];
+                    amrex::ParticleReal & AMREX_RESTRICT pt = part_pt[i];
+
+                    if (particle_bc_int==1) {
+
+                        // Periodic particle boundary condition:  apply phase wrapping in t (modulo bucket_duration):
+                        amrex::ParticleReal ttest = std::fmod(t+bucket_half_duration, bucket_duration);
+                        t = (bucket_duration != 0.0)? std::fmod(ttest+bucket_duration, bucket_duration)-bucket_half_duration : t;


Suggestion: we can write the if/switch on the enum particle_bc_int outside the amrex::ParallelFor and create 3 unique, performant ParallelFor kernels; instead of one branching (slow) one.

Oh, I thought about branching outside the ParallelFor, but it introduces a lot of duplication. It's ok with me to rework things this way if there is an expected performance advantage.

ax3l · 2026-04-14T23:58:12Z

+
+namespace impactx::particles
+{
+    /** Function to apply longitudinal particle boundary (periodic, etc.)


Add the AMREX_ENUM on the types of boundaries we have here.

ax3l · 2026-04-15T00:01:48Z

+        amrex::ParmParse pp_algo("algo");
+        std::string particle_bc = "open";


This feel like something we could set on beam.[...] was well... (probably need to generalize the section heading here)

But no super strong opinion.

Co-authored-by: Axel Huebl <axel.huebl@plasma.ninja>

cemitch99 · 2026-04-15T21:15:15Z

        std::list<std::unordered_map<std::string, amrex::ParticleReal> > m_beam_moments;

+        //! the RF bucket length for particles in the particle container
+        std::optional<amrex::ParticleReal> m_bucket_length;


@ax3l Making this optional is introducing build problems that are taking time to fix. Reverting to the previous behavior for now.

Oh yes, I just drafted the implementation. I can do it when the PR is ready from your end.

Co-authored-by: Chad Mitchell <46825199+cemitch99@users.noreply.github.com>

for more information, see https://pre-commit.ci

ax3l · 2026-04-16T20:40:20Z

+        if (particle_bc == "periodic") {
+            particle_bc_int = 1;
+        } else if (particle_bc == "absorbing") {


memo for @ax3l : use AMREX_ENUM (define in ParticleBoundary.H)

for more information, see https://pre-commit.ci

ax3l added 30 commits April 1, 2026 16:44

Update Stub Files

8f1562c

Update Stub Files

8f70685

Update Stub Files

c7663ad

Update Stub Files

f4c8369

Update Stub Files

462ee9f

Update Stub Files

f52b683

Update Stub Files

036db8d

Update Stub Files

fa66cd6

Update Stub Files

57a53fe

Update Stub Files

275be19

Update Stub Files

28baa60

Update Stub Files

bfa1af0

Update Stub Files

b237f58

Update Stub Files

e5d64dd

Update Stub Files

f5d3c2d

Update Stub Files

9f36f28

Update Stub Files

b5af6b9

Update Stub Files

4e0763f

Update Stub Files

98a578e

Update Stub Files

c81d377

Update Stub Files

70733c5

Update Stub Files

39192ab

Update Stub Files

0f8b0b9

Update Stub Files

2649d3c

Update Stub Files

8d2e63a

Update Stub Files

1f21292

Update Stub Files

be8a686

Update Stub Files

d70165a

Update Stub Files

907043a

Update Stub Files

d7bdcb7

cemitch99 and others added 5 commits April 10, 2026 16:22

Add Python bindings.

254b22c

[pre-commit.ci] auto fixes from pre-commit.com hooks

1ce5b3f

for more information, see https://pre-commit.ci

Merge branch 'development' into add_phase_wrapping

4821f4f

Add Python version of test.

2adf576

[pre-commit.ci] auto fixes from pre-commit.com hooks

72a3846

for more information, see https://pre-commit.ci

ax3l reviewed Apr 15, 2026

View reviewed changes

Apply suggestions from code review

52e8259

Co-authored-by: Axel Huebl <axel.huebl@plasma.ninja>

cemitch99 commented Apr 15, 2026

View reviewed changes

Comment thread src/particles/ImpactXParticleContainer.cpp

Fix optional bucket_length.

a798b00

cemitch99 commented Apr 15, 2026

View reviewed changes

Comment thread src/particles/ImpactXParticleContainer.cpp Outdated

Apply suggestion from @cemitch99

ccfe069

cemitch99 commented Apr 15, 2026

View reviewed changes

Comment thread src/particles/ImpactXParticleContainer.H Outdated

cemitch99 commented Apr 15, 2026

View reviewed changes

Comment thread src/particles/ImpactXParticleContainer.cpp Outdated

Remove std::optional from bucket_length.

8a0d5f3

Co-authored-by: Chad Mitchell <46825199+cemitch99@users.noreply.github.com>

ax3l mentioned this pull request Apr 15, 2026

LinearMap Property Check #1396

Merged

cemitch99 and others added 5 commits April 16, 2026 09:55

Move branching outside of ParallelFor.

daa439d

Add a second example.

a5e391f

[pre-commit.ci] auto fixes from pre-commit.com hooks

2e65cf0

for more information, see https://pre-commit.ci

Update CMakeLists to include new test.

c6b072d

[pre-commit.ci] auto fixes from pre-commit.com hooks

dd3e78a

for more information, see https://pre-commit.ci

ax3l reviewed Apr 16, 2026

View reviewed changes

Comment thread examples/phase_wrapper/run_drift_phase_wrap.py Outdated

ax3l reviewed Apr 16, 2026

View reviewed changes

cemitch99 and others added 7 commits April 16, 2026 14:53

Simplify test.

c878ffc

[pre-commit.ci] auto fixes from pre-commit.com hooks

43d5eab

for more information, see https://pre-commit.ci

Simplify example and example naming.

af45b34

Remove unused ParmParse variables.

2c28722

Fix second unused ParmParse error.

77953ba

Add draft of simple pytest using periodic bc.

1f1747e

[pre-commit.ci] auto fixes from pre-commit.com hooks

a78a4dc

for more information, see https://pre-commit.ci

	amrex::ParticleReal m_bucket_length;
	std::optional<amrex::ParticleReal> m_bucket_length;

		amrex::ParmParse pp_algo("algo");
		std::string particle_bc = "open";

Conversation

cemitch99 commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cemitch99 commented Apr 2, 2026 •

edited

Loading