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
create the simulation in PICMI
call
Simulation.write_input_file(DIR)
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 stepshas 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
picongpu_get_runner()
: Retrieve a PyPIConGPU Runnerpicongpu_template_dir
: Specify the template dir to use for code generation, please refer to the documentation on the matter for details
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 isNone
equal to[1, 1, 1]
Gaussian Laser
Laguerre Modes (
picongpu_laguerre_modes
andpicongpu_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 (usingparticle_type
) it may or may not be ionizableto enable ionization simulation set
charge_state
to an integerto 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.