Ocean Wave Group Velocity Calculator
This ocean wave group velocity calculator finds the speed at which wave energy and a narrow wave packet travel through water of finite depth.
Run — free
Enter the wavelength and water depth in meters, and the calculator solves the linear dispersion relation before applying the finite-depth group factor. The result includes group velocity, phase velocity, angular frequency, wave number, and relative depth. It is useful for coastal engineering, oceanography, marine operations, and classroom checks where shallow-water and deep-water shortcuts may not be accurate enough.
What group velocity describes
Individual wave crests move at the phase velocity, but a recognizable group of nearby wave components usually moves at another speed. The group velocity describes the propagation of the envelope and, within linear wave theory, the rate at which wave energy travels. That distinction matters when estimating when swell energy will reach a coastline, comparing a measured wave train with a forecast, or following the transformation of waves across changing bathymetry. This calculator starts with wavelength rather than period, so it is particularly convenient when wavelength is measured from imagery, a spatial model, a laboratory basin, or a known wave-number spectrum. The returned phase velocity gives a useful comparison with the group velocity. In very deep water the group velocity approaches one half of the phase velocity. In shallow water the two speeds approach one another because long waves become nearly nondispersive. Finite depth lies between those limits, and the full relation avoids choosing a shortcut too early.
How the finite-depth calculation works
The calculation assumes a small-amplitude, progressive surface gravity wave in water of uniform depth. It first converts wavelength L to wave number k using k = 2π/L. It then solves the linear dispersion relation ω² = gk tanh(kh), where ω is angular frequency, g is gravitational acceleration, and h is water depth. Phase velocity is ω/k. Group velocity is obtained by multiplying phase velocity by one half of the quantity 1 + 2kh/sinh(2kh). The dimensionless product kh, returned as relative depth, shows how strongly the seabed influences propagation. A small kh indicates shallow-water behavior, while a large kh indicates deep-water behavior. Standard gravity is used unless a different positive gravitational acceleration is supplied. Values are calculated directly, without iterative approximations, because wavelength and depth already determine wave number. The implementation also evaluates the large-depth limit safely, preventing an overflowing hyperbolic sine from corrupting an otherwise finite deep-water result.
Choosing inputs and interpreting results
Use wavelength and depth in meters and keep both quantities on the same physical scale. Depth means the still-water depth from the undisturbed surface to the bed, not wave height, draft, or elevation relative to an arbitrary datum. Wavelength is the horizontal distance between corresponding phases, commonly crest to crest. The calculator rejects zero or negative depth because the finite-depth dispersion relation does not define an ocean-wave solution there; it likewise rejects nonpositive wavelength or gravity and any nonfinite numeric value. Treat the output as a linear-theory estimate. Strong currents, large wave steepness, breaking, rapidly varying bathymetry, viscosity, surface tension at very short wavelengths, and directional spreading can require a more detailed model. For a quick reasonableness check, compare the group factor with its theoretical range: it tends toward one in shallow water and one half in deep water. A result between those limits is expected for ordinary finite-depth surface gravity waves and helps reveal unit mistakes before the value enters a larger analysis.
What you can do with it
Estimate swell energy arrival
Convert an observed or modeled wavelength and offshore depth into the propagation speed of a wave packet toward a monitoring location.
Check coastal engineering calculations
Compare group and phase velocities before computing energy flux, shoaling behavior, or travel time across a constant-depth segment.
Teach finite-depth dispersion
Explore how the dimensionless relative depth kh moves a wave between shallow-water and deep-water limits.
FAQ
What does the calculation cost?
Each API request costs $0.002. The calculation is also suitable for execution in the browser because it uses deterministic arithmetic and no network services.
Why is group velocity different from phase velocity?
Phase velocity follows individual crests, while group velocity follows the wave envelope and energy propagation. Dispersion makes those speeds differ.
What happens if water depth is zero or negative?
The request returns an invalid-input error because the finite-depth ocean-wave relation requires a water depth greater than zero.
Which gravity value is used by default?
The default is standard gravitational acceleration. You may provide another positive value when modeling a different convention or environment.
Does this calculator include currents or wave breaking?
No. It applies linear surface-gravity-wave theory for uniform depth and does not model currents, breaking, strong nonlinearity, or rapidly changing bathymetry.
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/earth/wave-group-velocity \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"wavelength_m":100,"depth_m":20}'const res = await fetch("https://api.kit.forhosting.com/earth/wave-group-velocity", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"wavelength_m": 100,
"depth_m": 20
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/earth/wave-group-velocity",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"wavelength_m": 100,
"depth_m": 20
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/earth/wave-group-velocity", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"wavelength_m":100,"depth_m":20}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"wavelength_m":100,"depth_m":20}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/earth/wave-group-velocity", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"wavelength_m": 100,
"depth_m": 20
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "earth.wave_group_velocity",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |