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 (the source-runtime extraction: 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; a synthetic short entered at 20.06 with mintick 0.01
// illustrates the same rule, with each zero-offset
// exit filling at its activation level:
//   trail_points 14.00001                -> 14 ticks (19.92)
//   trail_points 14.0001 / 14.001        -> 15 ticks (19.91)
//   trail_points 0.14 / syminfo.mintick  (= 14.000000000000002) -> 14 (19.92)
//   trail_points 14.0000001              -> 14 (19.92)
//   trail_points 18.2                    -> 19 (19.87)
//   trail_offset 0.3 / (syminfo.mintick * 10)  (= 2.9999999999999996)
//     -> 2 ticks (synthetic trough 19.80: fill 19.82
//     = trough + 2t; a tolerant floor would trail 3t and print 19.83)
// A synthetic BINANCE:BTCUSDT 15m short at 12807.99 with
// trail_points = 12808 * 0.02 / 0.01 = 25616.000000000004 exits
// at 12551.83 (25616 ticks); std::ceil gives 25617 -> 12551.82.
// 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, 20.06 - 21 * 0.01 is 19.849999999999998 — one ulp under the 19.85
// low — and the inclusive segment test reads it as "not reached" (NYSE:F
// synthetic 15m bar O 20.10 H 20.12 L 19.85 C 19.85: the trail fills
// there at 19.85; a raw comparison would miss the touch and gap-fill
// the next open at 19.84). 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 35.035 - 1 tick = 35.025) 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