Clarify .cfg files

[f-schmitt]

It should be clear in the submit/.cfg files which variables are used and which are just examples and need to be added to e.g. TBG_programParams to be actually used.

example: TBG_movingWindow in 0016gpus.cfg.

[ax3l]

👍

[ax3l]

Also some namings in .tpl files are not very clear. I started to declutter that in the slurm/sbatch tpl

[ax3l]

• add 1gpu.cfg for each example

[f-schmitt]

How about this layout for cfg files. I think each file should only contain the variables it is actually using. We might want to add an doc/CFG_FILES to describe all possible variables in detail. This would be the responsibility of plugin maintainers for plugin variables, of course.

##
## This configuration file is used by PIConGPU's TBG tool to create a
## batch script for PIConGPU runs. For a detailed description of PIConGPU
## configuration files including all available variables, see doc/CFG_FILES.
##


#################################
## Section: Required Variables ##
#################################

TBG_wallTime="23:53:00"

TBG_gpu_x=1
TBG_gpu_y=4
TBG_gpu_z=1

TBG_gridSize="-g 192 512 12"
TBG_steps="-s 2500"
TBG_devices="-d !TBG_gpu_x !TBG_gpu_y !TBG_gpu_z"


#################################
## Section: Optional Variables ##
#################################

TBG_pngYZ="--png_e.period 10 --png_e.axis yz --png_e.slicePoint 0.5 --png_e.folder pngElectronsYZ"
TBG_pngYX="--png_e.period 10 --png_e.axis yx --png_e.slicePoint 0.5 --png_e.folder pngElectronsYX"

TBG_ipngYX="--png_i.period 10 --png_i.axis yx --png_i.slicePoint 0.5 --png_i.folder pngIonsYX"

TBG_eBin="--bin_e.period 100 --bin_e.binCount 1024 --bin_e.minEnergy 0 --bin_e.maxEnergy 5000"
TBG_iBin="--bin_i.period 100 --bin_i.binCount 1024 --bin_i.minEnergy 0 --bin_i.maxEnergy 2000000"

TBG_analyser="!TBG_ipngYX                   \
              !TBG_eBin                     \
              !TBG_iBin                     \
              !TBG_pngYX                    \
              !TBG_pngYZ                    \
              --ions_cnt.period 100         \
              --elec_cnt.period 100         \
              --energy_fields.period 10     \
              --energy_e.period 10          \
              --energy_i.period 10"


#################################
## Section: Program Parameters ##
#################################

TBG_programParams="--periodic 1 1 1 \
                   !TBG_devices     \
                   !TBG_gridSize    \
                   !TBG_steps       \
                   !TBG_analyser    \
                   | tee output"

# TOTAL number of GPUs
TBG_tasks="$(( TBG_gpu_x * TBG_gpu_y * TBG_gpu_z ))"

"$TBG_cfgPath"/submitAction.sh

[f-schmitt]

Note: we might want to prefix variables that can be passed to programParams (_pp_ ?) to distinct them from those that are only used to create the former.

[ax3l]

I think the problem right now is, that depending on your compiled-in plugins and depending on the enabled species, the available program options vary heavily.

I actually like the hints like in examples/LaserWakefield/submit/0016gpus.cfg when I am a "user":

...
TBG_analyser="!TBG_pngYX                    \
              !TBG_pngYZ" 


# Pre-defined macros you may like to use
#
# create preview images (png)
TBG_pngYZ="--png_e.period 10 --png_e.axis yz --png_e.slicePoint 0.5 --png_e.folder pngElectronsYZ"
TBG_pngYX="--png_e.period 10 --png_e.axis yx --png_e.slicePoint 0.5 --png_e.folder pngElectronsYX"

TBG_IpngYZ="--png_i.period 10 --png_i.axis yz --png_i.slicePoint 0.5 --png_i.folder pngIonsYZ"
TBG_IpngYX="--png_i.period 10 --png_i.axis yx --png_i.slicePoint 0.5 --png_i.folder png
IonsYX"

# hdf5 output
TBG_hdf5="--hdf5.period 100 --hdf5.compression"
#--hdf5.file lwfa

# sum up total energy
TBG_sumEnergy="--energy_fields.period 10 --energy_e.period 10 --energy_i.period 10"
# count the number of macro particles
TBG_macroCount="--elec_cnt.period 100 --ions_cnt.period 100"

# create a particle-energy histogram
# [in keV]
TBG_eBin="--bin_e.period 10 --bin_e.binCount 1024 --bin_e.minEnergy 0 --bin_e.maxEnergy 150"
TBG_iBin="--bin_i.period 10 --bin_i.binCount 1024 --bin_i.minEnergy 0 --bin_i.maxEnergy 150"

# connect to a live-view server (start the server in advance)
TBG_liveViewYX="--live_e.period 1 --live_e.slicePoint 0.5 --live_e.ip 10.0.2.254 --live_e.port 2020 --live_e.axis yx"
TBG_liveViewYZ="--live_e.period 1 --live_e.slicePoint 0.5 --live_e.ip 10.0.2.254 --live_e.port 2021 --live_e.axis yz"
...

[f-schmitt]

I like the hints too, but I don't want them to be duplicated over all cfg files.
I would say the user should know which species/plugins are enabled and can then lookup the available vars in a central, easy to maintain (!) file

[ax3l]

probably a good idea... (you got me at easy to maintain...)
so let us put a comment like this in each cfg file instead:

...
TBG_analyser="!TBG_pngYX                    \
              !TBG_pngYZ" 


# Pre-defined macros you may like to use
# Hint: find more makros at doc/cfg/TBG_makros.cfg

# create preview images (png)
TBG_pngYZ="--png_e.period 10 --png_e.axis yz --png_e.slicePoint 0.5 --png_e.folder pngElectronsYZ"
TBG_pngYX="--png_e.period 10 --png_e.axis yx --png_e.slicePoint 0.5 --png_e.folder pngElectronsYX"

or similar? Contains only the makros that are used and a link to further documentation.

[f-schmitt]

Exactly. That's what I meant in the header anyway:

For a detailed description of PIConGPU
## configuration files including all available variables, see doc/CFG_FILES.

A second hint is fine, too.

[ax3l]

Great, agreed!

[f-schmitt]

@PrometheusPi could you please tell me the description for the --radiation flag, similar to --png below:

# ?
TBG_radiation="--radiation_e.period 1 --radiation_e.dump 2 --radiation_e.totalRadiation 1 \
               --radiation_e.lastRadiation 0 --radiation_e.start 2800 --radiation_e.end 3000"


# Create 2D images in PNG format every .period steps.
# Images can be created for the following particle species:
# - Electrons (--png_e)
# - Ions      (--png_i)
# The slice plane is defined using .axis [yx,yz] and .slicePoint (offset from origin
# as a float within [0.0,1.0].
# The output folder can be set with .folder.
TBG_E_pngYZ="--png_e.period 10 --png_e.axis yz --png_e.slicePoint 0.5 --png_e.folder pngElectronsYZ"

[PrometheusPi]

@f-schmitt-zih I will add this to the Plugin wiki as fast as possible (today)
Sorry for the delay.

[PrometheusPi]

@f-schmitt-zih
The description of the radiation flags is now in wiki:Plugins
If I should add these descriptions in the *.cfg files, tell me.

[ax3l]

Wow, 👍
I guess @f-schmitt-zih would love to read a two-liner instead of the full example, may we put in a link for the reader for extended documentation.

[f-schmitt]

That's totally fine, I can shorten these and put them in, thx for all the work!

[f-schmitt]

fixed with #153, closing