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

This paper introduces *sangkuriang*, an open-source Python library that utilizes Fourier pseudo-spectral methods and JIT-accelerated Runge-Kutta integration to accurately simulate Korteweg-de Vries soliton dynamics, demonstrating high-fidelity conservation laws and phase-space preservation across various interaction scenarios.

The Gist

Imagine the ocean as a giant, calm stage. Usually, when you throw a stone into a pond, you get ripples that spread out, get smaller, and disappear. But in certain parts of the ocean, something magical happens: the waves don't fade away. Instead, they lock together into a single, perfect, self-sustaining "hump" that travels for miles without losing its shape. Scientists call these solitons. They are like the "indestructible superheroes" of the wave world.

This paper introduces a new, free computer tool called Sangkuriang (named after a famous Indonesian folk hero) designed to simulate these waves on a regular laptop. Here is a simple breakdown of what the researchers did and why it matters.

1. The Problem: Predicting the Unpredictable

In the real ocean, waves are messy. They crash, they mix, and they change shape. However, there is a famous math equation (the Korteweg–de Vries or KdV equation) that describes how these perfect "soliton" waves behave. It's like a rulebook for how these waves should dance.

While mathematicians have known the rules for a long time, actually watching these waves interact on a computer is hard. If the computer simulation isn't perfect, the waves might lose their energy, break apart, or act weirdly, making the results useless for real-world ocean studies.

2. The Solution: The "Sangkuriang" Simulator

The authors built a new software library called Sangkuriang. Think of it as a high-speed, ultra-accurate digital aquarium.

• The Engine: It uses a clever math trick called "pseudo-spectral methods." Imagine trying to draw a smooth curve. Instead of connecting dots with straight lines (which looks jagged), this tool uses a "Fourier" approach, like drawing with a perfectly smooth, continuous brush. This makes the waves look incredibly realistic.
• The Speed: Usually, high-precision math is slow and requires supercomputers. But the authors used a special "turbocharger" (called Numba) that lets the software run incredibly fast on a standard laptop. It's like taking a bicycle and giving it a jet engine; it can do the work of a supercomputer in minutes.
• The Timekeeper: It uses an "adaptive" clock. If the waves are calm, the clock ticks slowly to save time. If two waves crash into each other, the clock speeds up to capture every tiny detail of the collision.

3. The Test Drive: Four Scenarios

To prove the tool works, they ran four different "race tracks" (simulations):

1. The Solo Run: A single wave travels across the screen.
   • Result: It kept its shape perfectly, just like a superhero gliding through the air.
2. The Mirror Match: Two identical waves travel side-by-side.
   • Result: They stayed perfectly parallel, never bumping into each other.
3. The Overtake: A fast, tall wave chases a slow, short wave and passes it.
   • Result: This is the tricky part. When they collided, they merged into a giant spike, then separated. The tall wave came out looking exactly the same as before, and the short wave did too. They didn't crash; they just "bounced" off each other elastically.
4. The Three-Way Dance: Three waves of different sizes chasing each other.
   • Result: A complex choreography where the biggest wave eventually caught up to the others. The simulation handled the chaos without breaking.

4. The "Health Check": Did the Physics Hold Up?

In the real world, energy and momentum are never created or destroyed; they are just moved around. The researchers checked if their computer waves followed these laws.

• The Conservation Score: They measured "Mass," "Momentum," and "Energy." The computer simulation was so accurate that the errors were smaller than a grain of sand on a beach (less than 0.01%).
• The "Fingerprint" Test: They used advanced math (like checking a fingerprint) to see if the waves were behaving like true solitons. The results showed that the waves maintained their "identity" perfectly, proving the simulation wasn't just a pretty picture—it was mathematically honest.

5. Why Should You Care?

You might think, "I don't need to simulate waves on my laptop." But here is the real-world impact:

