Add QED lookup tables generator/reader in /Tools

.github/workflows/scripts/checkQEDTableGenerator.sh

@@ -0,0 +1,77 @@
+
+#!/usr/bin/env bash
+#
+# Copyright 2022 Luca Fedeli
+#
+# License: BSD-3-Clause-LBNL
+
+set -eu -o pipefail
+
+export OMP_NUM_THREADS=2
+
+#
+# Generate QED lookup tables using external tool
+#
+./build_qed/bin/qed_tools/qed_table_generator \
+    --table BW --mode DP --dndt_chi_min 0.01 \
+    --dndt_chi_max 100 --dndt_how_many 64 \
+    --pair_chi_min 0.01 --pair_chi_max 100 \
+    --pair_chi_how_many 64 --pair_frac_how_many 64 \
+    -o bw_table_tool
+./build_qed/bin/qed_tools/qed_table_generator \
+    --table QS --mode DP --dndt_chi_min 0.001 \
+    --dndt_chi_max 100 --dndt_how_many 64 \
+    --em_chi_min 0.001 --em_chi_max 100 \
+    --em_chi_how_many 64 --em_frac_how_many 64 \
+    --em_frac_min 1e-12 -o qs_table_tool
+
+#
+# Generate QED lookup tables using WarpX
+#
+./build_qed/bin/warpx.3d \
+    ./Examples/Tests/qed/quantum_synchrotron/inputs_3d \
+    qed_bw.lookup_table_mode = "generate" \
+    qed_bw.tab_dndt_chi_min = 0.01 \
+    qed_bw.tab_dndt_chi_max = 100.0 \
+    qed_bw.tab_dndt_how_many = 64 \
+    qed_bw.tab_pair_chi_min = 0.01 \
+    qed_bw.tab_pair_chi_max = 100.0 \
+    qed_bw.tab_pair_chi_how_many = 64 \
+    qed_bw.tab_pair_frac_how_many = 64 \
+    qed_bw.save_table_in = "bw_table" \
+    qed_qs.lookup_table_mode = "generate" \
+    qed_qs.tab_dndt_chi_min = 0.001 \
+    qed_qs.tab_dndt_chi_max = 100.0 \
+    qed_qs.tab_dndt_how_many = 64 \
+    qed_qs.tab_em_chi_min = 0.001 \
+    qed_qs.tab_em_frac_min = 1.0e-12 \
+    qed_qs.tab_em_chi_max = 100.0 \
+    qed_qs.tab_em_chi_how_many = 64 \
+    qed_qs.tab_em_frac_how_many = 64 \
+    qed_qs.save_table_in = "qs_table"
+
+#
+# Convert lookup tables (generated with WarpX and with the external tool) in human-readable format
+#
+./build_qed/bin/qed_tools/qed_table_reader -i qs_table --table QS --mode DP -o qs_table
+./build_qed/bin/qed_tools/qed_table_reader -i qs_table_tool --table QS --mode DP -o qs_table_tool
+./build_qed/bin/qed_tools/qed_table_reader -i bw_table --table BW --mode DP -o bw_table
+./build_qed/bin/qed_tools/qed_table_reader -i bw_table_tool --table BW --mode DP -o bw_table_tool
+
+#
+# Compare the generated lookup tables
+#
+diff bw_table_dndt bw_table_tool_dndt
+diff bw_table_pair bw_table_tool_pair
+diff qs_table_phot_em qs_table_tool_phot_em
+diff qs_table_dndt qs_table_tool_dndt
+
+#
+# Run a WarpX simulation using the lookup tables generated by the external tool
+#
+./build_qed/bin/warpx.3d \
+    ./Examples/Tests/qed/quantum_synchrotron/inputs_3d \
+    qed_bw.lookup_table_mode = "load" \
+    qed_bw.load_table_from = "bw_table_tool" \
+    qed_qs.lookup_table_mode = "load" \
+    qed_qs.load_table_from = "qs_table_tool"

.github/workflows/ubuntu.yml

@@ -206,3 +206,35 @@ jobs:
       run: |
         export OMP_NUM_THREADS=1
         mpirun -n 2 Examples/Physics_applications/laser_acceleration/PICMI_inputs_3d.py
