navcore_math/

sailing.rs

//! Velocity made good and laylines.

use crate::{Position, angle, rhumb};

/// Speed made good directly towards a waypoint, knots.
///
/// Negative when the vessel is opening the range rather than closing it,
/// which is the normal state on the wrong tack and must not be clamped
/// away -- a beat is a sequence of legs that individually look bad.
#[must_use]
pub fn vmg_to_waypoint_kn(sog_kn: f64, cog_deg: f64, bearing_to_waypoint_deg: f64) -> f64 {
    sog_kn * angle::diff(bearing_to_waypoint_deg, cog_deg).to_radians().cos()
}

/// Speed made good directly to windward, knots.
///
/// Positive is progress towards the wind, so a boat on a run returns a
/// negative value; its downwind VMG is that number negated. One function
/// rather than two, because upwind and downwind VMG are the same
/// projection and splitting them invites disagreeing sign conventions.
#[must_use]
pub fn vmg_to_wind_kn(boat_speed_kn: f64, true_wind_angle_deg: f64) -> f64 {
    boat_speed_kn * true_wind_angle_deg.to_radians().cos()
}

/// The two close-hauled headings for a given wind, degrees true.
///
/// Returned as `(starboard_tack, port_tack)`. On starboard tack the wind
/// comes over the starboard side, which puts the heading to the left of the
/// wind's own direction.
#[must_use]
pub fn close_hauled_headings_deg(
    true_wind_direction_deg: f64,
    beat_angle_deg: f64,
) -> (f64, f64) {
    (
        angle::norm_360(true_wind_direction_deg - beat_angle_deg),
        angle::norm_360(true_wind_direction_deg + beat_angle_deg),
    )
}

/// How far to sail on each tack to fetch a mark dead to windward.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct TackLegs {
    /// Distance to sail on starboard tack, nautical miles.
    pub starboard_nm: f64,
    /// Distance to sail on port tack, nautical miles.
    pub port_nm: f64,
    /// Heading on starboard tack, degrees true.
    pub starboard_heading_deg: f64,
    /// Heading on port tack, degrees true.
    pub port_heading_deg: f64,
}

impl TackLegs {
    /// Total distance sailed, which is what the beat actually costs.
    #[must_use]
    pub fn total_nm(&self) -> f64 {
        self.starboard_nm + self.port_nm
    }
}

/// Splits the distance to an upwind mark into one leg on each tack.
///
/// `beat_angle_deg` is the angle the boat sails off the true wind when
/// close hauled -- a polar property of the boat, typically 35-50 degrees,
/// which is why it is a parameter and not a constant.
///
/// Returns `None` when the mark does not need two tacks: it is already
/// fetchable on one, or it is not upwind at all. That is the signal to stop
/// drawing laylines, not an error.
///
/// # Model
///
/// Plane trigonometry on the triangle formed by the two headings and the
/// bearing to the mark, deliberately: laylines are a tactical picture over
/// a few miles, where the difference against a spherical solution is far
/// below the accuracy of the beat angle it is built on. Do not reach for
/// this over ocean distances.
#[must_use]
pub fn tack_legs(
    bearing_to_mark_deg: f64,
    distance_to_mark_nm: f64,
    true_wind_direction_deg: f64,
    beat_angle_deg: f64,
) -> Option<TackLegs> {
    if !(0.0..90.0).contains(&beat_angle_deg) || beat_angle_deg <= 0.0 {
        return None;
    }
    if !distance_to_mark_nm.is_finite() || distance_to_mark_nm <= 0.0 {
        return None;
    }

    let (stb_hdg, prt_hdg) = close_hauled_headings_deg(true_wind_direction_deg, beat_angle_deg);

    // Solving d_stb * u(stb) + d_prt * u(prt) = d * u(bearing) for the two
    // leg lengths. The determinant of that 2x2 system is sin(2*beat), which
    // is why a beat angle of 0 or 90 has to be rejected above.
    let denom = (2.0 * beat_angle_deg).to_radians().sin();
    let stb =
        distance_to_mark_nm * angle::diff(prt_hdg, bearing_to_mark_deg).to_radians().sin() / denom;
    let prt =
        distance_to_mark_nm * angle::diff(bearing_to_mark_deg, stb_hdg).to_radians().sin() / denom;

    if stb < 0.0 || prt < 0.0 {
        return None;
    }

    Some(TackLegs {
        starboard_nm: stb,
        port_nm: prt,
        starboard_heading_deg: stb_hdg,
        port_heading_deg: prt_hdg,
    })
}

