Space charge 2D envelope push #841

cemitch99 · 2025-02-11T00:20:31Z

This PR implements the linear push of the covariance matrix in the presence of 2D space charge.

Basic math for space charge push
Add calculation of beam perveance
Add beam current user input
Update space charge flag to allow 2D/3D options
Adjust location to src/envelope
Add Python bindings
Benchmark example
Update documentation
Finalize control parameters & update examples

This addresses Issue #826 in the 2D (envelope) case. Follow-up: a corresponding model for 3D space charge.

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

src/particles/spacecharge/EnvelopeSpaceChargePush.H

src/particles/spacecharge/EnvelopeSpaceChargePush.cpp

Co-authored-by: Axel Huebl <[email protected]>

src/particles/spacecharge/EnvelopeSpaceChargePush.cpp

src/particles/spacecharge/EnvelopeSpaceChargePush.H

src/particles/spacecharge/EnvelopeSpaceChargePush.cpp

src/tracking/envelope.cpp

Co-authored-by: Axel Huebl <[email protected]>

updates: - [github.com/astral-sh/ruff-pre-commit: v0.9.4 → v0.9.6](astral-sh/ruff-pre-commit@v0.9.4...v0.9.6) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Move "workflows" to "how-to guides" as in WarpX. Clean up some wording.

Currently, we only support (and document correctly) "static" units, but the user was able to also pass "dynamic", upon which we did print "Dynamic units" but then still used static ones. This now errors out correctly for anything else than "static" until we implement another variant.

* `Source` Element for openPMD * Rename Source Files of `BeamMonitor` * Deduplicate openPMD Logic Helpers * Docs * Example * Doc: Fix Copy-Paste

* update dashboard __init__.py import * Add tooltips functionality to non-nested states * Add tooltips for the custom vselects * update type hints

src/elements/diagnostics/BeamMonitor.cpp

+        /*
+        using SrcData = WarpXParticleContainer::ParticleTileType::ConstParticleTileDataType;
+        tmp.copyParticles(*pc,
+                          [=] AMREX_GPU_HOST_DEVICE (const SrcData& src, int ip, const amrex::RandomEngine& engine)
+                          {
+                              const SuperParticleType& p = src.getSuperParticle(ip);
+                              return random_filter(p, engine) * uniform_filter(p, engine)
+                                     * parser_filter(p, engine) * geometry_filter(p, engine);
+                          }, true);
+        */


src/elements/diagnostics/BeamMonitor.cpp

+            /*
+            // comment this in once IntSoA::nattribs is > 0
+
+            std::copy(IntSoA::names_s.begin(), IntSoA::names_s.end(), int_soa_names.begin());
+
+            for (auto int_idx=0; int_idx < RealSoA::nattribs; int_idx++) {
+                auto const component_name = int_soa_names.at(int_idx);
+                getComponentRecord(component_name).storeChunkRaw(
+                    soa.GetIntData(int_idx).data(), {offset}, {numParticleOnTile64});
+            }
+            */


src/particles/spacecharge/EnvelopeSpaceChargePush.cpp

src/tracking/envelope.cpp

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

src/tracking/envelope.cpp

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

ax3l

This looks awesome!

Added small inline comments.

docs/source/usage/parameters.rst

docs/source/usage/python.rst

examples/CMakeLists.txt

src/envelope/spacecharge/EnvelopeSpaceChargePush.H

src/envelope/spacecharge/EnvelopeSpaceChargePush.cpp

src/initialization/InitDistribution.H

ax3l · 2025-02-20T23:54:59Z

src/initialization/InitDistribution.cpp

+            if (space_charge_model == "3D") {
+                pp_dist.query("charge", intensity);
+                throw std::runtime_error("3D space charge model not yet implemented in envelope mode.");
+            } else if (space_charge_model == "2D") {
+                pp_dist.query("current", intensity);
+            } else {
+                throw std::runtime_error("Unknown space_charge_model (use '2D' or '3D') ");
+            }


I think I want to unify this with algo.space_charge. There is no need for two parameters, we can just do algo.space_charge = false (default), = 2D and = 3D.

This makes sense, although it will break the existing space charge examples, where algo.space_charge = true. In that case, maybe we should push the change through as a follow-up, since it also impacts the logic outside the envelope tracking?

I think I can implement it in a backwards compatible way, will give it a try tomorrow.