+
+  build_qed_table_tools:
+    name: Clang QED table tools
+    runs-on: ubuntu-20.04
+    if: github.event.pull_request.draft == false
+    env:
+      # On CI for this test, Ninja is slower than the default:
+      #CMAKE_GENERATOR: Ninja
+      # setuptools/mp4py work-around, see
+      #   https://github.com/mpi4py/mpi4py/pull/159
+      #   https://github.com/mpi4py/mpi4py/issues/157#issuecomment-1001022274
+      SETUPTOOLS_USE_DISTUTILS: stdlib
+    steps:
+    - uses: actions/checkout@v2
+    - name: install dependencies
+      run: |
+        .github/workflows/dependencies/pyfull.sh
+    - name: build WarpX & QED tools
+      run: |
+        export CC=$(which clang)
+        export CXX=$(which clang++)
+        cmake -S . -B build_qed \
+         -DWarpX_APP=ON \
+         -DWarpX_LIB=OFF \
+         -DWarpX_MPI=ON \
+         -DWarpX_QED_TOOLS=ON \
+         -DWarpX_QED_TABLE_GEN=ON
+        cmake --build build_qed -j 6
+
+    - name: run table_generator_tool
+      run: |
+        ./.github/workflows/scripts/checkQEDTableGenerator.sh

CMakeLists.txt

@@ -58,9 +58,9 @@ set_default_install_dirs()
 # Options and Variants ########################################################
 #
 include(CMakeDependentOption)
-option(WarpX_APP           "Build the WarpX executable application"     ON)
-option(WarpX_ASCENT        "Ascent in situ diagnostics"                 OFF)
-option(WarpX_EB            "Embedded boundary support"                  OFF)
+option(WarpX_APP           "Build the WarpX executable application"                                         ON)
+option(WarpX_ASCENT        "Ascent in situ diagnostics"                                                    OFF)
+option(WarpX_EB            "Embedded boundary support"                                                     OFF)
 cmake_dependent_option(WarpX_GPUCLOCK
                            "Add GPU kernel timers (cost function)"      ON
                            "WarpX_COMPUTE STREQUAL CUDA OR WarpX_COMPUTE STREQUAL HIP" OFF)
@@ -72,6 +72,7 @@ option(WarpX_PYTHON        "Python bindings"                            OFF)
 option(WarpX_SENSEI        "SENSEI in situ diagnostics"                 OFF)
 option(WarpX_QED           "QED support (requires PICSAR)"                    ON)
 option(WarpX_QED_TABLE_GEN "QED table generation (requires PICSAR and Boost)" OFF)
+option(WarpX_QED_TOOLS     "Build external tool to generate QED lookup tables (requires PICSAR and Boost)" OFF)
 
 set(WarpX_DIMS_VALUES 1 2 3 RZ)
 set(WarpX_DIMS 3 CACHE STRING "Simulation dimensionality <1;2;3;RZ>")
@@ -103,6 +104,13 @@ if(NOT WarpX_PARTICLE_PRECISION IN_LIST WarpX_PARTICLE_PRECISION_VALUES)
     message(FATAL_ERROR "WarpX_PARTICLE_PRECISION (${WarpX_PARTICLE_PRECISION}) must be one of ${WarpX_PARTICLE_PRECISION_VALUES}")
 endif()
 
+set(WarpX_QED_TABLES_GEN_OMP_VALUES AUTO ON OFF)
+set(WarpX_QED_TABLES_GEN_OMP AUTO CACHE STRING "Enables OpenMP support for QED lookup tables generation (AUTO/ON/OFF)")
+set_property(CACHE WarpX_QED_TABLES_GEN_OMP PROPERTY STRINGS ${WarpX_QED_TABLES_GEN_OMP_VALUES})
+if(NOT WarpX_QED_TABLES_GEN_OMP IN_LIST WarpX_QED_TABLES_GEN_OMP_VALUES)
+    message(FATAL_ERROR "WarpX_QED_TABLES_GEN_OMP (${WarpX_QED_TABLES_GEN_OMP}) must be one of ${WarpX_QED_TABLES_GEN_OMP_VALUES}")
+endif()
+
 set(WarpX_COMPUTE_VALUES NOACC OMP CUDA SYCL HIP)
 set(WarpX_COMPUTE OMP CACHE STRING "On-node, accelerated computing backend (NOACC/OMP/CUDA/SYCL/HIP)")
 set_property(CACHE WarpX_COMPUTE PROPERTY STRINGS ${WarpX_COMPUTE_VALUES})

Docs/source/install/cmake.rst

