sangkuriang: A pseudo-spectral Python library for Korteweg-de Vries soliton simulation

TL;DR

This work presents sangkuriang, an open-source Python library for solving the Korteweg-de Vries (KdV) equation using Fourier pseudo-spectral spatial discretization and adaptive high-order time integration, accelerated by Numba JIT. The approach enforces accurate soliton dynamics through spectral derivatives and a DOP853 time-stepping scheme, with NetCDF CF-conformant outputs and diagnostic tools for conservation, soliton tracking, and phase-space structure. Validation across four test cases demonstrates conservation of the invariants $M$, $P$, and $E$ to $10^{-7}$–$10^{-4}$ relative error and soliton velocities consistent with the theoretical relation $v = εA/3$, while information-theoretic measures and RQA corroborate integrable-like behavior. The tool balances numerical fidelity with accessibility on modest hardware, making it suitable for classroom demonstrations and preliminary soliton-dynamics research, and it lays groundwork for future extensions to exact initial data, topography variation, and higher-dimensional generalizations such as the KP equation.

Abstract

The Korteweg-de Vries (KdV) equation serves as a foundational model in nonlinear wave physics, describing the balance between dispersive spreading and nonlinear steepening that gives rise to solitons. This article introduces sangkuriang, an open-source Python library for solving this equation using Fourier pseudo-spectral spatial discretization coupled with adaptive high-order time integration. The implementation leverages just-in-time (JIT) compilation for computational efficiency while maintaining accessibility for instructional purposes. Validation encompasses progressively complex scenarios including isolated soliton propagation, symmetric two-wave configurations, overtaking collisions between waves of differing amplitudes, and three-body interactions. Conservation of the classical invariants is monitored throughout, with deviations remaining small across all test cases. Measured soliton velocities conform closely to theoretical predictions based on the amplitude-velocity relationship characteristic of integrable systems. Complementary diagnostics drawn from information theory and recurrence analysis confirm that computed solutions preserve the regular phase-space structure expected for completely integrable dynamics. The solver outputs data in standard scientific formats compatible with common analysis tools and generates visualizations of spatiotemporal wave evolution. By combining numerical accuracy with practical accessibility on modest computational resources, sangkuriang offers a platform suitable for both classroom demonstrations of nonlinear wave phenomena and exploratory research into soliton dynamics.

Figures (6)

• Figure 1: Schematic of the shallow water wave domain. The fluid occupies a region bounded below by a rigid horizontal bottom at $z = 0$ and above by a free surface at $z = h_0 + \eta(x,t)$, where $h_0$ denotes the undisturbed water depth and $\eta(x,t)$ represents the free surface displacement. Gravitational acceleration $g$ acts in the negative $z$-direction, and wave propagation occurs along the $x$-axis with phase speed $c$.
• Figure 2: Conservation law diagnostics. (a) Relative mass deviation $(M - M_0)/|M_0|$; (b) relative momentum deviation $(P - P_0)/|P_0|$; (c) relative energy deviation $(E - E_0)/|E_0|$; (d) maximum relative errors across all cases on logarithmic scale. Solid blue: single soliton (C1); dashed orange: two equal solitons (C2); dash-dotted green: soliton collision (C3); dotted red: three solitons (C4).
• Figure 3: Three-dimensional spatiotemporal evolution of the wave amplitude $u(x,t)$ for the four test cases. (a) Single soliton propagating rightward; (b) two equal-amplitude solitons; (c) overtaking collision between fast (tall) and slow (short) solitons; (d) three-soliton interaction. Color scale indicates amplitude in meters. View angles: elevation $25^\circ$, azimuth $-55^\circ$.
• Figure 4: Soliton trajectory analysis. (a) Space-time contour plot for single soliton with tracked trajectory (dashed line); (b) collision case showing fast (dark red) and slow (blue) soliton tracks with collision region indicated; (c) measured velocity versus amplitude with theoretical relation $v = \varepsilon A/3$ (solid line); (d) wave profiles at selected times during collision, vertically offset for clarity.
• Figure 5: Spectral and information-theoretic analysis. (a) Power spectral density $P(k)$ at initial time for all cases; (b) normalized spectral entropy $S_k(t)$; (c) LMC statistical complexity $C(t) = H \times D$; (d) Fisher information $F(t)$. Line styles as in Figure \ref{['fig:conservation']}.