ePIC++: Electrostatic 2D-3V Particle-in-Cell Code

Overview

This project implements a 2D-3V electrostatic particle-in-cell simulation with MPI parallelization. It solves the Vlasov-Poisson system for charged particles interacting via self-consistent electric fields, supporting distributed-memory architectures.

Key Features

• 2D-3V PIC algorithm: Self-consistent update of particles and fields.
• MPI Parallelization: 1D slab decomposition with MPI to distribute particles and fields.
• Multiple Poisson Solvers: Spectral, Gauss-Seidel, PCG, and hybrid methods.
• Monte Carlo Collisions: Elastic, excitation, and ionization collisions.
• Custom Grids and Electrodes: Reactive conductor and circular grids.
• Particle Emitters: Configurable line emitters for one or two species.
• Flexible Normalization: Electron, ion, mixed, or user-defined schemes.
• HDF5 Output: Field and particle data in hierarchical HDF5 format.
• Python Postprocessing: Scripts for energy plots, dispersion, and phase-space animations.

Directory Structure

project_root/
├── CMakeLists.txt         # Build configuration
├── Doxyfile               # Doxygen documentation settings
├── include/               # Header files
├── src/                   # Core source files
├── linearalgebra/         # Custom matrix and solver routines
├── python_scripts/        # Postprocessing and visualization scripts
├── inputfiles/            # Sample INI configuration files
├── tests/                 # Unit and performance tests
├── build/                 # Out-of-source build directory
├── data/                  # Example output and plots
├── LICENSE
└── README.md

Requirements

• C++17 compiler (GCC, Clang)
• CMake ≥ 3.22
• MPI (OpenMPI, MPICH)
• FFTW3 (+ fftw3-mpi for spectral solver)
• HDF5 C/C++ libraries
• Python 3 with dev headers
• Python packages: NumPy, SciPy, Matplotlib

Installation

1. Clone the repository:

   git clone https://github.com/org/ePIC2D_mcc.git
   cd ePIC2D_mcc

2. Configure project:

   cmake -B build -S . -DCMAKE_BUILD_TYPE=Release

3. Build:

   cmake --build build -j

4. Run tests:

   ctest --output-on-failure

Usage

Run simulation with:

mpirun -np <ranks> ./build/ePIC++ inputfiles/input.ini

Input File Sections

The input.ini file configures the simulation. Each section groups parameters for a specific aspect of the run.

[file]

Parameter	Description
output	Path to directory where simulation output (HDF5) is saved

[time]

Parameter	Description
NUM_TS	Total number of time steps to run
DT_coeff	Time step as a fraction of (1/frequency): dt = DT_coeff / ω_pe or dt = DT_coeff / ω_pi

[diagnostics]

Parameter	Description
write_interval	Interval (in steps) to write density/field data
write_interval_phase	Interval (in steps) to write phase-space data
write_diagnostics	Interval (in steps) to print diagnostics (energies, phase plot, etc.)
write_flag	What to write to disk: 0=none, 1=all, 2=fields only, 3=phase-space only
save_fig	Save plots as images (1=yes, 0=no) (deprecated)
sub_cycle_interval	Frequency (in steps) of ion sub-cycling
precision	Floating-point precision level
diagtype	Diagnostics type: off (time only), basic (time + max_phi), full (everything + live plot)

[PlotFlags]

Flag	Description
phase_space	Phase-space plot: 1=x-vx, 2=y-vy
config_space	Configuration plot: 1=x-y, 2=vx-vy (vx-vy not implemented)
electric_field	Electric field plot: 1=Ex, 2=Ey
potential_field	Enable potential field plotting
density_contour	Plot species density contour
ke_components	Plot kinetic energy components (x, y, z)
total_energy	Plot total energy evolution
species_index	Species index for phase-space/density (0=first species, 1=second, ...)

[domain]

Parameter	Description
nx	Number of grid points along x axis
ny	Number of grid points along y axis
x0	Origin x-coordinate of the domain
y0	Origin y-coordinate of the domain

[Grids]

Property	Description
grid_count	Number of grids (grid_0, grid_1, ...)
type	Grid type: reactconduct (biased), circular (biased)
min_x, max_x	X-range (cell indices) for reactive conductor grid
min_y, max_y	Y-range (cell indices) for reactive conductor grid
grid_voltage	Voltage applied to the grid (Volts)
x_center, y_center	Center coordinate of circular grid
electrode_number	Number of electrodes composing the circular grid
grid_radius	Radius of the circular grid
electrode_radius	Radius of each electrode

