Wave Hydrodynamics Simulator v1.0.0

Wave Hydrodynamics Simulator v1.0.0

The first public release of Wave Hydrodynamics Simulator — an interactive
Python engineering application for calculating, visualizing, and exploring
finite-depth regular waves using first-order Airy / linear wave theory.

This project is a modernized, scientifically audited, and substantially
refactored evolution of an earlier MATLAB wave-parameter calculator and
particle-motion simulator that I originally developed during my postgraduate
studies in Ocean Engineering at IIT Madras.

Try it online

Live browser dashboard (lite version):
https://samtherocket.github.io/wave-hydrodynamics-simulator/

Highlights

Interactive desktop application

• User-defined water depth, wave height, wave period, gravity, and fluid density.
• Integrated calculation and wave-particle animation.
• Animation starts only after the user requests calculation.
• Pause, resume, and reset controls.
• Expandable engineering results and diagnostics.
• Text-report export.
• Shallow-, intermediate-, and deep-water regime classification.

Browser-based live dashboard

A static browser implementation is included under docs/ and is designed for
deployment through GitHub Pages.

It allows users to explore the V1.0 wave calculations and visualization directly
in a web browser without installing Python.

Airy / linear wave-theory solver

The V1.0 numerical model includes:

• finite-depth dispersion-relation solution;
• wavelength and deep-water wavelength;
• angular frequency and wave number;
• phase and group celerity;
• group-velocity factor;
• kinetic, potential, and total mean wave energy;
• wave-energy flux;
• shoaling transformation;
• equivalent deep-water wave properties;
• particle orbital geometry;
• horizontal and vertical particle velocities;
• horizontal and vertical particle accelerations;
• first-order dynamic-pressure fluctuations;
• second-order Stokes-drift diagnostic.

Corrected particle kinematics

The particle-motion implementation was reconstructed from the original MATLAB
prototype to use the local wave phase directly.

This corrects several limitations of the earlier implementation, including:

• spatial phase differences between particles at different longitudinal
  locations;
• physically uniform phase evolution;
• consistent material free-surface and upper-particle motion;
• conventional mean-sea-level coordinates with z = 0;
• seabed location at z = -d;
• use of the actual finite-depth wavelength in the simulation domain.

Deep-water wave-base visualization

For deep-water visualization, the application indicates the conventional wave
base at approximately:

L / 2

below the mean water level.

The exact Airy-wave solution is not artificially truncated at this depth:
particle-motion amplitudes decay continuously and remain mathematically
non-zero. The L / 2 limit is used only as a conventional engineering
visualization threshold for negligible orbital motion.

Wave-theory applicability map

V1.0 includes an original vector reconstruction of a wave-theory applicability
map informed by the wave-theory validity framework attributed to Le Méhauté
(1976) and reproduced in later wave-mechanics literature.

The implementation combines:

• analytically reconstructed physical boundaries;
• explicitly documented independently digitized reference boundaries;
• logarithmic dimensionless coordinates;
• a dynamically plotted current-case marker;
• distinction between the wave theory suggested by the map and the solver
  actually used.

The original textbook raster figure is not embedded in the application.

Important: All numerical wave-field calculations in V1.0 still use
first-order Airy / linear wave theory. The applicability map is advisory and
does not yet automatically switch the numerical solver to a higher-order wave
theory.

Engineering diagnostics

The application evaluates quantities including:

• relative water depth;
• wave steepness;
• relative wave height;
• Ursell number;
• approximate breaking-screening criteria;
• wave-theory applicability information.

These diagnostics are intended to help the user understand whether the
first-order Airy solution should be treated as an appropriate engineering model,
an approximation, or a baseline for comparison.

Validation

The V1.0 solver has been checked using multiple complementary validation
approaches, including:

• shallow-water analytical limiting behaviour;
• deep-water analytical limiting behaviour;
• intermediate-water reference cases;
• dispersion-relation consistency;
• local and deep-water energy-flux consistency;
• particle/free-surface kinematic consistency;
• deep-water numerical-stability checks;
• conventional wave-base behaviour;
• Python and browser-solver parity checks;
• regression testing of the historical MATLAB example.

Additional published and textbook worked examples are planned to continue
strengthening the validation suite in future releases.

Academic origin and acknowledgements

The foundation of this project grew from my postgraduate learning and work in
Ocean Engineering at the Indian Institute of Technology Madras (IIT Madras).

I gratefully acknowledge:

• Prof. S. Nallayarasu, whose guidance and teaching contributed to my
  development in ocean and offshore engineering.
• Prof. V. Sundar, whose coursework and teaching in wave hydrodynamics and
  ocean-wave mechanics provided important theoretical foundations that inspired
  the original MATLAB implementation.

The original MATLAB program was independently developed by
Sambit Supriya Dash as an academic software demonstration based on concepts
learned through coursework, lectures, and engineering study.

This repository is an independent personal engineering project and is not an
official IIT Madras, faculty, laboratory, course, publisher, or institutional
software product.

V1.0 scope

This release intentionally establishes a focused and testable foundation.

It currently supports:

• regular progressive waves;
• first-order Airy / linear wave theory;
• finite and constant water depth;
• two-dimensional wave propagation;
• interactive desktop visualization;
• browser-based demonstration;
• engineering diagnostics;
• numerical and visual outputs.

It is not intended to be a CFD solver, a complete offshore-structure analysis
package, or a universal multi-theory wave solver.

Future direction

Future development is planned in independent, validated layers, including:

• automatic wave-theory selection;
• Stokes second-, third-, and fifth-order theories;
• stream-function theory;
• cnoidal-wave theory;
• solitary-wave theory;
• irregular wave spectra;
• Pierson–Moskowitz and JONSWAP spectra;
• directional seas;
• wave superposition and wave groups;
• wave-current interaction;
• pressure-field contour animation;
• velocity-vector and acceleration fields;
• advanced Lagrangian particle tracking;
• Morison-equation and force-ready hydrodynamic quantities;
• wave-load quantities that do not require a complete structural model;
• radiation stress;
• mass, momentum, and energy transport;
• breaking evolution;
• varying bathymetry and shoaling;
• refraction;
• diffraction;
• reflection;
• standing waves;
• interactive probe placement;
• expanded data export;
• continued GUI development.

These capabilities are intentionally reserved for later releases so that
v1.0.0 remains a stable milestone representing the corrected and modernized
Airy-wave foundation.

Thank you

This release marks the first public version of a project whose earliest form
began as a MATLAB-based wave-parameter and particle-motion simulator during my
postgraduate studies.

The objective is to continue developing it, layer by layer, into a transparent,
well-tested, educational, and increasingly capable wave-hydrodynamics
engineering platform.