@@ -101,6 +101,8 @@ CMake Option                  Default & Values                             Descr
 ``WarpX_PYTHON``              ON/**OFF**                                   Python bindings
 ``WarpX_QED``                 **ON**/OFF                                   QED support (requires PICSAR)
 ``WarpX_QED_TABLE_GEN``       ON/**OFF**                                   QED table generation support (requires PICSAR and Boost)
+``WarpX_QED_TOOLS``           ON/**OFF**                                   Build external tool to generate QED lookup tables (requires PICSAR and Boost)
+``WarpX_QED_TABLES_GEN_OMP``  **AUTO**/ON/OFF                              Enables OpenMP support for QED lookup tables generation
 ``WarpX_SENSEI``              ON/**OFF**                                   SENSEI in situ visualization
 ============================= ============================================ =========================================================
 

Docs/source/usage/parameters.rst

@@ -3034,6 +3034,8 @@ Lookup tables store pre-computed values for functions used by the QED modules.
 
         * ``qed_bw.save_table_in`` (`string`): where to save the lookup table
 
+      Alternatively, the lookup table can be generated using a standalone tool (see :ref:`qed tools section <generate-lookup-tables-with-tools>`).
+
     * ``load``: a lookup table is loaded from a pre-generated binary file. The following parameter
       must be specified:
 
@@ -3071,6 +3073,8 @@ Lookup tables store pre-computed values for functions used by the QED modules.
 
         * ``qed_qs.save_table_in`` (`string`): where to save the lookup table
 
+      Alternatively, the lookup table can be generated using a standalone tool (see :ref:`qed tools section <generate-lookup-tables-with-tools>`).
+
     * ``load``: a lookup table is loaded from a pre-generated binary file. The following parameter
       must be specified:
 

Docs/source/usage/workflows.rst

@@ -9,6 +9,7 @@ This section collects typical user workflows and best practices for WarpX.
    :maxdepth: 2
 
    workflows/debugging
+   workflows/generate_lookup_tables_with_tools.rst
    workflows/libensemble
    workflows/plot_timestep_duration
    workflows/plot_distribution_mapping

Docs/source/usage/workflows/generate_lookup_tables_with_tools.rst

@@ -0,0 +1,45 @@
+.. _generate-lookup-tables-with-tools:
+
+Generate QED lookup tables using the standalone tool
+====================================================
+
+We provide tools to generate and convert into a human-readable format the QED lookup tables.
+Such tools can be compiled with ``cmake`` by setting the flag ``WarpX_QED_TOOLS=ON`` (this
+requires both ``PICSAR`` and ``Boost`` libraries). The tools are compiled alongside the WarpX executable
+in the  sub-folder ``bin/qed_tools``. We report here the help message displayed by the tools:
+
+.. code-block:: console
+
+    $ ./qed_table_reader -h
+    ### QED Table Reader ###
+    Command line options:
+    -h [NO ARG] Prints all command line arguments
+    -i [STRING] Name of the file to open
+    --table [STRING] Either BW (Breit-Wheeler) or QS (Quantum Synchrotron)
+    --mode [STRING] Precision of the calculations: either DP (double) or SP (single)
+    -o [STRING] filename to save the lookup table in human-readable format
+
+    $ ./qed_table_generator -h
+    ### QED Table Generator ###
+    Command line options:
+    -h [NO ARG] Prints all command line arguments
+    --table [STRING] Either BW (Breit-Wheeler) or QS (Quantum Synchrotron)
+    --mode [STRING] Precision of the calculations: either DP (double) or SP (single)
+    --dndt_chi_min [DOUBLE] minimum chi parameter for the dNdt table
+    --dndt_chi_max [DOUBLE] maximum chi parameter for the dNdt table
+    --dndt_how_many [INTEGR] number of points in the dNdt table
+    --pair_chi_min [DOUBLE] minimum chi for the pair production table (BW only)
+    --pair_chi_max [DOUBLE] maximum chi for the pair production table (BW only)
+    --pair_chi_how_many [INTEGR] number of chi points in the pair production table (BW only)
+    --pair_frac_how_many [INTEGR] number of frac points in the pair production table (BW only)
+    --em_chi_min [DOUBLE] minimum chi for the photon emission table (QS only)
+    --em_chi_max [DOUBLE] maximum chi for the photon emission production table (QS only)
+    --em_frac_min [DOUBLE] minimum frac for the photon emission production table (QS only)
+    --em_chi_how_many [INTEGR] number of chi points in the photon emission table (QS only)
+    --em_frac_how_many [INTEGR] number of frac points in the photon emission table (QS only)
+    -o [STRING] filename to save the lookup table
+
+These tools are meant to be compatible with WarpX: ``qed_table_generator`` should generate
+tables that can be loaded into WarpX and ``qed_table_reader`` should be able to read tables generated with WarpX.
+It is not safe to use these tools to generate a table on a machine using a different endianness with respect to
+the machine where the table is used.

Regression/Checksum/benchmarks_json/LaserAcceleration_single_precision_comms.json

@@ -22,4 +22,4 @@
     "jz": 1045267552192496.5,
     "rho": 2205684400.307701
   }
-}
+}

Tools/QedTablesUtils/CMakeLists.txt

@@ -0,0 +1,45 @@
+########
+# Common argument parser library
+########
+set(arg_parser_cpp "Source/ArgParser/QedTablesArgParser.cpp")
+set(arg_parser_h   "Source/ArgParser/QedTablesArgParser.H")
+
+add_library( QedToolsArgParser ${arg_parser_cpp} ${arg_parser_h} )
+
+########
+# Build QED lookup tables generator
+########
+set(qed_generator_name "qed_table_generator")
+set(qed_generator_src  "Source/QedTableGenerator.cpp")
+
+add_executable(${qed_generator_name} ${qed_generator_src})
+
+target_link_libraries(${qed_generator_name} PRIVATE PXRMP_QED)
+target_link_libraries(${qed_generator_name} PRIVATE QedToolsArgParser)
+
+target_compile_features(${qed_generator_name} PUBLIC cxx_std_17)
+set_target_properties(${qed_generator_name} PROPERTIES CXX_EXTENSIONS OFF)
+
+set_target_properties(${qed_generator_name} PROPERTIES
+  RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin/qed_tools)
+
+message(STATUS "QED lookup tables generator: ${qed_generator_name} (${qed_generator_src})")
+
+########
+# Build QED lookup tables reader
+########
+set(qed_reader_name "qed_table_reader")
+set(qed_reader_src  "Source/QedTableReader.cpp")
+
+add_executable(${qed_reader_name} ${qed_reader_src})
+
+target_link_libraries(${qed_reader_name} PRIVATE PXRMP_QED)
+target_link_libraries(${qed_reader_name} PRIVATE QedToolsArgParser)
+
+target_compile_features(${qed_reader_name} PUBLIC cxx_std_17)
+set_target_properties(${qed_reader_name} PROPERTIES CXX_EXTENSIONS OFF)
+
+set_target_properties(${qed_reader_name} PROPERTIES
+  RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin/qed_tools)
+
+message(STATUS "QED lookup tables generator: ${qed_reader_name} (${qed_reader_src})")

Tools/QedTablesUtils/Source/ArgParser/QedTablesArgParser.H

@@ -0,0 +1,58 @@
+#ifndef QED_TABLES_ARG_PARSER_
+#define QED_TABLES_ARG_PARSER_
+
+#include <optional>
+#include <string>
+#include <tuple>
+#include <unordered_map>
+#include <utility>
+#include <variant>
+#include <vector>
+
+namespace ArgParser
+{
+    /* Possible types of parameters of command line arguments (no argument, int, double, or std::string) */
+    enum class ArgType { NoArg, Integer, Double, String };
+
+    /* This type represents the type of a command line argument: if it exists it is either an int, a double, or a std::string */
+    using ArgVal = std::optional<std::variant<int, double, std::string>>;
+
+    /* The type of a possible command line argument */
+    using Key = std::tuple<std::string, ArgType, std::string>;
+
+    /* The type of the map of the parsed command line arguments */
+    using ParsedArgs = std::unordered_map<std::string, ArgVal>;
+
+    /**
+    * \brief Gets the value out of an ArgVal (std::optional<std::variant<int, double, std::string>>) object
+    *
+    * \tparam T          the type to return (must be int, double, or std::string)
+    * \param[in] arg_val the ArgVal object
+    * \return            the value in arg_val
+    */
+    template <typename T>
+    T GetVal(const ArgVal& arg_val)
+    {
+        return std::get<T>(*arg_val);
+    }
+
+    /**
+    * \brief Function to parse the command line arguments
+    *
+    * \param[in] keys    the list of possible command line arguments
+    * \param[in] argc    the number of command line arguments
+    * \param[in] argv    all the command line arguments
+    * \return            the parsed command line arguments
+    */
+    ParsedArgs ParseArgs (const std::vector<Key>& keys, const int argc, char const* const* argv);
+
+    /**
+    * \brief Prints the command line options
+    *
+    * \param[in] cmd_list    the list of possible command line arguments
+    */
+    void PrintHelp (const std::vector<Key>& cmd_list);
+};
+
+
+#endif //QED_TABLES_ARG_PARSER_