engine refactor

internal/engine/models.go

@@ -3,14 +3,13 @@ package engine
 import (
 	"math"
 	"sort"
-	"sync/atomic"
 
 	"predictor-refactored/internal/weather"
 )
 
 // Sum composes models by summing their derivatives at each evaluation point.
 //
-// Useful for combining e.g. a vertical-rate model with a horizontal wind model
+// Useful for combining a vertical-rate model with a horizontal wind model
 // into a single propagator. Equivalent to Tawhiri's LinearModel.
 func Sum(models ...Model) Model {
 	if len(models) == 1 {
@@ -29,18 +28,16 @@ func Sum(models ...Model) Model {
 }
 
 // ConstantRate returns a model with a constant vertical velocity (m/s).
-// A positive rate is upward (ascent); a negative rate is downward.
+// Positive rates are upward.
 func ConstantRate(rate float64) Model {
-	return func(_ float64, _ State) State {
-		return State{Altitude: rate}
-	}
+	return func(_ float64, _ State) State { return State{Altitude: rate} }
 }
 
-// ParachuteDescent returns a model where vertical velocity grows with altitude
-// because thinner air provides less drag.
+// ParachuteDescent returns a model where vertical velocity grows with
+// altitude because thinner air provides less drag. seaLevelRate is the
+// descent speed at sea level (m/s, positive).
 //
-// seaLevelRate is the descent speed at sea level (m/s, positive number).
-// The terminal velocity at altitude is computed as
+// Terminal velocity at altitude is computed as
 //
 //	v = -k / sqrt(rho(alt)),  k = seaLevelRate * 1.1045,
 //
@@ -52,9 +49,9 @@ func ParachuteDescent(seaLevelRate float64) Model {
 	}
 }
 
-// nasaDensity returns air density (kg/m^3) for the given altitude in metres,
-// using the NASA simple atmosphere model. See
-// https://www.grc.nasa.gov/WWW/K-12/airplane/atmosmet.html.
+// nasaDensity returns air density (kg/m^3) for an altitude in metres,
+// using the NASA simple atmosphere model.
+// See https://www.grc.nasa.gov/WWW/K-12/airplane/atmosmet.html.
 func nasaDensity(alt float64) float64 {
 	var temp, pressure float64
 	switch {
@@ -71,22 +68,17 @@ func nasaDensity(alt float64) float64 {
 	return pressure / (0.2869 * (temp + 273.1))
 }
 
-// RateSegment is one entry in a Piecewise rate schedule.
+// RateSegment is one entry in a Piecewise rate schedule. Until is the UNIX
+// timestamp at which this segment ends — the model emits the segment's
+// Rate for all t < Until. The final segment's Rate is held indefinitely.
 type RateSegment struct {
-	// Until is the UNIX timestamp at which this segment ends.
-	// The model applies the segment's Rate for all t < Until.
 	Until float64
-	// Rate is the vertical velocity (m/s) during the segment. Positive is up.
-	Rate float64
+	Rate  float64
 }
 
-// Piecewise returns a model that produces a piecewise-constant vertical rate
-// over a sequence of time intervals.
-//
-// Segments are searched by their Until field; the first segment whose Until
-// exceeds t supplies the active rate. For t at or after the last Until, the
-// final segment's Rate is held indefinitely. Input is sorted ascending by
-// Until on construction.
+// Piecewise returns a model that produces a piecewise-constant vertical
+// rate over a sequence of intervals. The input is sorted ascending by
+// Until on construction; later segments shadow earlier ones.
 func Piecewise(segments []RateSegment) Model {
 	if len(segments) == 0 {
 		return ConstantRate(0)
@@ -104,33 +96,13 @@ func Piecewise(segments []RateSegment) Model {
 	}
 }
 
-// Warnings aggregates non-fatal conditions encountered during integration.
-type Warnings struct {
-	// AltitudeTooHigh counts evaluations where the wind sampler reported
-	// that altitude was above the highest pressure level of the dataset.
-	AltitudeTooHigh atomic.Int64
-}
-
-// ToMap returns warnings as a map suitable for JSON output. Only counters
-// that have fired are included.
-func (w *Warnings) ToMap() map[string]any {
-	out := make(map[string]any)
-	if n := w.AltitudeTooHigh.Load(); n > 0 {
-		out["altitude_too_high"] = map[string]any{
-			"count":       n,
-			"description": "altitude exceeded the highest pressure level of the wind dataset; samples were extrapolated",
-		}
-	}
-	return out
-}
-
 // WindTransport returns a model that moves laterally at the wind velocity
-// sampled from field. The vertical component of the returned derivative is
-// zero. Wind units are converted from m/s to deg/s on Earth's surface.
+// sampled from field. Vertical component is zero. Wind components in m/s
+// are converted to deg/s on Earth's surface using R = 6371009 m.
 //
-// If warnings is non-nil, the AltitudeTooHigh counter is incremented for any
-// sample where the wind field reported altitude above the model top.
-func WindTransport(field weather.WindField, warnings *Warnings) Model {
+// If events is non-nil, an "above_model" event is emitted whenever the
+// wind field reports altitude above the highest pressure level.
+func WindTransport(field weather.WindField, events *EventSink) Model {
 	const earthR = 6371009.0
 	const piOver180 = math.Pi / 180.0
 	const degPerRad = 180.0 / math.Pi
@@ -139,8 +111,9 @@ func WindTransport(field weather.WindField, warnings *Warnings) Model {
 		if err != nil {
 			return State{}
 		}
-		if sample.AboveModel && warnings != nil {
-			warnings.AltitudeTooHigh.Add(1)
+		if sample.AboveModel && events != nil {
+			events.Emit("above_model", t, s,
+				"altitude exceeded the highest pressure level of the wind dataset; samples extrapolated")
 		}
 		r := earthR + s.Altitude
 		return State{