Hydraulic gradient calculator

A zero or negative distance is rejected with invalid_input instead of a divide-by-zero.

What i = (h1 − h2) / L means and which quantities you need to send

Delivering head_1, head_2, distance, head_difference, hydraulic_gradient, the short alias i, gradient_magnitude, formula, method, and a small flow_from hint as JSON makes the result easy to paste into notes, diff in automated tests, or reuse across languages without reimplementing the subtraction and division. Keep the length basis honest: mixing a head in metres with a well spacing in kilometres without converting first will silently scale i by a thousand and is not a unit-conversion service this endpoint provides.

How this calculator validates input and applies i = (h1 − h2) / L

Numeric strings that parse to finite numbers are accepted so forms and CSV-style pipelines can pass values without an extra cast. Distance must be strictly positive. A negative distance is rejected for the same reason: L is a geometric path length, not a signed coordinate jump. Hydraulic heads may be any finite value, including readings below a chosen datum; a negative head is physically common in confined aquifers referenced to ground surface and is not treated as an error. There is no unit-conversion table, no hydraulic-conductivity lookup, and no finite-difference groundwater solver; this is ideal one-dimensional i from three known quantities. Send a JSON body with three required fields: head_1, head_2, and distance. Every field must be finite: missing fields, empty strings, non-numeric text, NaN, and Infinity all fail immediately with invalid_input before any result is returned, and failed validation is not charged. Aliases are supported: h1, head1, hydraulic_head_1 for head_1; h2, head2, hydraulic_head_2 for head_2; L, length, dl for distance. A zero distance is always rejected as invalid_input because dividing a head difference by a vanishing path length is undefined, and that failure is the product contract named in the capability brief. After validation the engine subtracts head_2 from head_1, divides by distance, takes the absolute value for gradient_magnitude, and rounds to a stable decimal precision so the same input always yields the same JSON across JavaScript engines. A soft flow_from label records the implied isotropic direction—1_to_2 when i is positive, 2_to_1 when i is negative, and none when the heads are equal—purely as an educational convenience; it is not a three-dimensional flow-net, a particle-track, or a heterogeneous-aquifer classifier. The same pure function powers the free in-browser tool and the API path.

Practical use, limits, pricing, and delivery channels

Use the browser tool when you want an immediate i equals (h1 minus h2) over L check while grading a hydrogeology homework set, reducing a pair of site piezometers, sketching whether seepage under a sheet pile is steep enough to worry about piping, or sanity-checking the driving term you are about to multiply by hydraulic conductivity in Darcy's law. Choose units consistently—if both heads and the distance are in metres, i is dimensionless and ready for textbook comparison; the same is true for feet with feet. There is no language model, no external well-log service, and no randomness, so the capacity is safe to pin in continuous-integration checks and reproducible lesson materials. Each successful request is one billable item at $0.002; failed validation does not consume balance. Results are fully deterministic: the same three inputs always yield the same hydraulic_gradient, the same i alias, the same gradient_magnitude, and the same formula and method labels. Wire the endpoint into Darcy drills, contest answer checkers, seepage sketch tools, or preprocessing steps where you already prefer explicit domain errors—such as rejecting a zero distance—over opaque black-box widgets that cannot explain why a bad input was refused.