Merge branch 'development' into dependencies_pybind11_picmistandard

Author: EZoni

.pre-commit-config.yaml

@@ -65,15 +65,15 @@ repos:
 
 # C++ formatting
 - repo: https://github.com/pre-commit/mirrors-clang-format
-  rev: v21.1.2
+  rev: v21.1.5
   hooks:
   - id: clang-format
     files: '^Source/main.cpp'
 
 # Python: Ruff linter & formatter
 #   https://docs.astral.sh/ruff/
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.14.3
+  rev: v0.14.5
   hooks:
     # Run the linter
     - id: ruff

Docs/source/acknowledge_us.rst

@@ -116,7 +116,7 @@ If your project leads to a scientific publication, please consider citing all Wa
               howpublished = {https://blast-warpx.github.io}
            }
 
-Since the WarpX is an actively evolving project, a specific version might be used in your work to ensure reproducibility. You can select a *version-specific DOI* from the `release page <https://github.com/BLAST-WarpX/warpx/releases>`__ and add the version number to the cited title, e.g. for version ``25.10``:
+Since WarpX is an actively evolving project, a specific version might be used in your work to ensure reproducibility. You can select a *version-specific DOI* from the `release page <https://github.com/BLAST-WarpX/warpx/releases>`__ and add the version number to the cited title, e.g. for version ``25.10``:
 
 .. tab-set::
 

Docs/source/highlights.rst

@@ -100,6 +100,11 @@ Laser-Plasma Interaction
 
 Scientific works in laser-ion acceleration and laser-matter interaction.
 
+#. Lei B, Zhang H, Seipt D, Bonatto A, Qiao B, Resta-López J, Xia G, and Welsch C.
+   **Coherent Synchrotron Radiation by Excitation of Surface Plasmon Polariton on Near-Critical Solid Microtube Surface**.
+   Phys. Rev. Lett. **135**, 205001, 2025.
+   `DOI:10.1103/cnym-16hc <https://doi.org/10.1103/cnym-16hc>`__
+
 #. Garten M, Bulanov S S, Hakimi S, Obst-Huebl L, Mitchell C E, Schroeder C B, Esarey E, Geddes C G R, Vay J-L, Huebl A.
    **Laser-plasma ion beam booster based on hollow-channel magnetic vortex acceleration**.
    Physical Review Research **6**, 033148, 2024.

Docs/source/usage/parameters.rst

@@ -16,6 +16,7 @@ This section collects typical user workflows and best practices for WarpX.
    workflows/generate_lookup_tables_with_tools
    workflows/plot_timestep_duration
    workflows/psatd_stencil
+   workflows/stl_geometry_preparation
    workflows/archiving
    workflows/ml_dataset_training
    workflows/optimas

Docs/source/usage/workflows.rst