/// How far past the mark a layline ray reaches from [`layline_rays`], as a
/// multiple of the vessel's own current distance to the mark -- long
/// enough that the ray always extends past wherever the vessel actually
/// is on the chart, short enough that it does not dominate a zoomed-in
/// view. A fixed on-screen length cannot do this: it would either vanish
/// at ocean scale or blot out a marina at pier scale. `pub` so every
/// client draws the same length rather than picking its own.
pub const LAYLINE_LENGTH_FACTOR: f64 = 1.3;

/// How far a tack ray reaches from the vessel in [`tack_rays`].
///
/// Unlike a layline, a tack ray has no mark to scale itself against --
/// there is no "distance to" anything -- so this is a plain figure
/// instead: long enough to read clearly at typical coastal and harbour
/// display scales, short enough not to run off a zoomed-in view. `pub`
/// for the same reason as [`LAYLINE_LENGTH_FACTOR`].
pub const TACK_RAY_LENGTH_NM: f64 = 1.0;

/// The two laylines through `mark`, as ray endpoints from `mark` itself --
/// `(mark, starboard_end, port_end)` -- or `None` when `mark` does not
/// need a beat at all.
///
/// # Layline definition
///
/// A layline is a line through a mark, marking the boundary where
/// tacking fetches the mark on a single close-hauled board. It requires
/// a mark to exist, and returns `None` when the mark is already
/// fetchable on one tack or lies dead downwind -- the same wind-triangle
/// judgement [`tack_legs`] already makes. Each layline is the reciprocal
/// of its own close-hauled heading, extended out from the mark: crossing
/// it means the mark is fetchable on that tack.
#[must_use]
pub fn layline_rays(
    vessel: Position,
    mark: Position,
    true_wind_direction_deg: f64,
    beat_angle_deg: f64,
) -> Option<(Position, Position, Position)> {
    let bearing_to_mark_deg = rhumb::bearing_deg(vessel, mark);
    let distance_to_mark_nm = rhumb::distance_nm(vessel, mark);

    let legs = tack_legs(bearing_to_mark_deg, distance_to_mark_nm, true_wind_direction_deg, beat_angle_deg)?;

    let length_nm = distance_to_mark_nm * LAYLINE_LENGTH_FACTOR;
    let starboard_end =
        rhumb::destination(mark, angle::norm_360(legs.starboard_heading_deg + 180.0), length_nm);
    let port_end = rhumb::destination(mark, angle::norm_360(legs.port_heading_deg + 180.0), length_nm);

    Some((mark, starboard_end, port_end))
}

/// The vessel's own two close-hauled headings right now, as ray endpoints
/// from `vessel` itself -- `(starboard_end, port_end)`.
///
/// Unlike [`layline_rays`], there is no mark to test fetchability against
/// and so nothing to judge: a tack always has two possible headings,
/// whatever they are actually good for. This is simply
/// [`close_hauled_headings_deg`], projected out to a chart-drawable
/// length.
#[must_use]
pub fn tack_rays(vessel: Position, true_wind_direction_deg: f64, beat_angle_deg: f64) -> (Position, Position) {
    let (starboard_heading_deg, port_heading_deg) =
        close_hauled_headings_deg(true_wind_direction_deg, beat_angle_deg);
    let starboard_end = rhumb::destination(vessel, starboard_heading_deg, TACK_RAY_LENGTH_NM);
    let port_end = rhumb::destination(vessel, port_heading_deg, TACK_RAY_LENGTH_NM);
    (starboard_end, port_end)
}

#[cfg(test)]
mod tests {
    use super::*;

    fn close(a: f64, b: f64, tol: f64) -> bool {
        (a - b).abs() < tol
    }

    #[test]
    fn vmg_is_full_speed_straight_at_the_mark() {
        assert!(close(vmg_to_waypoint_kn(6.0, 90.0, 90.0), 6.0, 1e-9));
    }

    #[test]
    fn vmg_goes_negative_sailing_away() {
        assert!(close(vmg_to_waypoint_kn(6.0, 270.0, 90.0), -6.0, 1e-9));
    }

    #[test]
    fn vmg_across_the_bearing_is_zero() {
        assert!(close(vmg_to_waypoint_kn(6.0, 0.0, 90.0), 0.0, 1e-9));
    }

    #[test]
    fn pinching_beats_footing_only_up_to_a_point() {
        // The classic trade-off, and a check that the projection has the
        // right shape: 30 deg at 4 kn makes less to windward than 45 deg at
        // 6 kn, even though it points higher.
        let pinched = vmg_to_wind_kn(4.0, 30.0);
        let footed = vmg_to_wind_kn(6.0, 45.0);
        assert!(footed > pinched, "{footed} vs {pinched}");
    }

    #[test]
    fn running_gives_negative_vmg_to_windward() {
        assert!(vmg_to_wind_kn(7.0, 170.0) < 0.0);
    }

