[PICMI] Add ionization model configuration support

[BrianMarre]

adds the ability to configure ionization model interactions in the PIConGPU-PICMI interface.

replaces PR #4985

• [x] update documentation
• [x] add LWFA PICMI script as user example
• [x] add Test for Ionization configuration
• [ ] verify correct rendering of LWFA with Richard

also fixes a bug in the initialization configuration of the boundElectrons attribute, noticed in the refactoring of the SetBoundElectrons Operation, renamed in this PR to SetChargeState.

[mafshari64]

I reviewed the contents for PICMI collisional ionization.

[chillenzer]

Just for the record: @PrometheusPi takes over the merge after verifying that the rendered input files look correct.

[PrometheusPi]

The tbg issue is not caused by the pull request but a general bug in PIConGPU right now: #5026 Thus, I removed my "changes required".

[PrometheusPi]

I looked into the pngs at iteration 3520, and they differ (not only in color) but in where the elecrons ae created: dev:

picmi:

[PrometheusPi]

In contrast to a previous (now corrected) post, I do not belief that the error is with PIConGPU dev case 2, but with picmi.

The PICMI setup states:

ENABLE_IONS = True
ENABLE_IONIZATION = True

But, while there are ions included, according to the macro particle counter, electrons are initially present which should not be the case for the ENABLE_IONIZATION = True (as long as the laser in not there):

[BrianMarre]

The example mistakenly always added electrons even if ionization was activated. Fixed

[PrometheusPi]

@BrianMarre You last commit now causes an error when running the script:

$ python lwfa_picmi_setup2.py
Traceback (most recent call last):
  File "/...//_pr_5007/lwfa_picmi_setup2.py", line 204, in <module>
    sim.write_input_file(OUTPUT_DIRECTORY_PATH)
  File "/...//_pr_5007/picongpu/lib/python/picongpu/picmi/simulation.py", line 394, in write_input_file
    pypicongpu_simulation = self.get_as_pypicongpu()
  File "/...//_pr_5007/picongpu/lib/python/picongpu/picmi/simulation.py", line 458, in get_as_pypicongpu
    s.init_manager = self.__get_init_manager()
  File "/...//_pr_5007/picongpu/lib/python/picongpu/picmi/simulation.py", line 361, in __get_init_manager
    self.__fill_in_ionization_electrons(pypicongpu_by_picmi_species, ionization_model_conversion_by_species)
  File "/...//_pr_5007/picongpu/lib/python/picongpu/picmi/simulation.py", line 339, in __fill_in_ionization_electrons
    self.picongpu_interaction.fill_in_ionization_electron_species(
  File "/...//_pr_5007/picongpu/lib/python/picongpu/picmi/interaction/interaction.py", line 126, in fill_in_ionization_electron_species
    pypicongpu_ionization_electron_species = pypicongpu_by_picmi_species[
KeyError: <picongpu.picmi.species.Species object at 0x2aaab29bbd90>

[BrianMarre]

@PrometheusPi forgot to add a non placed electron species in the enable ionization case, fixed the example script and improved the error message printed to the user to make the error easier to understand.

[PrometheusPi]

Your second change fixed the setup.

[BrianMarre]

One CI job failed to acess the github repository, @PrometheusPi coulde you please restart it?

[chillenzer]

@BrianMarre @PrometheusPi What's the status of this?

[BrianMarre]

Richard is still in the process of doing an intial review, then I will split up the PR in several independent PRs. At least that is the current plan

[chillenzer]

Thanks for the update. I'll keep quiet then.

[BrianMarre]

Well ... since you ask, you could take over part of the review. ;)

[psychocoderHPC]

I set this PR to draft that it not get merged see: https://github.com/ComputationalRadiationPhysics/picongpu/pull/5007#issuecomment-2341357981

[BrianMarre]

rebased PR against current dev

[PrometheusPi]

FYI: do to the sheer size of this PR, I just took a brief look at the later files as I already saw that his needs to be splitt up anyway.

[BrianMarre]

Rebased to the current dev,

All reviewer comment changes are in last commit for easier review of last changes.

[BrianMarre]

Switched from pdg to particle due to pdg using the distutils removed with python 3.12 causing installs of pdg to fail

[BrianMarre]

@psychocoderHPC please restart the Ci jobs, the failed due to an un specified timeout without an error log