@@ -0,0 +1,144 @@
+.. _workflows-stl-geometry-preparation:
+
+STL Geometry Preparation for WarpX
+==================================
+
+WarpX has the ability to define the embedded boundary (EB) in a simulation using externally provided STL (STereoLithography) files.
+STL files are a common format for representing 3D geometries and can be used to define complex embedded boundaries in WarpX simulations, without having to define extensive EB implicit functions.
+However, there are some limitations to using STL files which must be resolved, including:
+
+1. Multiple STL files representing different parts of a device must be combined into a single file
+2. The STL geometry is "watertight" (The STL file shouldn't have duplicate faces or vertices, overlapping vertices should be merged, and there shouldn't be any gaps or holes in the mesh)
+3. The STL file is properly formatted for WarpX input
+
+.. 2. The STL file shouldn't have duplicate faces or vertices, and overlapping vertices should be merged. (issues with vertices can cause the MLMG solver to crash)
+
+Step 1: Combining Multiple STL Files
+------------------------------------
+
+If your device consists of multiple parts stored in separate STL files, you'll need to combine them into a single STL file.
+
+Using MeshLab
+^^^^^^^^^^^^^
+
+`MeshLab <https://www.meshlab.net/>`__ is a free, open-source tool for processing 3D meshes:
+
+1. Open MeshLab
+2. Import the first STL file: ``File -> Import Mesh``
+3. Import additional STL files: ``File -> Import Mesh`` (repeat for each file)
+4. All parts should now be visible in the same scene
+5. Create a union of the two parts, either by ``Filters -> Remeshing, Simplification and Reconstruction -> Mesh Boolean: Union``
+   or by right-clicking on one of the parts in the Layer Dialog panel on the right and clicking ``Mesh Boolean: Union``
+6. Select the union and export the combined mesh: ``File -> Export Mesh As``
+7. Choose STL format and save
+
+Using Python with trimesh
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also use Python with the `trimesh <https://github.com/mikedh/trimesh>`__ library:
+
+.. code-block:: python
+
+   import trimesh
+
+   # Load individual STL files
+   mesh1 = trimesh.load('part1.stl')
+   mesh2 = trimesh.load('part2.stl')
+
+   # Combine meshes
+   combined = trimesh.util.concatenate([mesh1, mesh2])
+
+   # Export combined mesh
+   combined.export('device_combined.stl')
+
+Step 2: Making the Geometry Watertight and Removing and Merging Duplicate Faces and Vertices
+---------------------------------------------------------------------------------------------------
+
+
+WarpX requires that STL geometries be "watertight" (manifold), meaning the mesh has no holes, gaps, or open edges.
+This ensures that WarpX can properly determine which regions are inside or outside the geometry.
+STL files that have overlapping or duplicate faces and vertices can cause the MLMG solver to crash, while a non-manifold file can be inherently leaky for Poynting flux in an EM simulation.
+These issues with the mesh might happen while exporting the STL file from a CAD program (such as SolidWorks)
+
+Using MeshLab
+^^^^^^^^^^^^^
+
+To check and repair a mesh in MeshLab:
+
+1. **Check for issues:**
+
+   * ``Filters -> Quality Measure and Computations -> Compute Topological Measures``
+   * Look for holes in the output
+   * Look for non-manifold edges and vertices in the output
+
+2. **Repair the mesh:**
+
+   * When loading in the mesh, there is an option to ``Unify Duplicated Vertices in STL files``, this will perform the next steps automatically, but gives the user less control.
+   * ``Filters -> Cleaning and Repairing -> Remove Duplicate Faces``
+   * ``Filters -> Cleaning and Repairing -> Remove Duplicate Vertices``
+   * ``Filters -> Cleaning and Repairing -> Merge Close Vertices``
+
+      * This filter gives the user an option to set an absolute or relative tolerance on the distance between the vertices to merge.
+
+   .. * ``Filters -> Cleaning and Repairing -> Remove Zero Area Faces``
+   .. * ``Filters -> Remeshing, Simplification and Reconstruction -> Close Holes``
+
+3. **Verify the mesh is watertight:**
+
+   * Run ``Filters -> Quality Measure and Computations -> Compute Topological Measures`` again
+   * Check that the mesh has no holes
+   * Check that the mesh is manifold (no warnings about non-manifold edges)
+
+      * An STL file with non-manifold edges won't necessarily crash a simulation, but may present other numerical issues.
+
+
+
+
+Step 3: Using STL Files in WarpX
+--------------------------------
+
+Once you have a single, watertight STL file, you can use it in WarpX by setting the following parameters in your input file:
+
+.. code-block:: text
+
+   # Specify that the embedded boundary comes from an STL file
+   eb2.geom_type = stl
+
+   # Path to your STL file
+   eb2.stl_file = path/to/device_watertight.stl
+
+You can also optionally set an electric potential on the embedded boundary:
+
+.. code-block:: text
+
+   # Define electric potential at the embedded boundary (optional)
+   warpx.eb_potential(x,y,z,t) = "voltage_function"
+
+For more details on embedded boundary parameters, see:
+
+* `Embedded Boundary Input Parameters <https://warpx.readthedocs.io/en/latest/usage/parameters.html#embedded-boundary-conditions:~:text=in%20this%20case.-,Embedded%20Boundary%20Conditions,-%EF%83%81>`__
+* `Embedded Boundary PICMI Input Parameters <https://warpx.readthedocs.io/en/latest/usage/python.html#pywarpx.picmi.EmbeddedBoundary:~:text=Custom%20class%20to,translated%20and%20inverted.>`__
+
+Tips and Best Practices
+-----------------------
+
+* *Units:* Ensure your STL file uses the same unit system as your WarpX simulation
+* *Scale:* If needed, scale your geometry in your CAD software or mesh editor before exporting
+* *Orientation:* Check that your geometry is properly oriented relative to WarpX's coordinate system
+* *Resolution:* The STL mesh resolution should be appropriate for your simulation - too coarse may miss important features, too fine may slow down initialization
+
+      * It's generally a good idea to simplify your geometery and remove features that are significantly smaller than the WarpX simulation grid
+
+* *Binary vs ASCII:* WarpX can read both binary and ASCII STL files, but binary files are typically smaller and faster to load
+
+
+Examples
+--------
+
+.. note::
+
+   **TODO**: WarpX does not yet have examples that use STL files for embedded boundaries.
+
+   Current embedded boundary examples in ``Examples/Tests/embedded_boundary_*`` use analytical
+   functions to define geometries. A complete example demonstrating STL file usage will be
+   added in the future.

Docs/source/usage/workflows/stl_geometry_preparation.rst

