trail_ticks.hpp

Go to the documentation of this file.

#pragma once
// TradingView's trailing-exit tick arithmetic: how strategy.exit's
// trail_points / trail_offset are read as tick counts and how a trailing
// level is materialized on the tick grid. Every constant here is a
// TradingView calibration (the pins are quoted below), so it belongs to the
// source layer; the kernel's own trail is TrailTicks (native_order.hpp),
// which needs none of it (R5 lane N14: moved verbatim from
// src/engine_internal.hpp, where no kernel translation unit used it).
#include <algorithm>
#include <cmath>
#include <limits>
 
namespace pineforge::compat::pine {
 
// ── Trailing-exit tick arithmetic ─────────────────────────────────────
//
// TradingView reads strategy.exit's trail_points / trail_offset as TICK
// COUNTS: trail_points is ceiled WITH a tolerance that swallows floating-
// point residue — a value computed as close * 0.02 / syminfo.mintick that
// lands a few ulps past a whole number is that whole number, not the next
// one — while trail_offset is floored EXACTLY. Pinned with `lab tv` on
// NYSE:F 15m 2025-04-01..05, short from the 04-02 19:00Z signal (entry
// 10.11, mintick 0.01; scratchpad/r7/pins/trail-eq-*), each zero-offset
// exit filling at its activation level:
//   trail_points 14.00001                -> 14 ticks (9.97)
//   trail_points 14.0001 / 14.001        -> 15 ticks (9.96)
//   trail_points 0.14 / syminfo.mintick  (= 14.000000000000002) -> 14 (9.97)
//   trail_points 14.0000001              -> 14 (9.97)
//   trail_points 18.2                    -> 19 (9.92)
//   trail_offset 0.3 / (syminfo.mintick * 10)  (= 2.9999999999999996)
//     -> 2 ticks (trail_points 18: fills 04-03 14:15Z @9.85 = trough 9.83
//     + 2t; a tolerant floor would trail 3t and print 9.86)
// and BINANCE:BTCUSDT 15m short 2025-08-17 23:30Z @117559.99 with
// trail_points = 117560 * 0.02 / 0.01 = 235120.00000000003: TV exits
// 08-18 03:30Z @115208.79 (235120 ticks); std::ceil gave 235121 -> .78.
// The ceil tolerance is bounded in [1e-5, 1e-4) by the 14.00001 / 14.0001
// pair; 5e-5 sits in the middle. Round 5's sub-tick pins hold: 0.0006 ->
// 1 tick, offsets 0 / 0.5 / 0.9 -> 0, 1.4 -> 1. This constant is
// only the fallback for a run without a usable mintick: TradingView's
// tolerance is c * mintick ticks (the two-argument overload below), which
// at mintick 0.01 also satisfies every pin above.
constexpr double kTrailPointsCeilEps = 5e-5;
 
inline double trail_points_to_ticks(double trail_points) {
    return std::ceil(trail_points - kTrailPointsCeilEps);  // NaN stays NaN
}
 
// The tolerance is not a constant number of ticks: it is c * mintick ticks.
// Pinned with `lab tv` synthetics (4 identical exports each; the
// callback-lifecycle test tapes, *-trailpts-*), each long's trail
// filling at its activation:
//   BINANCE:ETHUSDT.P (0.01): 24.000057417376482 -> 24, 24.00001 -> 24,
//     24.0001 / 24.001 / 24.4 / 24.6 -> 25
//   OANDA:XAUUSD (0.001): 1000.0 / 1000.000003 -> 1000, 1000.00003 -> 1001
//   OANDA:EURUSD (1e-5): 20.0 -> 20, 20.000001 / 20.00003 / 20.02 / 20.2 -> 21
// The ETH pair bounds c to (5.7417e-3, 1e-2); the XAU and EUR rows refute
// any constant tick or price tolerance, and 8e-3 sits inside the interval.
// At mintick 0.01 the tolerance is 8e-5 ticks, so every F and BTC pin above
// still holds. Without a usable mintick the constant rule applies.
constexpr double kTrailPointsCeilMintickScale = 8e-3;
 
inline double trail_points_to_ticks(double trail_points, double mintick) {
    if (!(mintick > 0.0) || !std::isfinite(mintick))
        return trail_points_to_ticks(trail_points);
    return std::ceil(trail_points - kTrailPointsCeilMintickScale * mintick);
}
 
inline double trail_offset_to_ticks(double trail_offset) {
    return std::floor(trail_offset);  // exact; NaN stays NaN
}
 
// The broker keeps trailing levels ON the tick grid: an activation level
// entry -/+ N ticks and a trailing level best -/+ K ticks are tick counts,
// and a bar extreme landing exactly on the level TOUCHES it. Built in
// doubles, 10.11 - 21 * 0.01 is 9.899999999999999 — one ulp under the 9.9
// low — and the inclusive segment test reads it as "not reached" (NYSE:F
// 15m 2025-04-03 13:45Z, bar O 10.165 H 10.18 L 9.9 C 9.9: TV fills the
// trail there @9.90, `lab tv` trail-eq-S-off0-tp21; the engine gap-filled
// the next open @9.89). Materialize a level within a millionth of a tick
// of the grid as the grid point, spelled the way tick_grid_price
// (engine.hpp) spells it so it compares EQUAL to a feed print bit for bit;
// a genuinely sub-tick level (best 196.135 - 1 tick = 196.125) stays raw
// and takes the directional fill snap downstream.
inline double snap_trail_level_to_tick_grid(double price, double mintick) {
    if (std::isnan(price) || !(mintick > 0.0)) return price;
    const double r = price / mintick;
    const double k = std::floor(r + 0.5);
    if (std::abs(r - k) > 1e-6) return price;
    const double inv = 1.0 / mintick;
    const double inv_int = std::floor(inv + 0.5);
    if (inv_int > 0.0 && std::abs(inv - inv_int) <= 1e-6 * inv_int) {
        return k / inv_int;
    }
    return k * mintick;
}
 
// The level the kernel's generic native_order::Trail rests at for a running
// best and a trailing distance, as the source layer's carried-trail tick
// reach reads it (PineExecutionAdapter::retune_carried_trails_for_tick_reach,
// which walks a bar through bests the kernel has not reported yet): best +/-
// distance, except that a distance of whole ticks from a best on the run's
// price ladder IS that ladder point, spelled on the reachable side
// (native_matching::checked_trail_stop and ladder_trail_stop, with the run's
// price tick, which the adapter declares as the symbol's mintick).
// tests/test_kernel_trail_stop_replica.cpp holds it to the kernel's
// arithmetic bit for bit.
inline double kernel_trail_stop_level(double best, double distance, bool is_buy,
                                      double tick) noexcept {
    const double raw = is_buy ? best + distance : best - distance;
    if (distance == 0.0 || !(tick > 0.0) || !std::isfinite(tick)) return raw;
    const auto ladder_index = [&](double price) {
        const double k = std::round(price / tick);
        if (k * tick == price) return k;
        const double inverse = 1.0 / tick;
        const double n = std::round(inverse);
        if (n > 0.0 && std::abs(inverse - n) <= 1e-6 * n && k / n == price) return k;
        return std::numeric_limits<double>::quiet_NaN();
    };
    const double best_index = ladder_index(best);
    const double distance_index = ladder_index(distance);
    if (std::isnan(best_index) || std::isnan(distance_index) || !(distance_index >= 1.0))
        return raw;
    const double index = is_buy ? best_index + distance_index : best_index - distance_index;
    const double product = index * tick;
    const double inverse = 1.0 / tick;
    const double n = std::round(inverse);
    if (!std::isfinite(product) || !(n > 0.0) || std::abs(inverse - n) > 1e-6 * n)
        return product;
    const double quotient = index / n;
    if (!std::isfinite(quotient)) return product;
    // A buy trail's region is price >= level: the lower spelling; a sell
    // trail's is price <= level: the higher.
    return is_buy ? std::min(product, quotient) : std::max(product, quotient);
}
 
}  // namespace pineforge::compat::pine