    #[test]
    fn close_hauled_headings_straddle_the_wind() {
        let (stb, prt) = close_hauled_headings_deg(0.0, 45.0);
        assert!(close(stb, 315.0, 1e-9));
        assert!(close(prt, 45.0, 1e-9));
    }

    #[test]
    fn a_mark_dead_upwind_splits_evenly() {
        let legs = tack_legs(0.0, 10.0, 0.0, 45.0).unwrap();
        assert!(close(legs.starboard_nm, legs.port_nm, 1e-9), "{legs:?}");
        assert!(close(legs.starboard_nm, 7.0710678, 1e-6), "{legs:?}");
        // Beating 45 degrees costs sqrt(2) times the straight-line distance.
        assert!(close(legs.total_nm(), 10.0 * 2f64.sqrt(), 1e-6), "{legs:?}");
    }

    #[test]
    fn a_mark_off_the_wind_axis_favours_one_tack() {
        // Wind from north, mark 30 degrees east of dead upwind: mostly port
        // tack (heading 045), with a short starboard hitch to finish.
        let legs = tack_legs(30.0, 10.0, 0.0, 45.0).unwrap();
        assert!(close(legs.starboard_nm, 2.5882, 1e-3), "{legs:?}");
        assert!(close(legs.port_nm, 9.6593, 1e-3), "{legs:?}");
        assert!(legs.port_nm > legs.starboard_nm, "{legs:?}");
    }

    #[test]
    fn a_fetchable_mark_needs_no_laylines() {
        // On the beam: laying it needs no tack at all.
        assert!(tack_legs(90.0, 10.0, 0.0, 45.0).is_none());
        // And dead downwind is not a beat either.
        assert!(tack_legs(180.0, 10.0, 0.0, 45.0).is_none());
    }

    #[test]
    fn exactly_on_the_layline_puts_everything_on_one_tack() {
        // Mark bearing 315 with wind from north is the starboard layline.
        let legs = tack_legs(315.0, 10.0, 0.0, 45.0).unwrap();
        assert!(close(legs.starboard_nm, 10.0, 1e-6), "{legs:?}");
        assert!(close(legs.port_nm, 0.0, 1e-6), "{legs:?}");
    }

    #[test]
    fn a_narrower_beat_angle_costs_less_distance() {
        let tight = tack_legs(0.0, 10.0, 0.0, 35.0).unwrap();
        let wide = tack_legs(0.0, 10.0, 0.0, 50.0).unwrap();
        assert!(tight.total_nm() < wide.total_nm());
    }

    #[test]
    fn nonsense_beat_angles_are_rejected() {
        assert!(tack_legs(0.0, 10.0, 0.0, 0.0).is_none());
        assert!(tack_legs(0.0, 10.0, 0.0, 90.0).is_none());
        assert!(tack_legs(0.0, 10.0, 0.0, -10.0).is_none());
        assert!(tack_legs(0.0, 0.0, 0.0, 45.0).is_none());
    }

    #[test]
    fn the_solution_actually_reaches_the_mark() {
        // Sail both legs as vectors and check we land on the mark -- the
        // property the linear solve is supposed to have.
        for bearing in [350.0, 0.0, 15.0, 340.0] {
            let legs = tack_legs(bearing, 8.0, 0.0, 42.0).unwrap();
            let leg_vec = |d: f64, h: f64| {
                let r = h.to_radians();
                (d * r.sin(), d * r.cos())
            };
            let (e1, n1) = leg_vec(legs.starboard_nm, legs.starboard_heading_deg);
            let (e2, n2) = leg_vec(legs.port_nm, legs.port_heading_deg);
            let (te, tn) = leg_vec(8.0, bearing);
            assert!(close(e1 + e2, te, 1e-6), "east off for {bearing}");
            assert!(close(n1 + n2, tn, 1e-6), "north off for {bearing}");
        }
    }

    #[test]
    fn a_mark_dead_upwind_gets_two_symmetric_laylines() {
        let vessel = Position::new(45.0, 13.0);
        let mark = rhumb::destination(vessel, 0.0, 10.0);
        let (from, starboard_end, port_end) =
            layline_rays(vessel, mark, 0.0, 45.0).expect("a beat needs laylines");
        assert_eq!(from, mark);

        // Both ends sit on the mark's own laylines -- reciprocal
        // close-hauled headings from a wind straight from the north -- and
        // therefore equally far from the vessel's own bearing to the
        // mark, mirrored port and starboard.
        let starboard_bearing = rhumb::bearing_deg(mark, starboard_end);
        let port_bearing = rhumb::bearing_deg(mark, port_end);
        assert!((starboard_bearing - 135.0).abs() < 1e-6, "{starboard_bearing}");
        assert!((port_bearing - 225.0).abs() < 1e-6, "{port_bearing}");
    }

