Skip to content

Commit 0f1f06e

Browse files
luisleo526PineForge Factorial
andauthored
factorial: engine-symbol-r7 [engine] (#164)
Co-authored-by: PineForge Factorial <[email protected]>
1 parent 7fc7347 commit 0f1f06e

22 files changed

Lines changed: 1967 additions & 94 deletions

‎include/pineforge/engine.hpp‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1069,7 +1069,13 @@ class BacktestEngine {
10691069
// Independent opt-in KI-55 HTF warmup parity. When enabled,
10701070
// request.security series aggregate from security_range_start_ms_ instead
10711071
// of the feed start and their embedded ta.ema na-warm per TV built-in
1072-
// semantics. Default OFF; touched only through feed_security_eval_state.
1072+
// semantics. The cut is taken per evaluator on HTF-BUCKET opens, not on
1073+
// input timestamps: an input bar is dropped when the D/W/M (or intraday
1074+
// grid) bucket it belongs to opened before the range start, so the first
1075+
// HTF bar every series sees is a whole bucket that opened at/after the
1076+
// range start (security_input_precedes_range_start). Default OFF;
1077+
// consulted only by feed_security_eval_state and the historical
1078+
// lookahead projection builder.
10731079
bool security_range_start_na_warmup_ = false;
10741080
int64_t security_range_start_ms_ = 0;
10751081
// Opt-in historical-only request.security lookahead projection. TradingView
@@ -2220,6 +2226,14 @@ class BacktestEngine {
22202226
int security_lower_tf_sub_bar_index(int sec_id) const;
22212227
void validate_security_timeframes(const std::string& input_tf);
22222228
bool security_series_slot_is_new(int sec_id) const;
2229+
// KI-55 range-start gate for one evaluator: true when the input bar at
2230+
// `input_ts` belongs to an HTF bucket that opened before
2231+
// security_range_start_ms_ (always false while the flag is off). The
2232+
// progressive feed and the historical lookahead projection builder must
2233+
// agree on this predicate so projected child indexes line up with the
2234+
// per-state feed cursor.
2235+
bool security_input_precedes_range_start(const SecurityEvalState& state,
2236+
int64_t input_ts) const;
22232237
void feed_security_eval_state(SecurityEvalState& state, const Bar& input_bar);
22242238

22252239
virtual void configure_security_evaluators() {}
@@ -2906,6 +2920,28 @@ class BacktestEngine {
29062920
// would regress the crypto-on-shifted-chart case).
29072921
void set_syminfo_timezone(const std::string& tz) { syminfo_.timezone = tz; }
29082922
void set_syminfo_session(const std::string& s) { syminfo_.session = s; }
2923+
// ``syminfo.type`` ("crypto" default; "forex" / "stock" / "futures" /
2924+
// "index" / "fund" / "cfd" per TradingView). Scripts branch on it for
2925+
// instrument conventions — the canonical one being the pip size
2926+
// (``syminfo.type == "forex" ? 0.0001 : syminfo.mintick``), which on a
2927+
// 5-digit FX symbol under the crypto default computed every pip-scaled
2928+
// stop/target 10x too tight (finding 454). Empty is ignored.
2929+
void set_syminfo_type(const std::string& t) { if (!t.empty()) syminfo_.type = t; }
2930+
// Generic string-field injection for the remaining OHLCV-less syminfo
2931+
// members (ticker / tickerid / currency / basecurrency / description /
2932+
// volumetype / type). Unknown keys and empty values are ignored; returns
2933+
// true when a field was set.
2934+
bool set_syminfo_string(const std::string& key, const std::string& value) {
2935+
if (value.empty()) return false;
2936+
if (key == "type") { syminfo_.type = value; return true; }
2937+
if (key == "ticker") { syminfo_.ticker = value; return true; }
2938+
if (key == "tickerid") { syminfo_.tickerid = value; return true; }
2939+
if (key == "currency") { syminfo_.currency = value; return true; }
2940+
if (key == "basecurrency") { syminfo_.basecurrency = value; return true; }
2941+
if (key == "description") { syminfo_.description = value; return true; }
2942+
if (key == "volumetype") { syminfo_.volumetype = value; return true; }
2943+
return false;
2944+
}
29092945
// Runtime syminfo injection (by design — the engine stores no instrument
29102946
// metadata of its own; the harness supplies it per run). mintick drives the
29112947
// directional fill snap + slippage*tick economics; pointvalue is the

‎include/pineforge/pineforge.h‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -611,6 +611,19 @@ PF_API void strategy_set_syminfo_timezone(pf_strategy_t s, const char* tz);
611611
* ignored. Call before #run_backtest*. */
612612
PF_API void strategy_set_syminfo_session(pf_strategy_t s, const char* session);
613613

614+
/** Set the instrument class (``syminfo.type``: "forex", "stock", "crypto",
615+
* "futures", "index", "fund", "cfd", ...; default "crypto"). Scripts branch
616+
* on it for instrument conventions (e.g. the forex pip size). `NULL` /
617+
* empty ignored. Call before #run_backtest*. */
618+
PF_API void strategy_set_syminfo_type(pf_strategy_t s, const char* type);
619+
620+
/** Set one of the remaining string ``syminfo.*`` members by Pine member
621+
* name: "ticker", "tickerid", "currency", "basecurrency", "description",
622+
* "volumetype" (and "type"). Returns 0 when set, -1 for an unknown key,
623+
* empty value or NULL. Call before #run_backtest*. */
624+
PF_API int strategy_set_syminfo_string(pf_strategy_t s, const char* key,
625+
const char* value);
626+
614627
/** Set the instrument tick size (``syminfo.mintick``, default 0.01). Drives the
615628
* directional stop-entry snap and ``slippage = N*mintick`` economics. Set
616629
* per-instrument (e.g. 0.25 for ES, 0.00001 for FX). Non-positive ignored.

‎include/pineforge/timeframe.hpp‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,18 @@ int64_t session_period_close_ms(int64_t ms, const std::string& tz,
138138
const std::string& session,
139139
CalendarPeriod period);
140140

141+
/// Exclusive close (Unix ms) of the LAST TRADED session-day of the D/W/M
142+
/// bar that contains `ms`: DAY is session_period_close_ms; WEEK / MONTH
143+
/// step back from the period's last session-day over weekend TRADING dates
144+
/// (Saturday / Sunday never hold a session on exchange-calendar symbols),
145+
/// so an equity week ends Friday 16:00 ET, a month whose last calendar day
146+
/// is a weekend ends on its last Friday, and the forex week ends Friday
147+
/// 17:00 ET (the Friday-open session is Saturday's trading date). Exchange
148+
/// holidays are not modelled. CalendarPeriod::NONE returns `ms`.
149+
int64_t session_period_last_traded_close_ms(int64_t ms, const std::string& tz,
150+
const std::string& session,
151+
CalendarPeriod period);
152+
141153
// ─── TimeframeAggregator ───────────────────────────────────────────────────────
142154

143155
class TimeframeAggregator {
@@ -173,6 +185,17 @@ class TimeframeAggregator {
173185
/// Whether aggregation is active (non-passthrough).
174186
bool is_active() const;
175187

188+
/// Open (Unix ms) of the target-TF bucket an input bar stamped `ms`
189+
/// belongs to, on the aggregator's anchor clock (syminfo tz + session):
190+
/// CALENDAR -> session_period_open_ms of the bar's D/W/M period (the
191+
/// forex week opens Sunday 17:00 ET, its month on the session whose
192+
/// close date is the 1st); RATIO -> the session-open-anchored intraday
193+
/// grid bucket (the same key feed() splits on); PASSTHROUGH, or a
194+
/// count-only ratio with no wall-clock width, -> `ms` itself. Pure
195+
/// function of the configuration: it neither reads nor advances the
196+
/// aggregation state, so callers may query it before feeding the bar.
197+
int64_t bucket_open_ms(int64_t ms) const;
198+
176199
private:
177200
enum class Mode { PASSTHROUGH, RATIO, CALENDAR };
178201

‎scripts/check_c_abi_runtime.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@
2222
"strategy_set_chart_timezone",
2323
"strategy_set_syminfo_timezone",
2424
"strategy_set_syminfo_session",
25+
"strategy_set_syminfo_type",
26+
"strategy_set_syminfo_string",
2527
"strategy_set_syminfo_mintick",
2628
"strategy_set_syminfo_pointvalue",
2729
"strategy_set_syminfo_metadata",

‎scripts/run_strategy.py‎

Lines changed: 61 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1017,6 +1017,13 @@ def _num(v):
10171017
chart_timezone=chart_tz,
10181018
syminfo_timezone=str(runtime_overrides.get("timezone") or "") or None,
10191019
syminfo_session=str(runtime_overrides.get("session") or "") or None,
1020+
syminfo_type=str(runtime_overrides.get("type") or "") or None,
1021+
syminfo_strings={
1022+
k: str(runtime_overrides.get(k))
1023+
for k in ("ticker", "tickerid", "currency", "basecurrency",
1024+
"description", "volumetype")
1025+
if runtime_overrides.get(k)
1026+
} or None,
10201027
syminfo_metadata=syminfo_metadata,
10211028
syminfo_mintick=_num(runtime_overrides.get("mintick")),
10221029
syminfo_pointvalue=_num(runtime_overrides.get("pointvalue")),
@@ -1125,6 +1132,16 @@ def _setup_signatures(self) -> None:
11251132
if hasattr(L, "strategy_set_syminfo_session"):
11261133
L.strategy_set_syminfo_session.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
11271134
L.strategy_set_syminfo_session.restype = None
1135+
# syminfo.type ("forex"/"stock"/"crypto"/...) + the generic string
1136+
# member setter (ticker/tickerid/currency/basecurrency/...). Older
1137+
# .so builds predate these exports — hasattr-guarded like the rest.
1138+
if hasattr(L, "strategy_set_syminfo_type"):
1139+
L.strategy_set_syminfo_type.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
1140+
L.strategy_set_syminfo_type.restype = None
1141+
if hasattr(L, "strategy_set_syminfo_string"):
1142+
L.strategy_set_syminfo_string.argtypes = [
1143+
ctypes.c_void_p, ctypes.c_char_p, ctypes.c_char_p]
1144+
L.strategy_set_syminfo_string.restype = ctypes.c_int
11281145
if hasattr(L, "strategy_set_syminfo_metadata"):
11291146
L.strategy_set_syminfo_metadata.argtypes = [
11301147
ctypes.c_void_p, ctypes.c_char_p, ctypes.c_double]
@@ -1151,6 +1168,8 @@ def run(self, bars_csv: Path, params: dict | None = None,
11511168
chart_timezone: str | None = None,
11521169
syminfo_timezone: str | None = None,
11531170
syminfo_session: str | None = None,
1171+
syminfo_type: str | None = None,
1172+
syminfo_strings: dict | None = None,
11541173
syminfo_metadata: dict | None = None,
11551174
syminfo_mintick: float | None = None,
11561175
syminfo_pointvalue: float | None = None,
@@ -1243,6 +1262,17 @@ def run(self, bars_csv: Path, params: dict | None = None,
12431262
self.lib.strategy_set_syminfo_timezone(state, str(syminfo_timezone).encode())
12441263
if syminfo_session and hasattr(self.lib, "strategy_set_syminfo_session"):
12451264
self.lib.strategy_set_syminfo_session(state, str(syminfo_session).encode())
1265+
# Instrument class (syminfo.type). Unset keeps the engine's
1266+
# "crypto" default byte-identical; per-symbol datasets pass
1267+
# TV's value ("forex" for OANDA:EURUSD, "stock" for NASDAQ:AAPL).
1268+
if syminfo_type and hasattr(self.lib, "strategy_set_syminfo_type"):
1269+
self.lib.strategy_set_syminfo_type(state, str(syminfo_type).encode())
1270+
if syminfo_strings and hasattr(self.lib, "strategy_set_syminfo_string"):
1271+
for skey, sval in syminfo_strings.items():
1272+
if sval is None or str(sval) == "":
1273+
continue
1274+
self.lib.strategy_set_syminfo_string(
1275+
state, str(skey).encode(), str(sval).encode())
12461276
if syminfo_metadata and hasattr(self.lib, "strategy_set_syminfo_metadata"):
12471277
for mkey, mval in syminfo_metadata.items():
12481278
try:
@@ -1515,6 +1545,32 @@ def _filter_trace_to_window(trace: list[dict], window: tuple[int, int] | None) -
15151545
]
15161546

15171547

1548+
def format_trade_qty(qty: float) -> str:
1549+
"""Lot-faithful quantity text for the TV-alignable export.
1550+
1551+
The previous ``f"{qty:g}"`` kept only 6 significant digits, so any
1552+
quantity with more digits than that was silently rewritten on the way
1553+
out: an OANDA:EURUSD all-in lot of 923941.16 units (TV export, 0.01 lot
1554+
step) printed as ``923941``, 897902.68 printed as ``897903`` (rounded UP),
1555+
92293.36 as ``92293.4``, and anything >= 1e6 as ``1e+06``. The ledger held
1556+
the exact value; only the CSV lied, which put a spurious 0.01-0.5 unit
1557+
"qty miss" on 1933/2708 entries of the EURUSD KI-52 all-in probe and on
1558+
every giua64 entry while the fills themselves were exact.
1559+
1560+
Eight decimals cover every lot step in use (1 share, 0.01 unit, 0.0001
1561+
contract, satoshi-scale 1e-8) and absorb binary noise from
1562+
floor(q/step)*step (0.30000000000000004 -> ``0.3``); trailing zeros are
1563+
trimmed the way TradingView prints its ``Size (qty)`` column, so every
1564+
value the old formatter rendered faithfully renders byte-identically.
1565+
"""
1566+
if not math.isfinite(qty):
1567+
return f"{qty:g}"
1568+
text = f"{qty:.8f}".rstrip("0").rstrip(".")
1569+
if text in ("", "-0", "-"):
1570+
return "0"
1571+
return text
1572+
1573+
15181574
def write_engine_trades_csv(trades: list[dict], path: Path) -> None:
15191575
"""Emit one row per trade *side* (exit then entry) in reverse-chronological
15201576
order — byte-for-byte alignable with TradingView's `trades.csv` export.
@@ -1552,7 +1608,7 @@ def write_engine_trades_csv(trades: list[dict], path: Path) -> None:
15521608
n, side,
15531609
_fmt_time_utc(t[time_key]),
15541610
f"{t[price_key]:.6f}",
1555-
f"{t['qty']:g}",
1611+
format_trade_qty(float(t["qty"])),
15561612
f"{t['pnl']:.6f}",
15571613
f"{t['pnl_pct']:.4f}",
15581614
f"{t['max_runup']:.6f}",
@@ -1677,6 +1733,10 @@ def _run_via_docker(strategy_dir: Path, ohlcv_path: Path, params: dict,
16771733
syminfo["timezone"] = run_kwargs["syminfo_timezone"]
16781734
if run_kwargs.get("syminfo_session"):
16791735
syminfo["session"] = run_kwargs["syminfo_session"]
1736+
if run_kwargs.get("syminfo_type"):
1737+
syminfo["type"] = run_kwargs["syminfo_type"]
1738+
for skey, sval in (run_kwargs.get("syminfo_strings") or {}).items():
1739+
syminfo[skey] = sval
16801740
if run_kwargs.get("syminfo_mintick") is not None:
16811741
syminfo["mintick"] = run_kwargs["syminfo_mintick"]
16821742
if run_kwargs.get("syminfo_pointvalue") is not None:

‎scripts/test_run_strategy_identity.py‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
from pathlib import Path
1010

1111
from pf_release_run import report_trades_to_runstrategy_shape
12-
from run_strategy import write_engine_trades_csv
12+
from run_strategy import format_trade_qty, write_engine_trades_csv
1313

1414

1515
class EngineEntryIdentityCsvTests(unittest.TestCase):
@@ -81,5 +81,50 @@ def test_release_report_mapping_preserves_incarnation(self) -> None:
8181
self.assertEqual(mapped[0]["entry_incarnation"], 73)
8282

8383

84+
class EngineTradeQtyFormatTests(unittest.TestCase):
85+
"""The exported ``Qty`` column must carry the ledger quantity to the lot
86+
step: ``%g``'s 6 significant digits truncated (and sometimes rounded UP)
87+
every OANDA:EURUSD-scale lot (TV KI-52 all-in: 92293.36 units)."""
88+
89+
def test_large_lots_keep_every_lot_step_digit(self) -> None:
90+
self.assertEqual(format_trade_qty(923941.16), "923941.16")
91+
self.assertEqual(format_trade_qty(897902.68), "897902.68")
92+
self.assertEqual(format_trade_qty(92293.36), "92293.36")
93+
self.assertEqual(format_trade_qty(1000000.0), "1000000")
94+
self.assertEqual(format_trade_qty(8741.59), "8741.59")
95+
96+
def test_binary_noise_and_trailing_zeros_are_trimmed(self) -> None:
97+
self.assertEqual(format_trade_qty(0.30000000000000004), "0.3")
98+
self.assertEqual(format_trade_qty(2.7051000000000001), "2.7051")
99+
self.assertEqual(format_trade_qty(1.0), "1")
100+
self.assertEqual(format_trade_qty(44.0), "44")
101+
self.assertEqual(format_trade_qty(0.0001), "0.0001")
102+
self.assertEqual(format_trade_qty(0.0), "0")
103+
104+
def test_values_the_old_formatter_rendered_exactly_are_unchanged(self) -> None:
105+
for qty in (55.2872, 5.4103, 0.0196, 44.9622, 48, 7.7232, 30.3796):
106+
self.assertEqual(format_trade_qty(float(qty)), f"{float(qty):g}")
107+
108+
def test_writer_uses_lot_faithful_qty(self) -> None:
109+
trade = {
110+
"entry_time": 1_735_689_600_000,
111+
"exit_time": 1_735_689_660_000,
112+
"entry_price": 1.08232,
113+
"exit_price": 1.07836,
114+
"pnl": -3658.81,
115+
"pnl_pct": -0.37,
116+
"is_long": True,
117+
"max_runup": 0.0,
118+
"max_drawdown": 0.0,
119+
"qty": 923941.16,
120+
}
121+
with tempfile.TemporaryDirectory() as tmp:
122+
path = Path(tmp) / "engine_trades.csv"
123+
write_engine_trades_csv([trade], path)
124+
with path.open(newline="", encoding="utf-8") as handle:
125+
rows = list(csv.DictReader(handle))
126+
self.assertEqual([row["Qty"] for row in rows], ["923941.16", "923941.16"])
127+
128+
84129
if __name__ == "__main__":
85130
unittest.main()

‎src/c_abi.cpp‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,23 @@ PF_API void strategy_set_syminfo_session(pf_strategy_t s, const char* session) {
257257
static_cast<pineforge::BacktestEngine*>(s)->set_syminfo_session(std::string(session));
258258
}
259259

260+
/* Plumb the instrument class (syminfo.type: "forex" / "stock" / "crypto" /
261+
* "futures" / ...) into syminfo_. Defaults to "crypto"; NULL/empty ignored. */
262+
PF_API void strategy_set_syminfo_type(pf_strategy_t s, const char* type) {
263+
if (!s || !type) return;
264+
static_cast<pineforge::BacktestEngine*>(s)->set_syminfo_type(std::string(type));
265+
}
266+
267+
/* Generic string-member injection (ticker / tickerid / currency /
268+
* basecurrency / description / volumetype / type). Returns 0 when set, -1
269+
* for a NULL handle, unknown key or empty value. */
270+
PF_API int strategy_set_syminfo_string(pf_strategy_t s, const char* key,
271+
const char* value) {
272+
if (!s || !key || !value) return -1;
273+
return static_cast<pineforge::BacktestEngine*>(s)->set_syminfo_string(
274+
std::string(key), std::string(value)) ? 0 : -1;
275+
}
276+
260277
/* Inject the instrument tick size (syminfo.mintick). Drives the directional
261278
* stop-entry snap (long ceil / short floor) and slippage = N*mintick economics.
262279
* Defaults to 0.01 (crypto/equity); set per-instrument (e.g. 0.25 for ES,

0 commit comments

Comments
 (0)