# Scientific methods and validity boundaries

`hrwqe/cf_ocean` provides small, dependency-free oceanographic calculations for
portable MoonBit data-processing workloads. The routines in `src/analytics`
are deliberately bounded engineering approximations. They are not a complete
implementation of TEOS-10 or the Gibbs SeaWater (GSW) toolbox, and the package
does not claim thermodynamic conformance or the accuracy of a dedicated
hydrographic library.

## Supported approximation contract

`validate_ocean_physics_inputs` reports values outside the shared screening
envelope. Boundary values are accepted:

| Quantity | Unit | Screening envelope |
| --- | --- | --- |
| Temperature | °C | -2 to 40 |
| Practical salinity | PSU | 0 to 42 |
| Pressure | dbar | 0 to 1,200 |
| Depth | m | 0 to 12,000 |
| Latitude | degrees | -90 to 90 |

The validator is a safety guard, not a full physical-quality or CF-compliance
validator. Domain experts should apply observation-specific QC and use a
validated TEOS-10/GSW implementation when publication-grade thermodynamic
accuracy is required.

The available methods have these explicit scopes:

- `seawater_density_surface` uses an EOS-80/UNESCO-style surface polynomial;
  pressure is fixed at 0 dbar.
- `speed_of_sound` uses a compact UNESCO/Chen-Millero-style engineering form.
- `practical_to_absolute_salinity` uses a fixed reference-salinity ratio; it
  does not model the TEOS-10 Absolute Salinity Anomaly Ratio.
- `potential_temperature` and `potential_to_conservative_temperature` are
  simple portable approximations and do not perform the full GSW integration.
- `estimate_mixed_layer_depth` is a density-threshold screening estimate from
  approximately 10 m and is not a complete mixed-layer detection protocol.
- `scan_ocean_profile_default` is a deterministic profile-screening pass. It
  preserves input order and reports finite-value, range, ordering, gradient,
  and increasing-depth density-inversion flags; it does not sort, repair, or
  certify a profile. Descending pairs are reported as ordering issues without
  being treated as density inversions.
  Its default depth envelope is 0 to 12,000 m and its gradient/inversion limits
  are conservative engineering thresholds exposed through `ProfileQcConfig`.
- `ProfileQcConfig::is_valid` rejects non-finite, reversed, or negative
  thresholds; scanning an invalid configuration returns an explicit
  `InvalidConfiguration` diagnostic. `ProfileQcSample::surface_density` and
  the density helper arrays return safe `None`/`0.0` fallbacks for values
  outside the shared temperature/salinity envelope.
- `profile_depth_intervals` returns absolute intervals for both ascending and
  descending input. `profile_density_inversions` only evaluates increasing-
  depth pairs with finite depths, so input direction or a NaN/Inf depth cannot
  create a false stability warning.

## Deterministic regression anchors

The analytics tests lock the following implementation anchors so changes are
reviewable and reproducible:

- `seawater_density_surface(20, 35)` is approximately `1024.763 kg/m³`.
- `speed_of_sound(15, 35, 100)` is `1508.40375 m/s` for the implemented
  polynomial.
- `depth_to_pressure(100, 45)` is approximately `100.512882 dbar` for the
  implemented hydrostatic approximation.
- Validator boundaries, invalid inputs, equatorial Coriolis handling, and
  short/constant MLD profiles are covered by deterministic tests.
- Profile screening covers empty and single-sample inputs, depth endpoints,
  non-finite values, duplicate and descending depths, gradient thresholds, and
  density inversions.

These anchors test the implementation contract; they are not a certification
that the approximation replaces TEOS-10/GSW.

## References

- [Unidata NetCDF User Guide](https://docs.unidata.ucar.edu/netcdf/NUG/netcdf_introduction.html)
  describes the CDF-1 and CDF-2 formats implemented by the binary package.
- [CF Conventions](https://cfconventions.org/conventions.html) is the source
  for the metadata vocabulary and version history used by the project.
- [TEOS-10 official site](https://www.teos-10.org/index.htm) and the
  [GSW documentation](https://teos-10.org/pubs/gsw/html/gsw_contents.html)
  define the full thermodynamic reference that this package intentionally does
  not reimplement.
- Fofonoff and Millard, *Algorithms for the computation of fundamental
  properties of seawater* (UNESCO Technical Papers in Marine Science 44,
  1983), [public bibliographic record and document link](https://legacy.repository.oceanbestpractices.org/handle/11329/109).