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

The Korteweg–de Vries (KdV) equation is a foundational model in geophysical fluid dynamics (GFD), governing the propagation of long internal and surface gravity waves in stratified and shallow ocean environments where the interplay between nonlinear steepening and frequency-dependent dispersion gives rise to solitons. Although the analytical tractability of the KdV equation through inverse scattering is well established, systematic numerical exploration of multi-soliton interactions remains valuable for benchmarking solvers, probing conservation properties under varied oceanic initial conditions, and building intuition for more complex ocean wave phenomena. 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. The implementation leverages just-in-time (JIT) compilation to achieve research-grade computational efficiency on standard hardware, making it readily accessible for coastal and ocean engineering applications, including idealized modeling of internal solitary waves on continental shelves, rapid parameter studies for solitary wave propagation in stratified basins, and pedagogical investigations of nonlinear dispersive wave dynamics. The solver is validated through four progressively complex idealized scenarios motivated by oceanic wave dynamics: isolated soliton propagation, symmetric interactions, overtaking collisions, and three-body interactions. High-fidelity conservation of mass, momentum, and energy is demonstrated, with relative errors remaining below O(10−4) across all test cases. Measured soliton velocities align with theoretical predictions within 5%, confirming the capture of the amplitude-dependent dispersion characteristic of oceanic solitary waves. Complementary diagnostics, including spectral entropy and recurrence quantification analysis (RQA), verify that the numerical solutions preserve the regular phase-space structure characteristic of integrable Hamiltonian systems. These results establish sangkuriang as a robust, lightweight platform for reproducible numerical investigation of idealized nonlinear dispersive wave dynamics relevant to coastal and ocean engineering applications.