From 1702c174ff255c2c8f949c239b3350cee3d147ad Mon Sep 17 00:00:00 2001 From: BrianMarre Date: Mon, 29 Jul 2024 10:38:37 +0200 Subject: [PATCH] bare bones documentation --- docs/source/usage/picmi/intro.rst | 60 +++++++++++++++---- .../python/picongpu/compiling/distribution.py | 1 + test/python/picongpu/compiling/species.py | 1 + 3 files changed, 52 insertions(+), 10 deletions(-) diff --git a/docs/source/usage/picmi/intro.rst b/docs/source/usage/picmi/intro.rst index 6fd4217521..97b07719ac 100644 --- a/docs/source/usage/picmi/intro.rst +++ b/docs/source/usage/picmi/intro.rst @@ -113,13 +113,31 @@ Parameters/Methods prefixed with ``picongpu_`` are PIConGPU-exclusive. - **Simulation** - - ``__init__(..., picongpu_template_dir)``: + additional constructor/configuration options: + - ``picongpu_template_dir``: Specify the template dir to use for code generation, please refer to :ref:`the documentation on the matter for details ` - - ``__init__(..., picongpu_typical_ppc)`` typical ppc to be used for normalization in PIConGPU + - ``picongpu_typical_ppc``: + typical ppc to be used for normalization in PIConGPU, if not set explicitly, PIConGPU will use the median ppc of all defined species + - ``picongpu_moving_window_move_point``: + portion of the simulation window a light ray reaches from the time of the start of the simulation until the simulation window begins to move. + + .. warning:: + + If the moving window is active, one gpu in y direction is reserved for initializing new spaces, thereby reducing the simulation window size accordingly + + - ``picongpu_moving_window_stop_iteration``: + iteration at which to stop moving the simulation window + - ``picongpu_interaction``: + ``Interaction`` object specifying all interactions of the simulation, i.e. all ionization models and their configurations and so on. + This replaces the PICMI ``add_interaction`` method. + + additional method arguments: - ``write_input_file(..., pypicongpu_simulation)``: use a :ref:`PyPIConGPU simulation` object instead of an PICMI- simulation object to generate a PIConGPU input. - - ``get_as_pypicongpu()``: + + additional methods: + - ``get_as_pypicongpu()``: convert the PICMI simulation object to an equivalent :ref:`PyPIConGPU ` simulation object. - ``picongpu_get_runner()``: Retrieve a :ref:`PyPIConGPU Runner ` for running a PIConGPU simulation from Python, **not recommended** @@ -128,6 +146,11 @@ Parameters/Methods prefixed with ``picongpu_`` are PIConGPU-exclusive. This may be used in conjunction with custom templates to change the code generation. See :ref:`PICMI custom code generation` for the documentation on using custom input. + not supported methods: + - ``add_interaction(self, interaction)``: + The PIConGPU PICMI interface does not support the PICMI interaction specification, due to PICMI standard ambiguities. + Instead you must use the PIConGPU specific ``Interaction`` interface described below. + - **Grid** - ``picongpu_n_gpus``: @@ -150,17 +173,34 @@ Parameters/Methods prefixed with ``picongpu_`` are PIConGPU-exclusive. - **Species** - - ``picongpu_ionization_electrons``: - Electron species to use for ionization. - Optional, will be guessed if possible. - - ``picongpu_fully_ionized``: - When defining an element (using ``particle_type``) it may or may not be ionizable + - ``picongpu_fixed_charge``: + When defining an ion species using ``particle_type`` it may or may not be ionizable + + - to **enable** ionization add an ionization model to the Interaction object of the simulation and set the initial charge state using ``charge_state``. + - to **disable** ionization set ``picongpu_fixed_charge=True``, this will fix the charge of particles of this species for entire simulation. - - to **enable** ionization simulation set ``charge_state`` to an integer - - to **disable** ionization (ions are only core without electrons) set ``picongpu_fully_ionized=True`` + ``picongpu_fixed_charge`` maybe combined with ``charge_state`` to control which charge state is to used for the ion species If neither is set a warning is printed prompting for either of the options above. +- **Interaction** + Configuration of the PIC-algorithm extensions, use as follows: + + .. code:: python + + from picongpu import picmi + from picongpu.interaction.ionization.fieldionization import ADK, ADKVariant + + e = picmi.Species(name="e", particle_type="electron") + nitrogen = picmi.Species(name="nitrogen", particle_type="N", charge_state=2) + + ADK_ionization = ADK(ADK_variant = ADKVariant.LinearPolarization, ion_species = nitrogen, ionization_electron_species=e) + interaction = Interaction(ground_state_ionizaion_model_list=[ADK_Ionization]) + + sim = picmi.simulation(picongpu_interaction=interaction) + sim.add_species(e, ...) + sim.add_species(nitrogen, ...) + Output ^^^^^^ Output is currently **not configurable** for picongpu using the PICMI interface. diff --git a/test/python/picongpu/compiling/distribution.py b/test/python/picongpu/compiling/distribution.py index 38d8118643..fc52acccd6 100644 --- a/test/python/picongpu/compiling/distribution.py +++ b/test/python/picongpu/compiling/distribution.py @@ -36,6 +36,7 @@ def _compile_distribution(self, distribution): particle_type="H", charge_state=0, initial_distribution=distribution, + picongpu_fixed_charge=True, ) self.sim.add_species(species_hydrogen, random_layout) runner = Runner(self.sim) diff --git a/test/python/picongpu/compiling/species.py b/test/python/picongpu/compiling/species.py index f59471f2ac..2d902de3ac 100644 --- a/test/python/picongpu/compiling/species.py +++ b/test/python/picongpu/compiling/species.py @@ -52,6 +52,7 @@ def test_hydrogen_atoms(self): charge_state=0, initial_distribution=uniform_dist, density_scale=3, + picongpu_fixed_charge=True, ) random_layout = picmi.PseudoRandomLayout(n_macroparticles_per_cell=2)