Skip to content

Docs: inputs section cleanup - QED #6385

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: development
Choose a base branch
from
Open

Docs: inputs section cleanup - QED #6385

Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
08eb1bb
Docs: inputs section cleanup - QED all together
aeriforme Nov 13, 2025
2529059
merge development
aeriforme Nov 13, 2025
586b503
Update Docs/source/usage/parameters.rst
aeriforme Nov 13, 2025
5817e53
minor fixes
aeriforme Nov 13, 2025
7e025a3
update compilation flags and minor fixes
aeriforme Nov 13, 2025
649cbb5
Update Docs/source/usage/parameters.rst
EZoni Nov 26, 2025
10e456e
integrate comments by luca
aeriforme Dec 2, 2025
56ec526
integrate comments by luca
aeriforme Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 70 additions & 54 deletions Docs/source/usage/parameters.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1425,43 +1425,6 @@ Particle initialization
species (must be smaller than the atomic number of chemical element given
in `physical_element`).

* ``<species_name>.do_classical_radiation_reaction`` (`int`) optional (default `0`)
Enables Radiation Reaction (or Radiation Friction) for the species. Species
must be either electrons or positrons. Boris pusher must be used for the
simulation. If both ``<species_name>.do_classical_radiation_reaction`` and
``<species_name>.do_qed_quantum_sync`` are enabled, then the classical module
will be used when the particle's chi parameter is below ``qed_qs.chi_min``,
the discrete quantum module otherwise.

* ``<species_name>.do_qed_quantum_sync`` (`int`) optional (default `0`)
Enables Quantum synchrotron emission for this species.
Quantum synchrotron lookup table should be either generated or loaded from disk to enable
this process (see "Lookup tables for QED modules" section below).
`<species_name>` must be either an electron or a positron species.
**This feature requires to compile with QED=TRUE**

* ``<species_name>.do_qed_breit_wheeler`` (`int`) optional (default `0`)
Enables non-linear Breit-Wheeler process for this species.
Breit-Wheeler lookup table should be either generated or loaded from disk to enable
this process (see "Lookup tables for QED modules" section below).
`<species_name>` must be a photon species (i.e., a species with ``<species_name>.species_type`` set to `photon`)
**This feature requires to compile with -DWarpX_QED=ON**

* ``<species_name>.qed_quantum_sync_phot_product_species`` (`string`)
If an electron or a positron species has the Quantum synchrotron process, a photon product species must be specified
(the name of an existing photon species must be provided)
**This feature requires to compile with QED=TRUE**

* ``<species_name>.qed_breit_wheeler_ele_product_species`` (`string`)
If a photon species has the Breit-Wheeler process, an electron product species must be specified
(the name of an existing electron species must be provided)
**This feature requires to compile with QED=TRUE**

* ``<species_name>.qed_breit_wheeler_pos_product_species`` (`string`)
If a photon species has the Breit-Wheeler process, a positron product species must be specified
(the name of an existing positron species must be provided).
**This feature requires to compile with QED=TRUE**

* ``<species_name>.do_resampling`` (`0` or `1`) optional (default `0`)
If `1` resampling is performed for this species. This means that the number of macroparticles
will be reduced at specific timesteps while preserving the distribution function as much as
Expand Down Expand Up @@ -2783,17 +2746,6 @@ Additional parameters
Note that if Perfectly Matched Layers (PML) are used, synchronization of the `E` and `B` fields
is performed at every timestep regardless of this parameter.

* ``warpx.use_hybrid_QED`` (`bool`; default: 0)
Will use the Hybrid QED Maxwell solver when pushing fields: a QED correction is added to the
field solver to solve non-linear Maxwell's equations, according to :cite:t:`param-GrismayerNJP2021`.
Note that this option can only be used with the PSATD build. Furthermore, one must set
``warpx.grid_type = collocated`` (which otherwise would be ``staggered`` by default).

* ``warpx.quantum_xi`` (`float`; default: 1.3050122.e-52)
Overwrites the actual quantum parameter used in Maxwell's QED equations. Assigning a
value here will make the simulation unphysical, but will allow QED effects to become more apparent.
Note that this option will only have an effect if the ``warpx.use_Hybrid_QED`` flag is also triggered.

* ``warpx.do_device_synchronize`` (`bool`) optional (default `1`)
When running in an accelerated platform, whether to call a ``amrex::Gpu::synchronize()`` around profiling regions.
This allows the profiler to give meaningful timers, but (hardly) slows down the simulation.
Expand Down Expand Up @@ -3880,11 +3832,61 @@ This shifts analysis from post-processing to runtime calculation of reduction op
The precision used when writing out the data to the text files.
This can also be specified for the specific diagnostic by setting ``<reduced_diags_name>.precision``.

Lookup tables and other settings for QED modules
------------------------------------------------
.. _running-cpp-parameters-qed:

QED
---

These features require to compile with ``-DWarpX_QED=ON``, unless stated otherwise.