@@ -84,3 +84,4 @@ add_subdirectory(single_particle)
 add_subdirectory(space_charge_initialization)
 add_subdirectory(subcycling)
 add_subdirectory(vay_deposition)
+add_subdirectory(virtual_photons)

Examples/Tests/CMakeLists.txt

@@ -0,0 +1,12 @@
+# Add tests (alphabetical order) ##############################################
+#
+
+add_warpx_test(
+    test_3d_virtual_photons  # name
+    3  # dims
+    1  # nprocs
+    inputs_test_3d_virtual_photons  # inputs
+    analysis_virtual_photons.py  # analysis
+    "analysis_default_regression.py --path diags/diag1"  # checksum
+    OFF  # dependency
+)

Examples/Tests/virtual_photons/CMakeLists.txt

@@ -0,0 +1 @@
+../../analysis_default_regression.py

Examples/Tests/virtual_photons/analysis_default_regression.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+
+# This test generates the population of virtual photons
+# of one high-energy electron.
+# The total number and spectrum of the virtual photons are
+# compared to the theoretical prediction.
+# Checks that the photons are in the same position of the electron.
+
+import matplotlib.pyplot as plt
+import numpy as np
+from numpy import log
+from openpmd_viewer import OpenPMDTimeSeries
+from scipy.constants import alpha, c, eV, m_e, pi
+
+###########################
+### ENERGY AND SPECTRUM ###
+###########################
+
+# useful constants
+GeV = 1e9 * eV
+
+# electron energy
+energy = 125 * GeV
+
+# virtual photons min energy
+hw_min = 1e-12 * m_e * c**2
+
+# min fractional energy of the virtual photon wrt electron energy
+ymin = hw_min / energy
+
+#############
+### WarpX ###
+#############
+
+series = OpenPMDTimeSeries("./diags/diag1/")
+sampling_factor = 1e7
+uz_virtual_photons, w_virtual_photons = series.get_particle(
+    ["uz", "w"], species="virtual_photons", iteration=1
+)
+w_electrons = series.get_particle(["w"], species="beam", iteration=1)
+
+# fractional photon energy (photon energy / electron energy)
+y_warpx = uz_virtual_photons * c / energy
+
+# bins for the fractional photon energy
+y = np.geomspace(ymin, 1, 401)
+
+# number of virtual photons per electron obtained with WarpX
+N_warpx = np.sum(w_virtual_photons) / np.sum(w_electrons)
+
+# spectrum of the virtual photons per electron
+H, b = np.histogram(y_warpx, bins=y, weights=w_virtual_photons)
+db = np.diff(b)
+b = 0.5 * (b[1:] + b[:-1])
+dN_dy_warpx = H / db / np.sum(w_electrons)
+
+##############
+### Theory ###
+##############
+
+y = b
+# spectrum of virtual photons for one electron
+dN_dy_theory = alpha / pi / y * (-2 * log(y))
+# dN_dy[dN_dy < 0] = 0.0
+
+# number of virtual photons for one electron from theory
+N_theory = alpha / pi * log(ymin) ** 2
+
+############
+### Plot ###
+############
+
+fig, ax = plt.subplots(ncols=1, nrows=1, figsize=(5, 4), dpi=200)
+ax.plot(y, dN_dy_theory, color="black", lw=6, label="theory")
+ax.plot(y, dN_dy_warpx, color="dodgerblue", lw=4, label="WarpX")
+ax.legend()
+ax.set_yscale("log")
+ax.set_xscale("log")
+ax.set_xlabel("Fractional photon energy")
+ax.set_ylabel("dN/dy")
+ax.set_title("Virtual photons spectrum")
+fig.savefig("spectrum_virtual_photons.png")
+
+#############
+### Error ###
+#############
+
+number_rel_error = np.abs(N_warpx - N_theory) / N_theory
+spectrum_rel_error = np.abs(dN_dy_warpx - dN_dy_theory) / dN_dy_theory
+
+print("Number of virtual photons per electron:")
+print(f"From simulation : {N_warpx}")
+print(f"From theory     : {N_theory}")
+print(f"Relative error  : {number_rel_error:.4%}")
+
+print("Spectrum of virtual photons per electron:")
+print(f"Max relative error: {spectrum_rel_error.max()}")
+
+assert number_rel_error < 0.02
+assert (spectrum_rel_error < 0.04).all()
+
+################
+### Position ###
+################
+
+x, y, z = series.get_particle(["x", "y", "z"], species="virtual_photons", iteration=1)
+x_e, y_e, z_e = series.get_particle(["x", "y", "z"], species="beam", iteration=1)
+
+assert np.unique(x) == x_e
+assert np.unique(y) == y_e
+assert np.unique(z) == z_e