• Safety: These waves (called Internal Solitary Waves) can be huge and invisible. They can slam into oil rigs, damage underwater cables, or mess up sonar signals for submarines.
• Accessibility: Before this, you needed a massive, expensive supercomputer to study these waves. Now, a graduate student or a researcher with a standard laptop can run these simulations in minutes.
• Open Source: The code is free. Anyone can download it, tweak it, and use it to understand the ocean better.

The Bottom Line

The authors created a digital time machine for ocean waves. It allows scientists to watch how these mysterious, perfect waves interact, collide, and travel with extreme precision, all without needing a supercomputer. It's a powerful new tool that helps us understand the hidden, energetic dance happening beneath the ocean's surface.

Technical Summary

1. Problem Statement

The Korteweg–de Vries (KdV) equation is a foundational model in geophysical fluid dynamics (GFD) describing the propagation of long internal and surface gravity waves in stratified, shallow environments. While the equation is analytically integrable (admitting exact soliton solutions via inverse scattering), systematic numerical exploration remains critical for:

• Benchmarking solvers under varied initial conditions.
• Probing conservation properties (mass, momentum, energy) in multi-soliton interactions.
• Building intuition for complex ocean wave phenomena like overtaking collisions and wave trains.

Existing numerical tools often lack a balance between computational efficiency (required for long-time integration), accessibility (running on standard hardware), and diagnostic depth (verifying integrability beyond visual inspection). The authors address the need for a lightweight, open-source, high-fidelity Python library capable of research-grade simulations of idealized oceanic soliton dynamics.

2. Methodology

The paper introduces sangkuriang, an open-source Python library designed to solve the KdV equation using a hybrid numerical approach optimized for performance and accuracy.

Mathematical Formulation

The solver targets the dimensionless KdV equation:
$$\frac{\partial u}{\partial t} + \epsilon u \frac{\partial u}{\partial x} + \mu \frac{\partial^3 u}{\partial x^3} = 0$$
where $u$ is the wave amplitude, $\epsilon$ represents nonlinearity, and $\mu$ represents dispersion. The equation balances nonlinear steepening against frequency-dependent dispersion, allowing for shape-preserving soliton solutions.

Numerical Scheme

• Spatial Discretization: The solver employs a Fourier pseudo-spectral method. Spatial derivatives are computed in wavenumber space using the Fast Fourier Transform (FFT). This approach offers exponential convergence for smooth periodic solutions and naturally handles the dispersive operator.
• Time Integration: The semi-discrete system is integrated using the Dormand–Prince 8(5,3) (DOP853) method, an adaptive eighth-order explicit Runge–Kutta scheme with embedded error estimators. This allows for rigorous control of local truncation errors.
• Performance Optimization:
  • JIT Compilation: Critical pointwise operations (nonlinear and dispersive terms) are accelerated using Numba (Just-In-Time compilation), translating Python code to optimized machine code via LLVM.
  • Parallelization: The implementation utilizes multi-core CPU parallelization (via OpenMP-style threading in Numba) for element-wise calculations, achieving significant speedups (5x–50x) over standard interpreted NumPy operations.
  • Data Handling: Outputs follow NetCDF (Climate and Forecast conventions) for interoperability with standard oceanographic tools.

Validation & Diagnostics

The solver was validated against four progressively complex idealized scenarios motivated by oceanic wave dynamics:

1. Single Soliton Propagation: Baseline shape preservation.
2. Symmetric Two-Soliton Interaction: Equal-amplitude waves maintaining separation.
3. Overtaking Collision: Unequal amplitudes where a faster, larger soliton overtakes a slower one.
4. Three-Body Interaction: A rank-ordered packet of three solitons with sequential collisions.

Beyond standard error metrics, the authors employed advanced information-theoretic diagnostics:

