Implement PICMI capability for TWTS and TWEAC lasers #5561

BeyondEspresso · 2025-11-28T10:17:56Z

This draft of a PR implements PICMI capability for TWTS and TWEAC lasers. It successfully runs and builds the Laser-wakefield PICMI example using:

laser_duration = 30.0e-15 / 2.35482
pulse_init = 15.0
laser_focal_position=[
    float(numberCells[0] * cellSize[0] / 2.0),
    4.62e-5,
    float(numberCells[2] * cellSize[2] / 2.0),
]
laser = picmi.TWTSLaser(
    wavelength=0.8e-6,
    waist=1.2e-6 / 1.17741,
    duration=laser_duration,
    focal_position=laser_focal_position,
    centroid_position=[
        float(numberCells[0] * cellSize[0] / 2.0),
        -0.5 * pulse_init * laser_duration * c,
        float(numberCells[2] * cellSize[2] / 2.0),
    ],
    focus_z_offset_si=laser_focal_position[2] - float(numberCells[2] * cellSize[2] / 2.0),
    a0=8.0,
    phi=5.0 * np.pi / 180.0,
    beta0=1.0,
    polarizationAngle=45.0 * np.pi / 180.0
)

As already mentioned, this PR should be still considered a draft, but feedback is welcome!

Current working items and/or questions are:

Include metadata routines.
Is the use of the laser profile free still appropriate?
How shall we integrate the functionality with centroid_position and focal_position? The semantics is not very intuitive for TWTS lasers here.
Is the approach for conditional laser insertion at ZMIN and ZMAX good?
Are the schema and requirements OK or still "wild"?
The traditional laser profile usage pattern suggests further refactoring of the TWTSTight laser by outsourcing the unit rescaling to unitless param-structs. However, this also affects unit-tests.
The focus_z_offset_si parameter shows a slight clash of philosophies between a param-file-centered and a PICMI-python-centered workflow, as for PICMI it is much easier to parameterize absolute focal positions in contrast to positions relative to the center of the simulation domain.

PrometheusPi · 2025-11-28T14:52:21Z

@BeyondEspresso The CI is seeing compile time errors with your TWTS implementation. For details please see CI log. Seems to be related to how you access fields.

BeyondEspresso · 2025-11-30T16:35:22Z

@PrometheusPi Thanks, I fixed a compile-time bug in the 2D branch.
if constexpr(simDim == DIM3) laserOrigin.z() += float_X(focus_z_offset_SI / cellDimensions.z());
became
if constexpr(simDim == DIM3) laserOrigin[simDim - 1] += float_X(focus_z_offset_SI / cellDimensions[simDim - 1]);

PrometheusPi

Minor changes required and some questions.

PrometheusPi · 2025-12-01T06:20:14Z

include/picongpu/fields/background/templates/twtstight/getFieldPositions_SI.tpp

                    floatD_X laserOrigin = precisionCast<float_X>(halfSimSize);
                    laserOrigin.y() = float_X(focus_y_SI / cellDimensions.y());
                    if constexpr(simDim == DIM3)
-                        laserOrigin.z() += float_X(focus_z_offset_SI / cellDimensions.z());


@psychocoderHPC why does the original version seems not to work?

The compiler does attempt a name lookup despite the compile-time condition. Since the .z() do not exist in 2D, this throws an error.

PrometheusPi · 2025-12-01T06:22:36Z

share/picongpu/pypicongpu/schema/laser.TWTSLaser.json

