An Open-Source Pseudo-Spectral Solver for Idealized Korteweg-de Vries Soliton Simulations

Abstract

The Korteweg-de Vries (KdV) equation governs the propagation of nonlinear internal and surface gravity waves in shallow ocean environments, where the balance between nonlinear steepening and frequency-dependent dispersion produces solitons. This article presents sangkuriang, an open-source Python library that solves the KdV equation using Fourier pseudo-spectral spatial discretization and adaptive eighth-order Runge-Kutta time integration, accelerated via just-in-time (JIT) compilation. Validation across four progressively complex scenarios-isolated soliton propagation, symmetric interactions, overtaking collisions, and three-body interactions-demonstrates high-fidelity conservation of mass, momentum, and energy, with relative errors below $O(10^{-4})$. Measured soliton velocities agree with theoretical predictions within $5\%$, and complementary diagnostics based on spectral entropy and recurrence quantification analysis (RQA) confirm that computed solutions preserve the regular phase-space structure characteristic of integrable Hamiltonian systems. Running on a standard laptop, sangkuriang provides a robust, lightweight platform for reproducible numerical investigation of idealized nonlinear dispersive wave dynamics relevant to coastal and ocean engineering applications.