Example:

grid_count = 3

# Reactive conductor grids
grid_0.type = reactconduct
grid_0.min_x = 0
grid_0.min_y = 30
grid_0.max_x = 22
grid_0.max_y = 31
grid_0.grid_voltage = 100

grid_1.type = reactconduct
grid_1.min_x = 10
grid_1.min_y = 20
grid_1.max_x = 30
grid_1.max_y = 40
grid_1.grid_voltage =  50

# Circular grid
grid_2.type = circular
grid_2.x_center = 40
grid_2.y_center = 25
grid_2.electrode_number = 10
grid_2.grid_radius = 8
grid_2.electrode_radius = 1
grid_2.electrode_voltage = -100

[Emitters]

Property	Description
x0, y0	Starting coordinate of emitter line (grid units)
x1, y1	Ending coordinate of emitter line (grid units)
temp	Emission temperature (ignored if 0)
numparticle	Number of particles injected per time step
vdx, vdy	Initial velocity components of injected particles
species_idx1	Index of the first species to emit
species_idx2	Index of the second species to emit

If species_idx1==species_idx2, only one species is emitted.

Example:

count = 1  # number of emitters

emitter_0.x0 = 1
emitter_0.y0 = 20
emitter_0.x1 = 1
emitter_0.y1 = 30
emitter_0.temp = 0
emitter_0.numparticle = 1
emitter_0.vdx = 2.0
emitter_0.vdy = 0.0
emitter_0.species_idx1 = 0
emitter_0.species_idx2 = 1

[normalization]

Parameter	Description
norm_scheme	Normalization scheme: 1=electron, 2=ion, 3=subcycling, 4=mixed, 5=mixed
vel_norm_scheme	Velocity normalization: 1=vthe, 2=vthi, 3=vcs (ion-acoustic speed)
length_scale	User-defined characteristic length scale
time_scale	User-defined characteristic time scale (e.g., 1/ω_pe)
energy_scale	User-defined characteristic energy scale

[simulation]

Parameter	Description
shapefunction	Interpolation scheme: NGP, CIC
push_parallel	Enable parallel particle push (1=yes)
deposit_parallel	Enable parallel charge deposition (1=yes)
density	Background plasma density
bc	Boundary condition: pbc (periodic), open
see_rate	Secondary electron emission rate (not implemented)
tempwall	Wall temperature (not implemented)
ionfixed	Fixed background ions (1=yes, 0=no)

[solver]

Parameter	Description
solvertype	Poisson solver: gs, pcg, spectral (spectral for PBCs)
tolerance	Convergence tolerance for iterative solvers
max_iteration	Maximum iterations for iterative solvers

[collision]

Parameter	Description
elastic	Enable elastic collisions (true/false)
excitation	Enable excitation collisions
ionization	Enable ionization collisions
GAS_DENSITY	Neutral gas density (e.g., 1e20)
collgroup	Collision group pairs (e.g., 12,21 means species 1 with neutrals of 2, etc.)

[species]

Each line defines a species:

name, mass, number_of_particles, temperature, charge_sign, density_fraction,
stream_velocity_x, stream_velocity_y, load_type

Example:

electron, 9.109e-31, 50000, 1, -1, 1, -10, 0, uniform
ion,      6.633e-26, 50000, 0,  1, 0,  0,  0, uniform
beam,     9.109e-31, 50000, 1, -1, 1,  10, 0, uniform

Note: Electron must be the first line, Ion the second, followed by others.

Output

Data in <output>/result.h5 with:

• /fielddata: potential and E fields
• /den_<species>: density contours
• /particle_<species>: positions and velocities
• /time_var: kinetic and potential energy time series
• /metadata, /metadata_species: simulation parameters

Use Python scripts:

python3 python_scripts/energy_plot.py <output>
python3 python_scripts/dispersion_test.py <output>
python3 python_scripts/phase_config_animate.py <output>

Contributing

• Fork and PR
• Follow C++17, clang-format, Doxygen style
• Add tests under tests/

License

Licensed under GPL-3.0 (see LICENSE).