I pushed a backwards compatible change and it currently passes CI. This is what existing users will see (True defaults now to 3D space charge and raises a warning to use the new syntax.)

I will push another commit now that updates all examples to the new syntax, so people see and use that going forward. After a few months (year), we can drop support for the old syntax. I added an inline TODO where we will remove it.

src/initialization/InitDistribution.cpp

+                //pp_dist.get("charge", intensity);
+                //amr_data->track_envelope.m_env = impactx::initialization::create_envelope(dist, intensity);


cemitch99 · 2025-02-21T18:15:47Z

examples/aperture/input_aperture.in

@@ -40,7 +40,7 @@ collimator.aperture_y = 1.5e-3
 # Algorithms
 ###############################################################################
 algo.particle_shape = 2
-algo.space_charge = false


I have one concern about this recent change. With algo.space_charge = false, it is obvious to the user that space charge is not active. Without this line, I think it is too easy to forget that space charge is off by default, especially when a nonzero bunch charge is provided. This is especially important in the examples. If we keep three string input options "2D", "3D", and "false", then we could keep this line.

I was wondering about that, good point.

Off was and is the default; I agree we can keep it explicit to avoid any confusion.

cemitch99 · 2025-02-21T18:19:52Z

src/python/ImpactX.cpp

+                        pp_algo.add("space_charge", std::string("3D"));
+                    } else {
+                        py::print("sim.space_charge = False is deprecated, please use space_charge = \"off\" (or skip for default)");
+                        pp_algo.add("space_charge", std::string("off"));


Yes, I see that the "off" string is supported, so I would keep this in the example input files.

Agreed. And we can still use false as well.

The problem why I need to internally call this off in the enum is that false is a C++ keyword.

Ah, can name it False internally (uppercase)

src/tracking/particles.cpp

src/tracking/envelope.cpp

src/tracking/particles.cpp

And add doxygen and improve case matching.

cemitch99 and others added 2 commits February 10, 2025 16:17

Initial draft commit.

a605081

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

9b464c1

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

ax3l self-requested a review February 11, 2025 00:35

ax3l added the component: space charge Space charge & potential solver label Feb 11, 2025

ax3l reviewed Feb 11, 2025

View reviewed changes

src/particles/spacecharge/EnvelopeSpaceChargePush.H Outdated Show resolved Hide resolved

src/particles/spacecharge/EnvelopeSpaceChargePush.cpp Outdated Show resolved Hide resolved

src/particles/spacecharge/EnvelopeSpaceChargePush.cpp Outdated Show resolved Hide resolved

cemitch99 and others added 3 commits February 10, 2025 19:07

Update EnvelopeSpaceChargePush.H

862d53e

Co-authored-by: Axel Huebl <[email protected]>

Update EnvelopeSpaceChargePush.cpp

5925584

Co-authored-by: Axel Huebl <[email protected]>

Update EnvelopeSpaceChargePush.cpp

25f9185

Co-authored-by: Axel Huebl <[email protected]>

ax3l reviewed Feb 11, 2025

View reviewed changes

src/particles/spacecharge/EnvelopeSpaceChargePush.cpp Outdated Show resolved Hide resolved

ax3l reviewed Feb 11, 2025

View reviewed changes

src/particles/spacecharge/EnvelopeSpaceChargePush.H Outdated Show resolved Hide resolved

src/particles/spacecharge/EnvelopeSpaceChargePush.cpp Outdated Show resolved Hide resolved

src/tracking/envelope.cpp Outdated Show resolved Hide resolved

cemitch99 and others added 8 commits February 11, 2025 10:01

Apply suggestions from code review

8130f43

Co-authored-by: Axel Huebl <[email protected]>

[pre-commit.ci] pre-commit autoupdate (BLAST-ImpactX#839)

98a9fb1

updates: - [github.com/astral-sh/ruff-pre-commit: v0.9.4 → v0.9.6](astral-sh/ruff-pre-commit@v0.9.4...v0.9.6) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Doc: How-To Update (BLAST-ImpactX#838)

cd1d75c

Move "workflows" to "how-to guides" as in WarpX. Clean up some wording.

openPMD Beam Input via Source Element (BLAST-ImpactX#820)

d37f810

* `Source` Element for openPMD * Rename Source Files of `BeamMonitor` * Deduplicate openPMD Logic Helpers * Docs * Example * Doc: Fix Copy-Paste

Dashboard: Add tooltips (BLAST-ImpactX#843)

8f34ad6

* update dashboard __init__.py import * Add tooltips functionality to non-nested states * Add tooltips for the custom vselects * update type hints

Update Stub Files

41cd4b0

Remove AMREX_FORCE_INLINE

99f69b7

github-advanced-security bot found potential problems Feb 11, 2025

View reviewed changes

cemitch99 and others added 8 commits February 11, 2025 13:45

Add calculation of beam perveance.

1ea8528

Fix ParmParse.

dbf41d4

Update EnvelopeSpaceChargePush.cpp

0397587

Update InitDistribution.cpp

dd171b9

Merge branch 'development' into add_spch2D_envelope

6b1174e

Input file for benchmark example.

1878ab0

Correct perveance calculation. Hard-coded current for testing.

7c39662

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

04ba2ba

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

cemitch99 commented Feb 14, 2025

View reviewed changes

src/tracking/envelope.cpp Outdated Show resolved Hide resolved

cemitch99 and others added 2 commits February 14, 2025 10:18

Update benchmark example input files.

7018335

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

a7ee8b3

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

Update how_to_run table.

bfa2cdd

ax3l reviewed Feb 20, 2025

View reviewed changes

ax3l self-assigned this Feb 20, 2025

ax3l added 4 commits February 20, 2025 15:23

Verbatim

0a6fd03

CMake: Rename Examples

4692d4e

CMake: Remove Empty Command

cc17e57

Readme Formatting & Link

b17c29a

ax3l reviewed Feb 20, 2025

View reviewed changes

ax3l and others added 2 commits February 20, 2025 15:55

Apply Changes from Review, Fix Tests

b922ed4

Update benchmark README.

865cbd1

ax3l force-pushed the add_spch2D_envelope branch 2 times, most recently from 04dd198 to e45cafd Compare February 21, 2025 08:24

github-advanced-security bot found potential problems Feb 21, 2025

View reviewed changes

cemitch99 commented Feb 21, 2025

View reviewed changes

Python: Envelope Class

0d04230

ax3l force-pushed the add_spch2D_envelope branch 2 times, most recently from 3acf310 to 716c149 Compare February 21, 2025 19:19

Backwards Compatible algo.space_charge evolution

6e65816

ax3l force-pushed the add_spch2D_envelope branch from 716c149 to 6e65816 Compare February 21, 2025 19:26

Update all Examples

b23c9af

ax3l reviewed Feb 21, 2025

View reviewed changes

src/tracking/particles.cpp Outdated Show resolved Hide resolved

ax3l reviewed Feb 21, 2025

View reviewed changes

src/tracking/envelope.cpp Outdated Show resolved Hide resolved

ax3l reviewed Feb 21, 2025

View reviewed changes

src/tracking/envelope.cpp Show resolved Hide resolved

ax3l reviewed Feb 21, 2025

View reviewed changes

src/tracking/particles.cpp Show resolved Hide resolved

ax3l added 2 commits February 24, 2025 10:08

Improve Status Print

6ddd63e

And add doxygen and improve case matching.

Envelope: Warn on Zero Current (2D SC)

65dd9d6

ax3l approved these changes Feb 24, 2025

View reviewed changes

ax3l enabled auto-merge (squash) February 24, 2025 18:26

ax3l merged commit e670d0e into BLAST-ImpactX:development Feb 24, 2025
15 of 16 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Space charge 2D envelope push #841

Space charge 2D envelope push #841

cemitch99 commented Feb 11, 2025 •

edited by ax3l

Loading

ax3l left a comment

ax3l Feb 20, 2025

cemitch99 Feb 21, 2025

ax3l Feb 21, 2025

ax3l Feb 21, 2025 •

edited

Loading

cemitch99 Feb 21, 2025

ax3l Feb 21, 2025

cemitch99 Feb 21, 2025

ax3l Feb 21, 2025

ax3l Feb 21, 2025

		//pp_dist.get("charge", intensity);
		//amr_data->track_envelope.m_env = impactx::initialization::create_envelope(dist, intensity);

Space charge 2D envelope push #841

Space charge 2D envelope push #841

Conversation

cemitch99 commented Feb 11, 2025 • edited by ax3l Loading

ax3l left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ax3l Feb 21, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cemitch99 commented Feb 11, 2025 •

edited by ax3l

Loading

ax3l Feb 21, 2025 •

edited

Loading