• Conservation Laws: Monitoring Mass ($M$), Momentum ($P$), and Energy ($E$) to ensure $dM/dt, dP/dt, dE/dt \approx 0$.
• Spectral Entropy & LMC Complexity: Quantifying the spectral distribution and structural complexity of the wave field.
• Fisher Information: Measuring the sharpness/localization of wave gradients.
• Recurrence Quantification Analysis (RQA): Analyzing phase-space trajectories to confirm the system remains on low-dimensional invariant manifolds (indicating integrability) rather than drifting into chaotic behavior.

3. Key Results

The sangkuriang solver was tested on a standard laptop workstation (Intel Core i7, 8 cores) without high-performance computing (HPC) resources.

• Computational Efficiency:

  • The solver achieved throughputs of 1,000–1,400 time steps per second.
  • The most complex case (3-soliton interaction, $N=1024$ grid points, 80s simulation) completed in ~9 minutes (534 seconds).
  • Numba JIT compilation and parallelization proved essential for achieving research-grade speeds on commodity hardware.

• Conservation Accuracy:

  • Mass, Momentum, and Energy were conserved with relative errors generally below $O(10^{-4})$.
  • The most complex case (3-soliton) showed maximum relative errors of $2.56 \times 10^{-4}$ (Mass), $8.86 \times 10^{-6}$ (Momentum), and $6.20 \times 10^{-6}$ (Energy).
  • Errors were primarily oscillatory rather than secular (drifting), indicating the absence of systematic bias, though the non-symplectic DOP853 integrator introduces small oscillations.

• Physical Fidelity:

  • Velocity-Amplitude Relation: Measured soliton velocities aligned with the theoretical prediction $v = \epsilon A / 3$ within 5%.
  • Elastic Scattering: In collision scenarios, solitons emerged with their original amplitudes and velocities intact, differing only by phase shifts, confirming the capture of the integrable nature of the KdV equation.
  • Trajectory Linearity: Soliton paths exhibited $R^2 > 0.99$, confirming constant-velocity propagation.

• Integrability Diagnostics:

  • Recurrence Quantification Analysis (RQA) yielded high determinism values (DET > 0.99), confirming that the numerical solutions preserve the regular, non-chaotic phase-space structure of the integrable Hamiltonian system.
  • Spectral entropy and Fisher information showed bounded variations with transient spikes only during collision events, returning to baseline states post-collision.

4. Key Contributions

1. Open-Source Tool (sangkuriang): A freely available, MIT-licensed Python library that democratizes access to high-fidelity KdV simulations, removing the barrier of needing HPC clusters for idealized studies.
2. Hybrid Numerical Architecture: Demonstrates that combining pseudo-spectral spatial discretization with Numba-accelerated JIT compilation and adaptive time-stepping yields both high accuracy and high performance on standard hardware.
3. Advanced Diagnostic Framework: Introduces a comprehensive suite of diagnostics (RQA, spectral entropy, Fisher information) to verify the preservation of integrability in numerical solutions, moving beyond simple visual or error-norm checks.
4. Benchmarking Suite: Provides standardized, reproducible test cases (single, symmetric, overtaking, and multi-soliton) that serve as benchmarks for future solvers in geophysical fluid dynamics.

5. Significance

• For Oceanography & GFD: The solver provides a robust platform for studying the fundamental balance between nonlinearity and dispersion in internal solitary waves (ISWs), which are critical for understanding energy transport, mixing, and structural loads in coastal and deep oceans.
• Methodological Impact: The use of information-theoretic measures (like RQA and Fisher information) offers a model-independent way to detect numerical breakdown or genuine non-integrability in perturbed systems (e.g., variable bathymetry or stratification).
• Accessibility: By running complex multi-soliton simulations in minutes on a laptop, the tool enables rapid prototyping and educational exploration of nonlinear wave dynamics for researchers and students without institutional HPC allocations.
• Future Extensions: The modular design of sangkuriang lays the groundwork for extending the framework to variable-coefficient KdV equations, higher-order dispersive models (Kawahara), rotational effects (Ostrovsky), and 2D generalizations (Kadomtsev–Petviashvili), bridging the gap between idealized theory and realistic ocean modeling.