Add laser model description to docs #5397

steindev · 2025-06-24T10:23:07Z

PR adds analytic formulas, which are the basis of the implementation of the GaussianPulse and DispersivePulse, to the docs.

I see this as a first version. Feedback is welcome!

chillenzer

Minor typos.

docs/source/models/lasers.rst

chillenzer · 2025-08-05T05:22:16Z

docs/source/models/lasers.rst

+.. math::
+  \varphi |_{z=0} = \varphi(x,\Omega) |_{z=0} = k_x(\Omega) \cdot x\,,
+
+where :math:`k_x = \tfrac{\Omega}{c} \vec{\mathrm e}_\Omega \cdot \vec{\mathrm e}_x = -\tfrac{\Omega}{c}\sin\theta` with :math:`\theta=\theta(\Omega)` being the angle enclosed by the propagation directions of frequency :math:`\Omega` and the central laser frequency :math:`\Omega_0`.


I would have loved to see the symmetry $\vec{\mathrm e}\Omega \cdot \vec{\mathrm e}{\Omega_0}$ exposed here but I agree that for the rest of the text choosing that direction to be $x$ upfront probably eases notation.

Yes, and it is also the way PIConGPU internally implements the lasers. They propagate along x and the internal system is rotated according to the users choice of PropagationDirection in params.

docs/source/models/lasers.rst

chillenzer · 2025-08-05T05:35:59Z

docs/source/models/lasers.rst

+Result
+^^^^^^
+According to the definitions above
+
+.. math::
+  \hat E(x,y,z,\Omega) = \hat E_x \cdot \hat E_y\,.
+


This currently provides very little additional value as a separate section. I'd either drop the section heading or expand on this further by, e.g., providing the full formula plugged in with the various terms.

Well you probably find it obvious since it is written this explicitly. But I am afraid it wouldn't be that obvious when removing the section title. It is only this high in document hierarchy because of its importance.

chillenzer

Sorry, wrong button. But it's very quick fixes.

PrometheusPi · 2025-08-11T14:20:23Z

@steindev what is the status of this PR?

PrometheusPi

minor questions

PrometheusPi · 2025-08-13T09:38:42Z

docs/source/models/lasers.rst

+.. math::
+  \hat{\vec E}(\vec r, \Omega) = \hat E_\mathrm{A}(\vec r, \Omega) e^{-\imath \varphi(\vec r, \Omega)}\vec{\mathrm e}_x\,,
+
+where :math:`\Omega=2\pi\nu` is the angular frequency and :math:`\vec r` the position considered, :math:`\hat E_\mathrm{A}` is the spectral amplitude and


you never defined $\nu$

PrometheusPi · 2025-08-13T09:46:22Z

docs/source/models/lasers.rst

+:math:`\varphi=\tfrac{\Omega}{c} \vec{\mathrm e}_\Omega \cdot \vec r`
+the spectral phase of the pulse,
+with :math:`\vec{\mathrm e}_\Omega` being the propagation direction of frequency :math:`\Omega`.
+Dispersions are assumed to occur only in the plane spanned by the direction of pulse propagation :math:`\vec{\mathrm e}_z`, being equal to the direction of propagation of the central frequency :math:`\Omega_0`, and polarization :math:`\vec{\mathrm e}_x`, i.e. :math:`\vec{\mathrm e}_\Omega \cdot \vec{\mathrm e}_y = 0`.


Is this generally true or only for the central frequency?

Suggested change

Dispersions are assumed to occur only in the plane spanned by the direction of pulse propagation :math:`\vec{\mathrm e}_z`, being equal to the direction of propagation of the central frequency :math:`\Omega_0`, and polarization :math:`\vec{\mathrm e}_x`, i.e. :math:`\vec{\mathrm e}_\Omega \cdot \vec{\mathrm e}_y = 0`.

Dispersions are assumed to occur only in the plane spanned by the direction of pulse propagation :math:`\vec{\mathrm e}_z`, being equal to the direction of propagation of the central frequency :math:`\Omega_0`, and polarization :math:`\vec{\mathrm e}_x`, i.e. :math:`\vec{\mathrm e}_{\Omega_0} \cdot \vec{\mathrm e}_y = 0`.

Could you answer this question?

Sorry, I think you never saw this question - even if it from August. 😄

But what is the question? The sentence is incomplete

PrometheusPi · 2025-08-13T09:50:08Z

docs/source/models/lasers.rst

