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

TL;DR

This paper introduces sangkuriang, an open-source Python library that accurately simulates KdV soliton dynamics using spectral methods and adaptive time-stepping, validated across various complex wave interactions.

Contribution

The paper presents sangkuriang, a novel open-source Python tool for high-fidelity KdV soliton simulations with efficient spectral discretization and validation against theoretical and complex interaction scenarios.

Findings

High conservation of mass, momentum, and energy with errors below 10^{-4}

Soliton velocities match theoretical predictions within 5%

Spectral entropy and RQA confirm preservation of integrable phase-space structure

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.