    #[test]
    fn a_ray_reaches_past_the_vessel_not_just_to_it() {
        let vessel = Position::new(45.0, 13.0);
        let mark = rhumb::destination(vessel, 10.0, 5.0);
        let (from, starboard_end, _port_end) =
            layline_rays(vessel, mark, 0.0, 45.0).expect("a beat needs laylines");
        // The starboard layline passes near the vessel (it is the one on
        // the vessel's own side, for a mark bearing 10 degrees off a wind
        // from the north) -- its ray must extend beyond that point, not
        // stop short of it.
        let to_vessel_nm = rhumb::distance_nm(from, vessel);
        let to_ray_end_nm = rhumb::distance_nm(from, starboard_end);
        assert!(to_ray_end_nm > to_vessel_nm, "{to_ray_end_nm} vs {to_vessel_nm}");
    }

    #[test]
    fn a_mark_already_fetchable_on_one_tack_needs_no_laylines() {
        let vessel = Position::new(45.0, 13.0);
        // On the beam relative to a wind from the north: no beat at all,
        // the same case tack_legs's own tests cover.
        let mark = rhumb::destination(vessel, 90.0, 5.0);
        assert!(layline_rays(vessel, mark, 0.0, 45.0).is_none());
    }

    #[test]
    fn a_mark_dead_downwind_needs_no_laylines_either() {
        let vessel = Position::new(45.0, 13.0);
        let mark = rhumb::destination(vessel, 180.0, 5.0);
        assert!(layline_rays(vessel, mark, 0.0, 45.0).is_none());
    }

    #[test]
    fn a_tighter_beat_angle_narrows_the_laylines() {
        let vessel = Position::new(45.0, 13.0);
        let mark = rhumb::destination(vessel, 5.0, 8.0);
        let (from, tight_starboard, _) =
            layline_rays(vessel, mark, 0.0, 30.0).expect("still a beat at 30 degrees");
        let (_, wide_starboard, _) =
            layline_rays(vessel, mark, 0.0, 50.0).expect("still a beat at 50 degrees");

        // Both starboard laylines run back towards the wind from a
        // heading close to due south (the reciprocal of a close-hauled
        // course near due north); the tighter angle's should sit closer
        // to the mark's own true bearing back to the vessel.
        let vessel_bearing_from_mark = rhumb::bearing_deg(from, vessel);
        let tight_bearing = rhumb::bearing_deg(from, tight_starboard);
        let wide_bearing = rhumb::bearing_deg(from, wide_starboard);
        let tight_off = angle::diff(vessel_bearing_from_mark, tight_bearing).abs();
        let wide_off = angle::diff(vessel_bearing_from_mark, wide_bearing).abs();
        assert!(tight_off < wide_off, "{tight_off} vs {wide_off}");
    }

    #[test]
    fn a_wind_straight_from_the_north_gives_symmetric_tack_rays() {
        let vessel = Position::new(45.0, 13.0);
        let (starboard_end, port_end) = tack_rays(vessel, 0.0, 45.0);

        // Starboard tack: wind over the starboard side, heading to the
        // left of the wind's own direction -- 315 degrees for a wind from
        // due north at 45 degrees off it. Port tack mirrors it at 045.
        let starboard_bearing = rhumb::bearing_deg(vessel, starboard_end);
        let port_bearing = rhumb::bearing_deg(vessel, port_end);
        assert!((starboard_bearing - 315.0).abs() < 1e-6, "{starboard_bearing}");
        assert!((port_bearing - 45.0).abs() < 1e-6, "{port_bearing}");
    }

    #[test]
    fn tack_rays_need_no_mark_and_never_disappear() {
        // The one property that tells a tack ray apart from a layline:
        // there is no fetchability to fail, so this always returns
        // something, even on the beam or dead downwind -- the two cases
        // that clear a layline entirely.
        let vessel = Position::new(45.0, 13.0);
        let (beam_starboard, beam_port) = tack_rays(vessel, 90.0, 45.0);
        assert_ne!(beam_starboard, vessel);
        assert_ne!(beam_port, vessel);
    }

    #[test]
    fn a_tighter_beat_angle_narrows_the_tack_rays_too() {
        let vessel = Position::new(45.0, 13.0);
        let (tight_starboard, _) = tack_rays(vessel, 0.0, 30.0);
        let (wide_starboard, _) = tack_rays(vessel, 0.0, 50.0);

        let tight_bearing = rhumb::bearing_deg(vessel, tight_starboard);
        let wide_bearing = rhumb::bearing_deg(vessel, wide_starboard);
        // Starboard tack sits to the left of the wind (north, 0 degrees):
        // a narrower beat angle points closer to it, i.e. a smaller
        // bearing measured the short way round from 360.
        assert!(360.0 - tight_bearing < 360.0 - wide_bearing);
    }
}