+This last exponential simply contributes a term to :math:`\gamma_4`, which is located between eqs. (13) and (14) in [Steiniger2024]_, in the form of
+
+.. math::
+  \gamma_4\; +\negthickspace= -\frac{y^2 R_y^{-1}(z)}{2c}\frac{1}{\tau_0}\,.


This renders as $+=$ - what is this suppose to mean in this mathematical context?

chillenzer · 2025-09-02T07:19:39Z

Updates?

PrometheusPi · 2025-09-11T08:42:58Z

@steindev what is the status of this PR?

steindev · 2025-09-11T08:44:23Z

Work in progress. Might come back to it this or next week.

chillenzer · 2025-09-19T06:34:15Z

Poke

Co-authored-by: chillenzer <107195608+chillenzer@users.noreply.github.com>

steindev · 2025-10-02T11:34:17Z

@PrometheusPi @chillenzer @BeyondEspresso @finnolec Ready for review!

PrometheusPi

Only minor suggestions - rendered doc page looks good.

docs/source/models/lasers.rst

PrometheusPi · 2025-10-07T15:27:37Z

docs/source/models/lasers.rst

+The profile assumes a gaussian shape for the laser's spectrum.
+The respective in-focus values of these dispersions can be provided as parameters.
+However, the electric field values in time domain are computed from the field's values in frequency domain by a discrete Fourier transform.
+Therefore, it is possible to use any other shape of the laser's spectrum by modifying the profile's source code.


Could you link to the lines in the source code here?

PrometheusPi · 2025-10-07T15:29:37Z

docs/source/models/lasers.rst

+:math:`\varphi=\tfrac{\Omega}{c} \vec{\mathrm e}_\Omega \cdot \vec r`
+the spectral phase of the pulse,
+with :math:`\vec{\mathrm e}_\Omega` being the propagation direction of frequency :math:`\Omega`.
+Dispersions are assumed to occur only in the plane spanned by the direction of pulse propagation :math:`\vec{\mathrm e}_z`, being equal to the direction of propagation of the central frequency :math:`\Omega_0`, and polarization :math:`\vec{\mathrm e}_x`, i.e. :math:`\vec{\mathrm e}_\Omega \cdot \vec{\mathrm e}_y = 0`.


Could you answer this question?

PrometheusPi · 2025-10-07T15:30:22Z

docs/source/models/lasers.rst

+the spectral phase of the pulse,
+with :math:`\vec{\mathrm e}_\Omega` being the propagation direction of frequency :math:`\Omega`.
+Dispersions are assumed to occur only in the plane spanned by the direction of pulse propagation :math:`\vec{\mathrm e}_z`, being equal to the direction of propagation of the central frequency :math:`\Omega_0`, and polarization :math:`\vec{\mathrm e}_x`, i.e. :math:`\vec{\mathrm e}_\Omega \cdot \vec{\mathrm e}_y = 0`.
+This implies, that the spectral phase does not vary along the :math:`y`-direction in focus, i.e.


Suggested change

This implies, that the spectral phase does not vary along the :math:`y`-direction in focus, i.e.

This implies that the spectral phase does not vary along the :math:`y`-direction in focus, i.e.

I do not understand what you mean with "y-direction in focus" (knowing that y is the common laser propagation direction)

Furthermore, above you say:

direction of pulse propagation :math:\vec{\mathrm e}_z,

This seems to contrast the new propagation direction y here and might lead to confusion.

Okay -it's clear now: y-direction here is orthogonal to laser polarization in x and propagation in z.
Fine.

PrometheusPi · 2025-10-07T15:41:47Z

docs/source/models/lasers.rst

+Derivation
+^^^^^^^^^^
+[Steiniger2024]_ computed the 2D :math:`\hat E_x(x,z,\Omega)` part of eq. :math:`\bigstar`, i.e. computed :math:`\clubsuit` and thereby omitted the last integral in :math:`\bigstar`.
+The result of this last integral can be read off from the known solution for the 2D part, being provided in eq. (6) of [Steiniger2024]_.


Suggested change

The result of this last integral can be read off from the known solution for the 2D part, being provided in eq. (6) of [Steiniger2024]_.

The result of this last integral can be read from the known solution for the 2D part, being provided in eq. (6) of [Steiniger2024]_.

Just a suggestion

PrometheusPi · 2025-10-07T15:43:43Z

docs/source/models/lasers.rst

+    \mathrm e^{\imath\frac{1}{2}\arctan\frac{z}{z_{\mathrm R,y}}}
+    \mathrm e^{-\imath \frac{y^2 R_y^{-1}(z)}{2c}\frac{1}{\tau_0}\Omega^\prime}
+
+only the last exponential depends on frequency :math:`\Omega^\prime` and needs to be taken into account in the Fourier transform.