Nonlinear Compton scattering
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* ``qed_qs.photon_creation_energy_threshold`` (`float`) optional (default `2`)
Energy threshold for photon particle creation in units of :math:`m_e c^2`.

* ``<species_name>.do_qed_quantum_sync`` (`int`) optional (default `0`)
Enables Quantum synchrotron emission for this species.
Quantum synchrotron lookup table should be either generated or loaded from disk to enable
this process (see "Lookup tables for QED modules" section below).
`<species>` must be either an electron or a positron species.

* ``<species_name>.qed_quantum_sync_phot_product_species`` (`string`)
If an electron or a positron species has the Quantum synchrotron process, a photon product species must be specified
(the name of an existing photon species must be provided)

* ``<species_name>.do_classical_radiation_reaction`` (`int`) optional (default `0`)
Enables Radiation Reaction (or Radiation Friction) for the species. Species
must be either electrons or positrons. Boris pusher must be used for the
simulation. If both ``<species>.do_classical_radiation_reaction`` and
``<species_name>.do_qed_quantum_sync`` are enabled, then the classical module
will be used when the particle's chi parameter is below ``qed_qs.chi_min``,
the discrete quantum module otherwise.
Copy link
Member

@lucafedeli88 lucafedeli88 Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a quick comment: classical radiation reaction does not require a compilation with WarpX_QED=ON, since it is just a modified Boris pusher.



Nonlinear Breit-Wheeler
^^^^^^^^^^^^^^^^^^^^^^^

* ``<species_name>.do_qed_breit_wheeler`` (`int`) optional (default `0`)
Enables non-linear Breit-Wheeler process for this species.
Breit-Wheeler lookup table should be either generated or loaded from disk to enable
this process (see "Lookup tables for QED modules" section below).
`<species>` must be a photon species (i.e., a species with ``<species_name>.species_type`` set to `photon`)

* ``<species_name>.qed_breit_wheeler_ele_product_species`` (`string`)
If a photon species has the Breit-Wheeler process, an electron product species must be specified
(the name of an existing electron species must be provided)

* ``<species_name>.qed_breit_wheeler_pos_product_species`` (`string`)
If a photon species has the Breit-Wheeler process, a positron product species must be specified
(the name of an existing positron species must be provided).


Lookup tables
^^^^^^^^^^^^^

Lookup tables store pre-computed values for functions used by the QED modules.
**This feature requires to compile with QED=TRUE (and also with QED_TABLE_GEN=TRUE for table generation)**
This feature requires with the extra compilation flag ``-DWarpX_QED_TABLE_GEN=ON`` for table generation.

* ``qed_bw.lookup_table_mode`` (`string`)
There are three options to prepare the lookup table required by the Breit-Wheeler module:
Expand Down Expand Up @@ -3968,12 +3970,12 @@ Lookup tables store pre-computed values for functions used by the QED modules.
* ``qed_qs.chi_min`` (`float`): minimum chi parameter to be considered by the Quantum Synchrotron engine
(suggested value : 0.001)

* ``qed_qs.photon_creation_energy_threshold`` (`float`) optional (default `2`)
Energy threshold for photon particle creation in `*me*c^2` units.

Schwinger process
^^^^^^^^^^^^^^^^^

* ``warpx.do_qed_schwinger`` (`bool`) optional (default `0`)
If this is 1, Schwinger electron-positron pairs can be generated in vacuum in the cells where the EM field is high enough.
Activating the Schwinger process requires the code to be compiled with ``QED=TRUE`` and ``PICSAR``.
If ``warpx.do_qed_schwinger = 1``, Schwinger product species must be specified with
``qed_schwinger.ele_product_species`` and ``qed_schwinger.pos_product_species``.
Schwinger process requires either ``warpx.grid_type = collocated`` or
Expand Down Expand Up @@ -4007,6 +4009,20 @@ Lookup tables store pre-computed values for functions used by the QED modules.
Note that, regardless of this parameter, the number of macroparticles created is at most one per cell
per timestep per species (with a weight corresponding to the number of physical pairs created).

* ``warpx.use_hybrid_QED`` (`bool`; default: 0)
Will use the Hybrid QED Maxwell solver when pushing fields: a QED correction is added to the
field solver to solve non-linear Maxwell's equations, according to :cite:t:`param-GrismayerNJP2021`.
Note that this option can only be used with the PSATD build. Furthermore, one must set
``warpx.grid_type = collocated`` (which otherwise would be ``staggered`` by default).
This feature does not require to compile with ``-DWarpX_QED=ON``.

* ``warpx.quantum_xi`` (`float`; default: 1.3050122.e-52)
Overwrites the actual quantum parameter used in Maxwell's QED equations. Assigning a
value here will make the simulation unphysical, but will allow QED effects to become more apparent.
Note that this option will only have an effect if the ``warpx.use_Hybrid_QED`` flag is also triggered.
This feature does not require to compile with ``-DWarpX_QED=ON``.


Checkpoints and restart
-----------------------
WarpX supports checkpoints/restart via AMReX.
Expand Down
Loading