Configuration (YAML input)

Note

See descriptions of input parameters in the WarpX PICMI documentation

A simulation is defined by a single YAML file passed as input_file. The top level is a mapping with these sections:

Section	Required	Purpose
grid	yes	Geometry, resolution, and boundary conditions
solver	yes	Field solver (electromagnetic / -static / hybrid)
simulation	yes	Time stepping and global algorithm options
fields	no	Applied / initial fields (list)
lasers	no	Laser pulses (list) — not yet implemented
species	no	Particle species (list)
diagnostics	no	Output diagnostics (list)

Each section’s keys map directly onto the corresponding PICMI object. Every value listed by that PICMI class is accepted, including the warpx_* backend options; an unknown key raises a ValueError that names the offending field. The accepted value lists are also enumerated on warpx.warpx.WarpX.available.

grid

grid_type selects the geometry; the remaining keys are forwarded to the matching PICMI grid class.

Valid grid_type values:

• Cartesian3DGrid

• Cartesian2DGrid

• Cartesian1DGrid

• CylindricalGrid

grid:
  grid_type: Cartesian2DGrid
  number_of_cells: [64, 128]
  lower_bound: [-0.01, 0.0]
  upper_bound: [0.01, 0.02]
  lower_boundary_conditions: [dirichlet, dirichlet]
  upper_boundary_conditions: [dirichlet, dirichlet]
  lower_boundary_conditions_particles: [absorbing, absorbing]
  upper_boundary_conditions_particles: [absorbing, absorbing]
  warpx_potential_lo_z: 0.0
  warpx_potential_hi_z: 150.0e3

Common keys include number_of_cells, lower_bound / upper_bound, lower_boundary_conditions / upper_boundary_conditions (and the _particles variants), electrode potentials (warpx_potential_lo_* / warpx_potential_hi_*), warpx_max_grid_size, and warpx_blocking_factor. Cylindrical grids additionally take nr, nz, and n_azimuthal_modes.

solver

solver_type selects both the PICMI solver class and its method:

solver_type	Maps to
EM_Yee EM_CKC EM_Lehe	Electromagnetic (FDTD)
EM_PSTD EM_PSATD EM_GPSTD	Electromagnetic (spectral)
EM_DS EM_ECT	Electromagnetic
ES_FFT_LF ES_FFT_EMS	Electrostatic (FFT)
ES_FFT_EP ES_FFT_Rel	Electrostatic (FFT)
ES_MLMG_LF ES_MLMG_EMS	Electrostatic (Multigrid)
ES_MLMG_EP ES_MLMG_Rel	Electrostatic (Multigrid)
Hybrid_RK4 Hybrid_RKF45	Hybrid PIC

The electrostatic suffixes pick the physics model automatically:

• LF — labframe (standard)

• EMS — labframe electromagnetostatic (adds a magnetostatic solve)

• EP — labframe effective potential

• Rel — relativistic electrostatic

solver:
  solver_type: ES_MLMG_EMS
  required_precision: 1.0e-6
  warpx_magnetostatic_required_precision: 1.0e-6
  warpx_self_fields_verbosity: 0

Electromagnetic solvers accept cfl, stencil_order, and PML options; electrostatic solvers accept required_precision, maximum_iterations, and the warpx_magnetostatic_* / warpx_effective_potential_* options; hybrid solvers accept Te, n0, plasma_resistivity, and substep controls.

simulation

Time stepping and global algorithm selection. No *_type key — the keys map directly onto pywarpx.picmi.Simulation.

simulation:
  time_step_size: 1.0e-12
  max_time: 3.0e-10
  particle_shape: 1

Frequently used keys: time_step_size, max_steps, max_time, particle_shape, gamma_boost, and the many warpx_* algorithm options (deposition, gathering, pusher, load balancing, sorting, embedded boundary, collisions, …). Verbosity is taken from the constructor’s verbose flag.

fields

A list of applied or initial fields. field_type selects the kind:

field_type	Description
AnalyticInitial	Initial E/B from analytic expressions
ConstantApplied	Constant applied E/B
AnalyticApplied	Applied E/B from analytic expressions
FromFile	Load initial field from a file (path)
PlasmaLens	Plasma-lens array (starts/lengths)
Mirror	Field mirror

fields:
  - field_type: ConstantApplied
    Bz: 0.5
  - field_type: AnalyticApplied
    Ez_expression: "1e5 * sin(z)"

species

A list of particle species. Each entry requires a distribution-type and a layout; the remaining keys configure the species, its initial distribution, and its particle layout.

Distributions (distribution-type):

• GaussianBunch — needs n_physical_particles, rms_bunch_size

• Uniform — needs density

• Analytic — needs density_expression

• UniformFlux / AnalyticFlux — surface emission; need flux, flux_normal_axis, surface_flux_position, flux_direction

• ParticleList — explicit x/y/z/ux/uy/uz/weight

• FromFile — needs file_path

Layouts (layout):

• Gridded — n_macroparticle_per_cell

• PseudoRandom — n_macroparticles / n_macroparticles_per_cell / seed (required for flux injection)

species:
  - particle_type: electron
    name: electron
    distribution-type: UniformFlux
    flux: 6.241509e23
    flux_normal_axis: z
    surface_flux_position: 0.0
    flux_direction: 1
    flux_tmin: 0.0
    flux_tmax: 2.0e-11
    gaussian_flux_momentum_distribution: true
    rms_velocity: [1.5e5, 1.5e5, 1.5e5]
    layout: PseudoRandom
    n_macroparticles_per_cell: 4
    initialize_self_field: false

Tip

Use a standard species name (e.g. electron) so openPMD-beamphysics can resolve the particle mass/charge for energy and kinetic-energy plots.

diagnostics

A list of output diagnostics. diagnostic_type selects the kind:

diagnostic_type	Required keys	Notes
Particle	period	Per-species particle dumps
Field	period	Field grids (data_list)
TimeAveragedField	period	Time-averaged fields
ElectrostaticField	period	Electrostatic field grids
Reduced	period, reduced_type	Reduced (scalar) diagnostics
LabFrameParticle	num_snapshots, dt_snapshots	Back-transformed particles
LabFrameField	num_snapshots, dt_snapshots	Back-transformed fields

diagnostics:
  - diagnostic_type: Particle
    name: diag1
    period: 30
    species: [electron]
  - diagnostic_type: Field
    name: diag_fields
    period: 30
    data_list: [phi, rho, Ex, Ez]

Important

Unless you override them, non-reduced diagnostics default to warpx_format: openpmd with the h5 backend and are written to <path>/diags. This is what the plotting and archiving helpers expect. For a Particle / LabFrameParticle diagnostic, the species list must reference species names you defined above.