+      "exclusiveMinimum": 0
+    },
+    "pulse_init": {
+      "description": " The laser pulse will be initialized pulse_init times of the pulse_duration_si",


Suggested change

"description": " The laser pulse will be initialized pulse_init times of the pulse_duration_si",

"description": "The laser pulse will be initialized pulse_init times of the pulse_duration_si",

PrometheusPi · 2025-12-01T06:22:56Z

share/picongpu/pypicongpu/schema/laser.TWTSLaser.json

+    },
+    "pulse_duration_si": {
+      "type": "number",
+      "description": "sigma of std. gauss for intensity (E^2) [s]",


Suggested change

"description": "sigma of std. gauss for intensity (E^2) [s]",

"description": "sigma of std. Gauss for intensity (E^2) [s]",

PrometheusPi · 2025-12-01T06:23:26Z

share/picongpu/pypicongpu/schema/laser.TWTSLaser.json

+      }
+    },
+    "huygens_surface_positions": {
+      "description": "position of the huygens surface relative from domain boundaries",


Suggested change

"description": "position of the huygens surface relative from domain boundaries",

"description": "position of the Huygens surface relative from domain boundaries",

also fix it the original schema you copied them from.

PrometheusPi · 2025-12-01T06:33:30Z

lib/python/picongpu/picmi/lasers/twts_laser.py

+
+    - a0 : float, optional
+        Normalized vector potential at focus [dimensionless].
+        Specify either a0 or E0 (E0 takes precedence).


Does E0 take precedence, or is this an outdated comment? I added throwing an error if both were given for the Gauss and Dispersive pulse.

It is outdated. See here:

picongpu/lib/python/picongpu/picmi/lasers/base_laser.py

Lines 42 to 43 in 4a42ebb

if (E0 is not None) and (a0 is not None):

raise ValueError("Only one of E0 or a0 should be specified. You set both.")

Please update the comment.

PrometheusPi · 2025-12-01T06:40:47Z

lib/python/picongpu/picmi/lasers/twts_laser.py

+#   def check(self):
+#       self._validate_common_properties()


Please remove commented out code.

PrometheusPi · 2025-12-01T06:41:17Z

lib/python/picongpu/picmi/lasers/twts_laser.py

+        # self._validate_common_properties()
+        self.pulse_init = self._compute_pulse_init()
+
+    """PICMI object for TWTS Laser"""


Why do you have this comment (string) at the bottom of the code?

This was how it was structured for other PICMI lasers. However, I had to remove the general laser checks as they do not apply for TWTS lasers. These assume implicitly that lasers enter via the YMIN-plane and thus do not apply here.

PrometheusPi · 2025-12-01T06:44:58Z

share/picongpu/pypicongpu/template/include/picongpu/param/incidentField.param.mustache

+        static constexpr float_64 FOCUS_Y_SI = focus_position[1];//56.0e-6;
+        static constexpr float_64 FOCUS_Z_OFFSET_SI = {{{focus_z_offset_si}}};//8.0e-6;
+        static constexpr float_64 PHI = {{{phi}}};//5.0 * (PI / 180.);
+        static constexpr float_64 BETA_0 = 1.0;//{{{beta0}}};
+        static constexpr float_64 TDELAY = {{{time_offset_si}}};//124.535e-6 / sim.si.getSpeedOfLight();
+        static constexpr bool AUTO_TDELAY = false;
+        static constexpr float_X Polarization = {{{polarizationAngle}}};//45.10716816968629 * (PI / 180.);
+        static constexpr float_X windowStart = 0.0;
+        static constexpr float_X windowEnd = 10.0e+20;
+        static constexpr float_X windowLength = 10000.0;//10000.0;


Suggested change

static constexpr float_64 FOCUS_Y_SI = focus_position[1];//56.0e-6;

static constexpr float_64 FOCUS_Z_OFFSET_SI = {{{focus_z_offset_si}}};//8.0e-6;

static constexpr float_64 PHI = {{{phi}}};//5.0 * (PI / 180.);

static constexpr float_64 BETA_0 = 1.0;//{{{beta0}}};

static constexpr float_64 TDELAY = {{{time_offset_si}}};//124.535e-6 / sim.si.getSpeedOfLight();

static constexpr bool AUTO_TDELAY = false;

static constexpr float_X Polarization = {{{polarizationAngle}}};//45.10716816968629 * (PI / 180.);

static constexpr float_X windowStart = 0.0;

static constexpr float_X windowEnd = 10.0e+20;

static constexpr float_X windowLength = 10000.0;//10000.0;

static constexpr float_64 FOCUS_Y_SI = focus_position[1];

static constexpr float_64 FOCUS_Z_OFFSET_SI = {{{focus_z_offset_si}}}

static constexpr float_64 PHI = {{{phi}}};

static constexpr float_64 BETA_0 = {{{beta0}}};

static constexpr float_64 TDELAY = {{{time_offset_si}}};

static constexpr bool AUTO_TDELAY = false;

static constexpr float_X Polarization = {{{polarizationAngle}}};

static constexpr float_X windowStart = 0.0;

static constexpr float_X windowEnd = 10.0e+20;

static constexpr float_X windowLength = 10000.0;

There was some commented-out code left and I think beta0was never applied.

PrometheusPi · 2025-12-01T07:05:45Z

include/picongpu/fields/incidentField/profiles/TWTSPulse.def

+                constexpr float_X a0 = 0.3635819;
+                constexpr float_X a1 = 0.4891775;
+                constexpr float_X a2 = 0.1365995;
+                constexpr float_X a3 = 0.0106411;


What are these constants? Could you add a comment what these magic numbers represent?

This is the window type. I should add a comment.

PrometheusPi · 2025-12-01T07:07:09Z

include/picongpu/fields/incidentField/profiles/TWTSPulse.def

Why did you need to add this file? I thought we already have a TWTS implementation.

The one we have is only via background fields. There seems to be no incident field TWTS mainline yet. Correct @BeyondEspresso?

Rest of file looks okay - I have to trust @BeyondEspresso that the equations are correct. Perhaps @steindev could have a second look at this file.

@BeyondEspresso Since you added now this TWTS incident field pulse, please add the option to our incidentField.param files. E.g.

picongpu/include/picongpu/param/incidentField.param

Lines 36 to 37 in 4a42ebb

* - profiles::Wavepacket<> : wavepacket with Gaussian spatial and temporal envelope profile with given

* parameters

and the examples and tests.

The TWTS implementation can be used for both background and incidentFields. With TWTSPulse.def, I basically reduced the boiler plate code I had to include in the param-files production runs. The question here would be, whether a more extended version (not relying on the Free-profile and including metadata methods) should be included in this PR already or whether this can deferred to a later PR.

@PrometheusPi Just to clarify: we already have a working incident field implementation in mainline. The TWEAC-FOM setup also makes use of that. This change is about reducing boiler plate code and does not change any equations of the existing TWTSTight model.

chillenzer · 2025-12-01T07:31:36Z

share/picongpu/pypicongpu/template/include/picongpu/param/incidentField.param.mustache

+        static constexpr float_X windowStart = 0.0;
+        static constexpr float_X windowEnd = 10.0e+20;
+        static constexpr float_X windowLength = 10000.0;//10000.0;


Why are there hardcoded numbers here?

Only for initial testing, I will remove them an add these to the parameters.

chillenzer · 2025-12-01T07:36:28Z

lib/python/picongpu/picmi/lasers/twts_laser.py

+        else:
+            self.phiPos = False
+        self.beta0 = beta0
+        self.phi0 = 0.0


What's this? How is this different from phi?

phi0 is the phase inherited from BaseModel and has no function for TWTSTight. I set it to zero to show what it would be for TWTSTight. However, it would be straightforward and easy to add such a capability to the TWTSTight-interface.
phi is the laser incident angle and as such a different physics quantity. I want to keep the naming to remain consistent with all my other code.

I know you will hate that, but it might be better to use laserIncidentAngle as variable name instead of phi, much less likely to cause confusion with the myriad other phi-s already in use in PICMI.
In general I prefer immediately understandable names even though they are longer.

BrianMarre · 2025-12-01T14:02:00Z

lib/python/picongpu/picmi/lasers/twts_laser.py

+@typeguard.typechecked
+class TWTSLaser(BaseLaser):
+    """
+    Specifies a TWTS laser


what does TWTS stand for? Please add the full length form of the acronym at least one to the PICMI class definition to ensure that other users understand the difference to the other laser models.
It would also make sense to add one ore more reference and/or a short description of the TWTS laser model.

BrianMarre · 2025-12-01T14:04:24Z

lib/python/picongpu/picmi/lasers/twts_laser.py

+    - wavelength: float
+        Central wavelength of the laser [m].


Current form is fine, but I would prefer doxygen style parameter definitions. That will make it easier to autogenerate a API documentation later.

@BrianMarre @chillenzer We can use doxygen-style parameter definitions, but this is not yet used in our python code. Before I break some implicit design decision here, is there any style that we intend to enforce in the future?

I would argue for doxygen, no need to support two different tools for auto generating API documentation.

BrianMarre · 2025-12-01T14:10:33Z

lib/python/picongpu/picmi/lasers/twts_laser.py

+    - phi: float
+        Laser incident angle [rad]
+        denoting the mean laser phase propagation direction
+        with respect to the y-axis.


magical axis definition, either requires a fixed coordinate system or should be defined relative to something like the focus movement direction.
Please remember that we may not assume that the focus moves parallel to the y-direction in PICMI, since this might not be true in other PIC-codes.

BrianMarre · 2025-12-01T14:11:57Z

share/picongpu/pypicongpu/schema/laser.TWTSLaser.json

+    "waist_si",
+    "pulse_duration_si",
+    "focus_pos_si",
+    "phase",


I thought the TWTS laser does not support a phase?

psychocoderHPC · 2025-12-02T12:45:02Z

I converted the PR to draft to avoid merging accidentally

BeyondEspresso · 2025-12-05T09:48:31Z

@PrometheusPi @psychocoderHPC @BrianMarre @chillenzer Thanks for your feedback. In this update I included all suggestions except for the doxygen-style comments in order to avoid breaking style with the other existing python-scripts. In particular, the refactored TWEAC-FOM-benchmark now showcases reduced boiler plate code using TWTSPulse.def.

BeyondEspresso · 2025-12-05T09:50:54Z

I performed 3 compilation tests on the FOM setup (fieldBackground, incidentField w/o componentwise operators, incidentField with componentwise operators). The envisioned picmi-setup also compiles.

BeyondEspresso · 2025-12-05T09:51:28Z

The draft tag can now be removed.

Implement TWTS PICMI capability

a5360b3

Fix compile-time name lookup for 2D case.

d317d30

BeyondEspresso force-pushed the topic-twtstight-add-picmi-support branch from cc199e8 to d317d30 Compare November 30, 2025 22:56

PrometheusPi requested changes Dec 1, 2025

View reviewed changes

PrometheusPi added PICMI pypicongpu and picmi related component: core in PIConGPU (core application) labels Dec 1, 2025

PrometheusPi added this to the 0.9.0 / next stable milestone Dec 1, 2025

chillenzer added the CI:no-compile CI is skipping compile/runtime tests but runs PICMI tests label Dec 1, 2025

chillenzer requested changes Dec 1, 2025

View reviewed changes

BrianMarre reviewed Dec 1, 2025

View reviewed changes

psychocoderHPC marked this pull request as draft December 2, 2025 12:44

Apply reviewers comments

4c09288

PrometheusPi marked this pull request as ready for review December 5, 2025 10:48

	"description": " The laser pulse will be initialized pulse_init times of the pulse_duration_si",
	"description": "The laser pulse will be initialized pulse_init times of the pulse_duration_si",

	"description": "sigma of std. gauss for intensity (E^2) [s]",
	"description": "sigma of std. Gauss for intensity (E^2) [s]",

	"description": "position of the huygens surface relative from domain boundaries",
	"description": "position of the Huygens surface relative from domain boundaries",

	if (E0 is not None) and (a0 is not None):
	raise ValueError("Only one of E0 or a0 should be specified. You set both.")

	* - profiles::Wavepacket<> : wavepacket with Gaussian spatial and temporal envelope profile with given
	* parameters

Implement PICMI capability for TWTS and TWEAC lasers #5561

Are you sure you want to change the base?

Implement PICMI capability for TWTS and TWEAC lasers #5561

Uh oh!

Conversation

BeyondEspresso commented Nov 28, 2025

Uh oh!

PrometheusPi commented Nov 28, 2025

Uh oh!

BeyondEspresso commented Nov 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

PrometheusPi left a comment

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!

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!

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!

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

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!

psychocoderHPC commented Dec 2, 2025

BeyondEspresso commented Nov 30, 2025 •

edited

Loading

BeyondEspresso Dec 2, 2025 •

edited

Loading