Intro

This is a brief overview over PICMI.

Example

from picongpu import picmi

boundary_conditions = ["periodic", "periodic", "periodic"]
grid = picmi.Cartesian3DGrid(
    # note: [x] * 3 == [x, x, x]
    number_of_cells=[192] * 3,
    lower_bound=[0, 0, 0],
    upper_bound=[0.0111152256] * 3,
    # delta {x, y, z} is computed implicitly
    # lower & upper boundary conditions must be equal
    lower_boundary_conditions=boundary_conditions,
    upper_boundary_conditions=boundary_conditions,
)
solver = picmi.ElectromagneticSolver(method="Yee", grid=grid)

profile = picmi.UniformDistribution(
    density=1e20,
    # most probable E_kin = 5 mc^2
    # approx. 9000 keV for electrons
    # must be equal for all three components
    rms_velocity=[4.18 * picmi.constants.c] * 3,
)
electron = picmi.Species(
    name="e",
    # openPMD particle type
    particle_type="electron",
    initial_distribution=profile,
)

sim = picmi.Simulation(
    time_step_size=9.65531e-14,
    max_steps=1024,
    solver=solver,
)

layout = picmi.PseudoRandomLayout(n_macroparticles_per_cell=25)
sim.add_species(electron, layout)

sim.write_input_file("generated_input")

Creates a directory generated_input, where you can run pic-build and subsequently tbg.

Generation Results

The recommended way to use the generated simulations is to

  1. create the simulation in PICMI

  2. call Simulation.write_input_file(DIR)

  3. use the normal PIConGPU toolchain (pic-build, tbg)

Note

Rationale: PICMI does not (yet) support enough parameters to meaningfully control the execution process.

Additionally, the following methods work (but are not recommended):

  • call Simulation.step(NUM)

    • directly builds and runs the simulation

    • NUM must be the maximum number of steps

    • has no diagnostic output (i.e. console hangs without output)

  • call Simulation.picongpu_run()

    • equivalent to Simulation.step() with the maximum number of steps

  • use the PyPIConGPU runner

Output

Warning

This is subject to change.

Output is currently not configurable.

Some output is automatically enabled, including PNGs. For this the period is chosen that the output is generated (approx.) 100 times over the entire simulation duration.

To configure output you must change the generated files.

Unsupported Features

You will be alerted for unsupported features.

Either a warning is printed or an error thrown (including because a class does not exist). In this case read the error message to fix this.

For reference you can see how the tests in $PICSRC/test/python/picongpu/quick/picmi use the interface.

Reference

The full PICMI reference is available upstream.

Extensions

Parameters/Methods prefixed with picongpu_ are PIConGPU-exclusive.

Warning

We strive to quickyl contribute these parameters to PICMI upstream, so this list is to be considered volatile.

  • Simulation

  • Grid

    • picongpu_n_gpus: list of a 1 or 3 integers, greater than zero, describing GPU distribution in space 3-integer list: [N_gpu_x, N_gpu_y, N_gpu_z] 1-integer list: [1, N_gpu_y, 1] Default is None equal to [1, 1, 1]

  • Gaussian Laser

    • Laguerre Modes (picongpu_laguerre_modes and picongpu_laguerre_phases): Two lists of float, passed to PIConGPU laser definition

  • 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

      • to enable ionization simulation set charge_state to an integer

      • to disable ionization (ions are only core without electrons) set picongpu_fully_ionized=True

      If neither is set a warning is printed prompting for either of the options above.