Add QED lookup tables generator/reader in /Tools

[lucafedeli88]

This PR adds new tools to generate and/or read into human-readable format the QED lookup tables (they can be compiled with cmake by enabling the flag DWarpX_QED_TOOLS. The PR also adds a documentation page to succinctly describe how to use these tools. Finally, it adds a new CI test to check that these tools generate lookup tables identical to those generated by WarpX. Specifically, the CI test does the following:

        export OMP_NUM_THREADS=2
        ./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
        ./build_qed/bin/warpx \
          ./Examples/Modules/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"
        ./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
        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
        ./build_qed/bin/warpx \
          ./Examples/Modules/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"

Note that the lookup tables cannot be compared in binary format because the serialization routines also serialize the padding bytes, whose value is in general unspecified. These results in minor (insignificant) differences between the binary table generated by the tool and the binary table generated by WarpX

[NeilZaim]

I've only reviewed to C++ and sh parts and they look good to me (I'll let @ax3l review in more details the github workflows and cmake parts).

Only significant comment is that it would be good to provide somewhere recommended table parameters for users (this can be done in a follow-up PR though).

[NeilZaim]

It could be useful for users to give recommended table parameters in this file (there are a lot of parameters and it's not trivial to choose them).

[lucafedeli88]

you are right... we need to properly document everything related to the QED module... I promise that I will work on that starting from January 2023!

[lucafedeli88]

@ax3l , what do you think about the cmake and the github workflow parts of this PR?

[aeriforme]

Can we add a link to the specific workflow sub-section?

[lucafedeli88]

should be ok now

[aeriforme]

This is very convenient, thank you for implementing this tool, @lucafedeli88!
I tried it and it works fine. It's quite fast too.
Just to be sure, I compared the tables obtained with this new tool
with those obtained with the tool integrated in WarpX
(by converting them to human readable format)
and they are the same (at least in the case I chose).

As @NeilZaim mentioned, it would be useful to provide a guide for the choice of the parameters.
It would also be useful to specify the parameters used in the builtin tables.

[github-advanced-security]

CodeQL found more than 10 potential problems in the proposed changes. Check the Files changed tab for more details.

[ax3l]

Is this library used anywhere else?

If you like, generalize it and make it part of the ABLASTR utils? (as a follow-up PR?)

[lucafedeli88]

@ax3l , it seems to me that when WarpX is compiled as a library the QED tools are not built.
A Tools/ folder is generated in the build directory, but no executables are generated in bin. If I run make inside this Tools folder the qed tools executables are correctly generated in the bin folder. Unfortunately I don't know how to modify the cmake file to fix this...

[ax3l]

.rst ending not needed :)
#4804