A validated hybrid transfer-matrix-method (TMM) and drift–diffusion (DD) solver for perovskite solar cells with Wentzel–Kramers–Brillouin (WKB) contact tunneling, traps, and mobile-ion effects

Accurate perovskite solar-cell simulation requires optical interference, carrier transport, recombination, selective contacts, interfacial tunneling, charged defects, and mobile-ion effects to be solved in a reproducible workflow. We present and validate a one-dimensional hybrid transfer-matrix-method (TMM)/drift–diffusion (DD) solver for planar perovskite solar cells. In contrast to mature general-purpose tools such as SCAPS, wxAMPS, commercial TCAD packages, and PSC-focused ion-transport solvers such as Driftfusion and IonMonger, the present workflow emphasizes an auditable Python implementation that combines coherent/hybrid optics, conservative TMM-to-DD source mapping, finite-volume Scharfetter–Gummel transport, charged traps, mobile ions, finite contacts, and full numerical Wentzel–Kramers–Brillouin (WKB) contact tunneling in one reproducible source package. Validation tests cover optical energy closure, generation-current conservation, Poisson/DD convergence, charged-trap residual and Jacobian consistency, Fermi–Dirac limiting behavior, WKB rectangular and triangular analytical limits, ion conservation, baseline JV behavior, and five literature-derived device stacks. An added contact-physics demonstration shows that a 0.55 eV electron-extraction barrier can reduce FF from 0.820 to 0.353 in a thermionic-only contact model, whereas including WKB tunneling through a 1 nm barrier recovers FF = 0.709 and increases PCE from 8.04% to 15.89%. For representative planar perovskite stacks, 21-point steady-state JV sweeps converge well below one second on a standard laptop, with all tested mesh sizes achieving 21/21 converged voltage points. Mesh/timing benchmarks and all scripts are supplied with the supplementary package.