KMC Charge Transport Simulator (Nearest-Neighbor + Gaussian Site Energies)

This project runs a kinetic Monte Carlo (KMC) simulation of charge transport on a 3D cubic lattice with:

• Nearest-neighbor hopping only (6 neighbors: ±x, ±y, ±z)
• Periodic boundary conditions (PBC) for the walk inside the box
• Real/unwrapped displacement tracking so diffusion is computed from the true traveled displacement
• Gaussian site energies: each site has an energy sampled from a Normal distribution with sigma = 0.1 eV
• Marcus hopping rates using ΔG = E_j - E_i

---

Project layout

Typical structure:

• run_kmc.py
  Entry point (CLI runner)
• charge_transport_sim.yaml
  Simulation inputs
• requirements.txt
  Python dependencies
• kmc_sim/
  Package code (runner, trajectory, energy model, rates, config parsing, etc.)

---

Requirements

• Python 3.9+ recommended
• Packages:
  • numpy
  • pyyaml
  • tqdm
• Optional:
  • mpi4py (only if you want to run with MPI across multiple processes)

---

Setup (Windows + VS Code)

1. Open the project folder in VS Code.

2. Create and activate a virtual environment:

PowerShell

python -m venv .venv
.\.venv\Scripts\Activate.ps1

3. Install dependencies:

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

If you want MPI support:

python -m pip install mpi4py

---

Configuration (YAML)

Edit charge_transport_sim.yaml.

Key parts that can be changed:

• Sweeps:
  • T (temperature in K)
  • L (box size in lattice units, written as nm in output label)
• Energy landscape:
  • sigma_eV: 0.1 (Gaussian disorder)
• Progress:
  • show_progress: true

Example snippet:

simulation:
  rep_total: 20
  vary: "T" # "L" or "T"

sweeps:
  T: { start: 300, step: 50, end: 300 }
  L: { start: 100, step: 50, end: 100 }

energy:
  mean_eV: 0.0
  sigma_eV: 0.1
  seed: 3

output:
  data_dir: "Data"
  raw_dir: "RawData"
  save_raw: false
  show_progress: true

---

Run (single process)

From the project root (same folder as run_kmc.py):

python .\run_kmc.py -c .\charge_transport_sim.yaml

You should see progress bars (tqdm) during the repetitions, and console lines for each sweep point.

---

Run (MPI, optional)

If you have MPI installed and mpi4py installed, you can run e.g. with 4 processes:

mpiexec -n 4 python .\run_kmc.py -c .\charge_transport_sim.yaml

Notes:

• Only rank 0 shows tqdm progress (to avoid terminal chaos).
• Work is split across ranks by assigning repetitions to ranks.

---

Output

Results are written to the folder specified in YAML:

• Data/ contains a CSV file like:
  • data_L_YYYYMMDD_HHMMSS.csv or data_T_YYYYMMDD_HHMMSS.csv

CSV columns:

• sweep variable (L(nm) or T(K))
• Travel(nm)
• Time(ns)
• D(cm^2/s)
• mu(cm^2/Vs)
• standard errors: ±Travel, ±Time, ±D, ±Mu

---

Web Application

A modern web interface is available for running simulations and visualizing results.

• Location: webapp/ directory.
• Run: Execute ./run_app.sh from the root directory.
• Access: Open http://localhost:5173.

See webapp/README.md for full details.

---

Common issues

• No progress bar appears

  • Ensure tqdm is installed: python -m pip show tqdm
  • Ensure show_progress: true in YAML

• Import errors

  • Make sure your venv is activated
  • Reinstall: python -m pip install -r requirements.txt

---

How it works (short)

At each KMC step:

1. Read current site energy E_i
2. For each of 6 neighbors, compute E_j
3. Compute Marcus rates k_ij from ΔG = E_j - E_i
4. Total rate K = Σ k_ij (plus optional recombination rate)
5. Sample time increment Δt ~ Exp(K)
6. Choose next hop with probability k_ij / K
7. Apply PBC for coordinates but update image counters to preserve real displacement