Merge branch 'development' into add_spch2D_envelope

CMakeLists.txt

@@ -1,7 +1,7 @@
 # Preamble ####################################################################
 #
 cmake_minimum_required(VERSION 3.24.0)
-project(ImpactX VERSION 25.01)
+project(ImpactX VERSION 25.02)
 
 include(${ImpactX_SOURCE_DIR}/cmake/ImpactXFunctions.cmake)
 

cmake/dependencies/ABLASTR.cmake

@@ -128,7 +128,7 @@ macro(find_ablastr)
         set(COMPONENT_DIM 3D)
         set(COMPONENT_PRECISION ${ImpactX_PRECISION} P${ImpactX_PRECISION})
 
-        find_package(ABLASTR 25.01 CONFIG REQUIRED COMPONENTS ${COMPONENT_DIM})
+        find_package(ABLASTR 25.02 CONFIG REQUIRED COMPONENTS ${COMPONENT_DIM})
         message(STATUS "ABLASTR: Found version '${ABLASTR_VERSION}'")
     endif()
 
@@ -162,7 +162,7 @@ set(ImpactX_openpmd_src ""
 set(ImpactX_ablastr_repo "https://github.com/ECP-WarpX/WarpX.git"
     CACHE STRING
     "Repository URI to pull and build ABLASTR from if(ImpactX_ablastr_internal)")
-set(ImpactX_ablastr_branch "958a39463c9e3fea0bbe1da0306104ccf9a2164c"
+set(ImpactX_ablastr_branch "25.02"
     CACHE STRING
     "Repository branch for ImpactX_ablastr_repo if(ImpactX_ablastr_internal)")
 

cmake/dependencies/pyAMReX.cmake

@@ -59,7 +59,7 @@ function(find_pyamrex)
         endif()
     elseif(NOT ImpactX_pyamrex_internal)
         # TODO: MPI control
-        find_package(pyAMReX 25.01 CONFIG REQUIRED)
+        find_package(pyAMReX 25.02 CONFIG REQUIRED)
         message(STATUS "pyAMReX: Found version '${pyAMReX_VERSION}'")
     endif()
 endfunction()
@@ -74,7 +74,7 @@ option(ImpactX_pyamrex_internal "Download & build pyAMReX" ON)
 set(ImpactX_pyamrex_repo "https://github.com/AMReX-Codes/pyamrex.git"
     CACHE STRING
     "Repository URI to pull and build pyamrex from if(ImpactX_pyamrex_internal)")
-set(ImpactX_pyamrex_branch "458c9ae7ab3cd4ca4e4e9736e82c60f9a7e7606c"
+set(ImpactX_pyamrex_branch "25.02"
     CACHE STRING
     "Repository branch for ImpactX_pyamrex_repo if(ImpactX_pyamrex_internal)")
 

docs/source/conf.py

@@ -81,9 +81,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "25.01"
+version = "25.02"
 # The full version, including alpha/beta/rc tags.
-release = "25.01"
+release = "25.02"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

setup.py

@@ -230,7 +230,7 @@ def build_extension(self, ext):
 setup(
     name="impactx",
     # note PEP-440 syntax: x.y.zaN but x.y.z.devN
-    version="25.01",
+    version="25.02",
     packages=["impactx"],
     # Python sources:
     package_dir={"": "src/python"},

src/particles/spacecharge/CMakeLists.txt

@@ -2,6 +2,7 @@ target_sources(lib
   PRIVATE
     ForceFromSelfFields.cpp
     GatherAndPush.cpp
+    HandleSpacecharge.cpp
     PoissonSolve.cpp
     EnvelopeSpaceChargePush.cpp
 )

src/particles/spacecharge/ForceFromSelfFields.H

@@ -19,7 +19,7 @@
 #include <unordered_map>
 
 
-namespace impactx::spacecharge
+namespace impactx::particles::spacecharge
 {
     /** Calculate the space charge force field from the electric potential
      *
@@ -36,6 +36,6 @@ namespace impactx::spacecharge
         const amrex::Vector<amrex::Geometry>& geom
     );
 
-} // namespace impactx
+}  // namespace impactx::particles::spacecharge
 
 #endif // IMPACTX_FORCEFROMSELFFIELDS_H

src/particles/spacecharge/ForceFromSelfFields.cpp

@@ -14,7 +14,7 @@
 #include <AMReX_SPACE.H>      // for AMREX_D_DECL
 
 
-namespace impactx::spacecharge
+namespace impactx::particles::spacecharge
 {
     void ForceFromSelfFields (
         std::unordered_map<int, std::unordered_map<std::string, amrex::MultiFab> > & space_charge_field,
@@ -60,4 +60,4 @@ namespace impactx::spacecharge
             }
         }
     }
-} // namespace impactx::spacecharge
+}  // namespace impactx::particles::spacecharge

src/particles/spacecharge/GatherAndPush.H

@@ -20,7 +20,7 @@
 #include <string>
 
 
-namespace impactx::spacecharge
+namespace impactx::particles::spacecharge
 {
     /** Gather force fields and push particles in x,y,z
      *
@@ -41,6 +41,6 @@ namespace impactx::spacecharge
         amrex::ParticleReal slice_ds
     );
 
-} // namespace impactx
+}  // namespace impactx::particles::spacecharge
 
 #endif // IMPACTX_GATHER_AND_PUSH_H

src/particles/spacecharge/GatherAndPush.cpp

@@ -16,7 +16,7 @@
 #include <AMReX_SPACE.H>      // for AMREX_D_DECL
 
 
-namespace impactx::spacecharge
+namespace impactx::particles::spacecharge
 {
     void GatherAndPush (
         ImpactXParticleContainer & pc,
@@ -105,4 +105,4 @@ namespace impactx::spacecharge
             } // end loop over all particle boxes
         } // env mesh-refinement level loop
     }
-} // namespace impactx::spacecharge
+}  // namespace impactx::particles::spacecharge

src/particles/spacecharge/HandleSpacecharge.H

@@ -0,0 +1,38 @@
+/* Copyright 2022-2025 The Regents of the University of California, through Lawrence
+ *           Berkeley National Laboratory (subject to receipt of any required
+ *           approvals from the U.S. Dept. of Energy). All rights reserved.
+ *
+ * This file is part of ImpactX.
+ *
+ * Authors: Axel Huebl, Chad Mitchell
+ * License: BSD-3-Clause-LBNL
+ */
+#ifndef IMPACTX_HANDLE_SPACECHARGE_H
+#define IMPACTX_HANDLE_SPACECHARGE_H
+
+#include "initialization/AmrCoreData.H"
+
+#include <AMReX_REAL.H>
+
+#include <functional>
+#include <memory>
+
+
+namespace impactx::particles::spacecharge
+{
+    /** Function to handle space charge including charge deposition, Poisson solve,
+     * field calculation, interpolation, and particle push.
+     *
+     * @param[in,out] amr_data AMR data like particle container and fields
+     * @param[in] ResizeMesh function to call to resize the mesh
+     * @param[in] slice_ds slice spacing along s
+     */
+    void HandleSpacecharge (
+        std::unique_ptr<initialization::AmrCoreData> & amr_data,
+        std::function<void()> ResizeMesh,
+        amrex::Real slice_ds
+    );
+
+} // namespace impactx::particles::spacecharge
+
+#endif // IMPACTX_HANDLE_SPACECHARGE_H

src/particles/spacecharge/HandleSpacecharge.cpp

@@ -0,0 +1,108 @@
+/* Copyright 2022-2025 The Regents of the University of California, through Lawrence
+ *           Berkeley National Laboratory (subject to receipt of any required
+ *           approvals from the U.S. Dept. of Energy). All rights reserved.
+ *
+ * This file is part of ImpactX.
+ *
+ * Authors: Axel Huebl, Chad Mitchell
+ * License: BSD-3-Clause-LBNL
+ */
+#include "HandleSpacecharge.H"
+
+#include "initialization/AmrCoreData.H"
+#include "particles/ImpactXParticleContainer.H"
+#include "particles/spacecharge/ForceFromSelfFields.H"
+#include "particles/spacecharge/GatherAndPush.H"
+#include "particles/spacecharge/PoissonSolve.H"
+#include "particles/transformation/CoordinateTransformation.H"
+
+#include <AMReX_ParmParse.H>
+#include <AMReX_REAL.H>
+
+#include <memory>
+
+
+namespace impactx::particles::spacecharge
+{
+    void HandleSpacecharge (
+        std::unique_ptr<initialization::AmrCoreData> & amr_data,
+        std::function<void()> ResizeMesh,
+        amrex::Real slice_ds
+    )
+    {
+        BL_PROFILE("impactx::particles::wakefields::HandleSpacecharge")
+
+        amrex::ParmParse const pp_algo("algo");
+        bool space_charge = false;
+        pp_algo.query("space_charge", space_charge);
+
+        // turn off if disabled by user
+        if (!space_charge) { return; }
+
+        // turn off if less than 2 particles
+        if (amr_data->track_particles.m_particle_container->TotalNumberOfParticles(true, false) < 2) { return; }
+
+        // transform from x',y',t to x,y,z
+        transformation::CoordinateTransformation(
+            *amr_data->track_particles.m_particle_container,
+            CoordSystem::t
+        );
+
+        // Note: The following operation assume that
+        // the particles are in x, y, z coordinates.
+
+        // Resize the mesh, based on `amr_data->track_particles.m_particle_container` extent
+        ResizeMesh();
+
+        // Redistribute particles in the new mesh in x, y, z
+        amr_data->track_particles.m_particle_container->Redistribute();
+
+        // charge deposition
+        amr_data->track_particles.m_particle_container->DepositCharge(
+            amr_data->track_particles.m_rho,
+            amr_data->refRatio()
+        );
+
+        // poisson solve in x,y,z
+        spacecharge::PoissonSolve(
+            *amr_data->track_particles.m_particle_container,
+            amr_data->track_particles.m_rho,
+            amr_data->track_particles.m_phi,
+            amr_data->refRatio()
+        );
+
+        // calculate force in x,y,z
+        spacecharge::ForceFromSelfFields(
+            amr_data->track_particles.m_space_charge_field,
+            amr_data->track_particles.m_phi,
+            amr_data->Geom()
+        );
+
+        // gather and space-charge push in x,y,z , assuming the space-charge
+        // field is the same before/after transformation
+        // TODO: This is currently using linear order.
+        spacecharge::GatherAndPush(
+            *amr_data->track_particles.m_particle_container,
+            amr_data->track_particles.m_space_charge_field,
+            amr_data->Geom(),
+            slice_ds
+        );
+
+        // transform from x,y,z to x',y',t
+        transformation::CoordinateTransformation(
+            *amr_data->track_particles.m_particle_container,
+            CoordSystem::s
+        );
+
+        // for later: original Impact implementation as an option
+        // Redistribute particles in x',y',t
+        //   TODO: only needed if we want to gather and push space charge
+        //         in x',y',t
+        //   TODO: change geometry beforehand according to transformation
+        //m_amr_data->track_particles.m_particle_container->Redistribute();
+        //
+        // in original Impact, we gather and space-charge push in x',y',t ,
+        // assuming that the distribution did not change
+    }
+
+} // namespace impactx::particles::spacecharge

src/particles/spacecharge/PoissonSolve.H

@@ -17,7 +17,7 @@
 #include <unordered_map>
 
 
-namespace impactx::spacecharge
+namespace impactx::particles::spacecharge
 {
     /** Calculate the electric potential from charge density
      *
@@ -36,6 +36,6 @@ namespace impactx::spacecharge
         amrex::Vector<amrex::IntVect> rel_ref_ratio
     );
 
-} // namespace impactx
+} // namespace impactx::particles::spacecharge
 
 #endif // IMPACTX_POISSONSOLVE_H

src/particles/spacecharge/PoissonSolve.cpp

@@ -21,7 +21,7 @@
 #include <cmath>
 
 
-namespace impactx::spacecharge
+namespace impactx::particles::spacecharge
 {
     void PoissonSolve (
         ImpactXParticleContainer const & pc,
@@ -121,4 +121,4 @@ namespace impactx::spacecharge
             phi_at_level.FillBoundary(pc.GetParGDB()->Geom()[lev].periodicity());
         }
     }
-} // impactx::spacecharge
+}  // impactx::particles::spacecharge

src/python/impactx/__init__.pyi

@@ -81,7 +81,7 @@ __author__: str = (
     "Axel Huebl, Chad Mitchell, Ryan Sandberg, Marco Garten, Ji Qiang, et al."
 )
 __license__: str = "BSD-3-Clause-LBNL"
-__version__: str = "25.01"
+__version__: str = "25.02"
 s: impactx_pybind.CoordSystem  # value = <CoordSystem.s: 0>
 t: impactx_pybind.CoordSystem  # value = <CoordSystem.t: 1>
 cxx = impactx_pybind

src/python/impactx/dashboard/Input/components.py

@@ -6,6 +6,9 @@
 
 server, state, ctrl = setup_server()
 
+state.documentation_drawer_open = False
+state.documentation_url = ""
+
 
 class CardComponents:
     """
@@ -41,7 +44,7 @@ def documentation_icon(section_name: str) -> vuetify.VIcon:
         return vuetify.VIcon(
             "mdi-information",
             style="color: #00313C;",
-            click=lambda: generalFunctions.documentation(section_name),
+            click=lambda: generalFunctions.open_documentation(section_name),
         )
 
     @staticmethod
@@ -187,3 +190,21 @@ def create_dialog_tabs(name: str, num_tabs: int, tab_names: list[str]) -> None:
                 for tab_name in tab_names:
                     vuetify.VTab(tab_name)
             vuetify.VDivider()
+
+    @staticmethod
+    def create_documentation_drawer():
+        with vuetify.VNavigationDrawer(
+            v_model=("documentation_drawer_open",),
+            absolute=True,
+            right=True,
+            hide_overlay=True,
+            style="width: 30vw; top: 64px !important;  position: fixed;",
+        ):
+            with vuetify.VContainer(
+                fluid=True,
+                classes="pa-0 fill-height",
+            ):
+                html.Iframe(
+                    src=("documentation_url",),
+                    style="width: 100%; height: 100%; border: none;",
+                )

src/python/impactx/dashboard/Input/defaults.py

@@ -119,6 +119,14 @@ class DashboardDefaults:
         "emitt": "m",
     }
 
+    DOCUMENTATION = {
+        "input_parameters": "https://impactx.readthedocs.io/en/latest/usage/python.html#impactx.ImpactX",
+        "lattice_configuration": "https://impactx.readthedocs.io/en/latest/usage/python.html#lattice-elements",
+        "distribution_parameters": "https://impactx.readthedocs.io/en/latest/usage/python.html#initial-beam-distributions",
+        "space_charge": "https://impactx.readthedocs.io/en/latest/usage/parameters.html#space-charge",
+        "csr": "https://impactx.readthedocs.io/en/latest/usage/parameters.html#coherent-synchrotron-radiation-csr",
+    }
+
 
 class TooltipDefaults:
     """