is "exponential" here correct or "exponent"

Co-authored-by: Richard Pausch <r.pausch@hzdr.de>

chillenzer · 2025-10-14T06:22:50Z

What's the status here? Occasional green reviews and then updates again?

steindev added this to the 0.9.0 / next stable milestone Jun 24, 2025

steindev requested review from BeyondEspresso, PrometheusPi, chillenzer and finnolec June 24, 2025 10:23

steindev added documentation regarding documentation or wiki discussions CI:no-compile CI is skipping compile/runtime tests but runs PICMI tests labels Jun 24, 2025

steindev force-pushed the 2025-06_add-laser-doc branch from cff45ec to 5f2592c Compare June 25, 2025 08:50

chillenzer approved these changes Aug 5, 2025

View reviewed changes

chillenzer requested changes Aug 5, 2025

View reviewed changes

chillenzer previously approved these changes Aug 12, 2025

View reviewed changes

PrometheusPi requested changes Aug 13, 2025

View reviewed changes

steindev dismissed chillenzer’s stale review via 72f7b11 October 1, 2025 04:54

steindev force-pushed the 2025-06_add-laser-doc branch from 0e19f29 to 72f7b11 Compare October 1, 2025 04:54

steindev and others added 7 commits October 2, 2025 11:10

Add laser model description to docs

b1478d4

Update docs/source/models/lasers.rst

3517e20

Co-authored-by: chillenzer <107195608+chillenzer@users.noreply.github.com>

Update docs/source/models/lasers.rst

212ede7

Co-authored-by: chillenzer <107195608+chillenzer@users.noreply.github.com>

Update docs/source/models/lasers.rst

1a44890

Co-authored-by: chillenzer <107195608+chillenzer@users.noreply.github.com>

laser docu: Add intro text

11dc943

LaserDoc: Add small info

7cd316b

LaserDoc: Add reference to laser setup

4caaf07

steindev force-pushed the 2025-06_add-laser-doc branch from 72f7b11 to 4caaf07 Compare October 2, 2025 11:32

PrometheusPi previously approved these changes Oct 7, 2025

View reviewed changes

Update docs/source/models/lasers.rst [RP1]

ca34f4b

Co-authored-by: Richard Pausch <r.pausch@hzdr.de>

steindev dismissed PrometheusPi’s stale review via ca34f4b October 10, 2025 13:53

	Dispersions are assumed to occur only in the plane spanned by the direction of pulse propagation :math:`\vec{\mathrm e}_z`, being equal to the direction of propagation of the central frequency :math:`\Omega_0`, and polarization :math:`\vec{\mathrm e}_x`, i.e. :math:`\vec{\mathrm e}_\Omega \cdot \vec{\mathrm e}_y = 0`.
	Dispersions are assumed to occur only in the plane spanned by the direction of pulse propagation :math:`\vec{\mathrm e}_z`, being equal to the direction of propagation of the central frequency :math:`\Omega_0`, and polarization :math:`\vec{\mathrm e}_x`, i.e. :math:`\vec{\mathrm e}_{\Omega_0} \cdot \vec{\mathrm e}_y = 0`.

	This implies, that the spectral phase does not vary along the :math:`y`-direction in focus, i.e.
	This implies that the spectral phase does not vary along the :math:`y`-direction in focus, i.e.

	The result of this last integral can be read off from the known solution for the 2D part, being provided in eq. (6) of [Steiniger2024]_.
	The result of this last integral can be read from the known solution for the 2D part, being provided in eq. (6) of [Steiniger2024]_.

Add laser model description to docs #5397

Are you sure you want to change the base?

Add laser model description to docs #5397

Uh oh!

Conversation

steindev commented Jun 24, 2025

Uh oh!

chillenzer left a comment

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chillenzer left a comment

Choose a reason for hiding this comment

Uh oh!

PrometheusPi commented Aug 11, 2025

Uh oh!

PrometheusPi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PrometheusPi Aug 13, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chillenzer commented Sep 2, 2025

Uh oh!

PrometheusPi commented Sep 11, 2025

Uh oh!

steindev commented Sep 11, 2025

Uh oh!

chillenzer commented Sep 19, 2025

Uh oh!

steindev commented Oct 2, 2025

Uh oh!

PrometheusPi left a comment

Choose a reason for hiding this comment

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!

chillenzer commented Oct 14, 2025

Uh oh!

Reviewers

Assignees

Labels

PrometheusPi Aug 13, 2025 •

edited

Loading