Docs: how to generate QED tables in beam-beam example

Examples/Physics_applications/beam_beam_collision/README.rst

@@ -30,6 +30,26 @@ For `MPI-parallel <https://www.mpi-forum.org>`__ runs, prefix these lines with `
    :caption: You can copy this file from ``Examples/Physics_applications/beam_beam_collision/inputs_test_3d_beam_beam_collision``.
 
 
+QED tables
+----------
+
+The quantum synchrotron and nonlinear Breit-Wheeler modules are based on a Monte Carlo algorithm that computes the probabilities of an event from tabulated values.
+WarpX comes with `builtin` tables (see the input file above), however these are low resolution tables that may not provide accurate results.
+There are two ways to generate your own lookup table:
+
+* Inside WarpX, at runtime: the tables are generated by WarpX itself at the beginning of the simulation.
+  This requires to compile WarpX with ``-DWarpX_QED_TABLE_GEN=ON`` and to add the desired tables parameters in WarpX's input file.
+  `Here <https://warpx.readthedocs.io/en/latest/usage/parameters.html#lookup-tables-and-other-settings-for-qed-modules>`__  are more details.
+
+* Outside of WarpX, using an external table generator: the tables are pregenerated, before running the actual simulation.
+  This standalone tool can be compiled at the same time as WarpX using ``-DWarpX_QED_TOOLS=ON``.
+  The table parameters are then passed to the table generator and do not need to be added to WarpX's input file.
+  `Here <https://warpx.readthedocs.io/en/latest/usage/workflows/generate_lookup_tables_with_tools.html>`__ are more details.
+
+Once the tables have been generated, they can be loaded in the input file using
+``qed_qs,bw.lookup_table_mode=load`` and ``qed_qs,bw.load_table_from=/path/to/your/table``.
+
+
 Visualize
 ---------
 
@@ -42,13 +62,13 @@ We compare different results for the reduced diagnostics with the literature:
 
 The small-scale simulation has been performed with a resolution of ``nx = 64, ny = 64, nz = 64`` grid cells, while the large-scale one has a much higher resolution of ``nx = 512, ny = 512, nz = 1024``.
 Moreover, the large-scale simulation uses dedicated QED lookup tables instead of the builtin tables.
-To generate the tables within WarpX, the code must be compiled with the flag ``-DWarpX_QED_TABLE_GEN=ON``.
-For the large-scale simulation we have used the following options:
+For the large-scale simulation we have used the following options (added to the input file):
 
 .. code-block:: ini
 
    qed_qs.lookup_table_mode = generate
    qed_bw.lookup_table_mode = generate
+
    qed_qs.tab_dndt_chi_min=1e-3
    qed_qs.tab_dndt_chi_max=2e3
    qed_qs.tab_dndt_how_many=512
@@ -58,6 +78,7 @@ For the large-scale simulation we have used the following options:
    qed_qs.tab_em_frac_how_many=512
    qed_qs.tab_em_frac_min=1e-12
    qed_qs.save_table_in=my_qs_table.txt
+
    qed_bw.tab_dndt_chi_min=1e-2
    qed_bw.tab_dndt_chi_max=2e3
    qed_bw.tab_dndt_how_many=512
@@ -68,6 +89,19 @@ For the large-scale simulation we have used the following options:
    qed_bw.save_table_in=my_bw_table.txt
 
 
+The same table can be also obtained using the table generator with the following lines:
+
+.. code-block:: ini
+
+   ./qed_table_generator --table QS --mode DP -o my_qs_table.txt \
+                         --dndt_chi_min 1e-3 --dndt_chi_max 2e3 --dndt_how_many 512 \
+                         --em_chi_min 1e-3 --em_chi_max 2e3 --em_frac_min 1e-12 --em_chi_how_many 512 --em_frac_how_many 512
+
+
+   ./qed_table_generator --table BW --mode DP -o my_bw_table.txt \
+                         --dndt_chi_min 1e-2 --dndt_chi_max 2e3 --dndt_how_many 512 --pair_chi_min 1e-2 --pair_chi_max 2e3 --pair_chi_how_many 512 --pair_frac_how_many 512
+
+
 .. figure:: https://gist.github.com/user-attachments/assets/2dd43782-d039-4faa-9d27-e3cf8fb17352
    :alt: Beam-beam collision benchmark against :cite:t:`ex-Yakimenko2019`.
    :width: 100%

Examples/Physics_applications/beam_beam_collision/inputs_test_3d_beam_beam_collision

@@ -203,6 +203,12 @@ qed_bw.chi_min = 1.e-2
 #qed_bw.tab_pair_frac_how_many=512
 #qed_bw.save_table_in=my_bw_table.txt
 
+# if you wish to use existing tables:
+#qed_qs.lookup_table_mode=load
+#qed_qs.load_table_from = /path/to/my_qs_table.txt
+#qed_bw.lookup_table_mode=load
+#qed_bw.load_table_from = /path/to/my_bw_table.txt
+
 warpx.do_qed_schwinger = 0.
 
 #################################