Skip to content

Commit b4dd9a3

Browse files
luisleo526claude
andcommitted
docs(mtf): add multi-timeframe tutorial + Doxygen page
Two side-by-side strategies under tutorial/mtf/ exercise both MTF surfaces — request.security (HTF aggregation) and request.security_lower_tf (sub-bar synthesis from input OHLC). A new run_mtf.py prints three tables that walk script_tf switching, the input_tf/script_tf pair matrix, and the lower-TF synthesis ratio, each annotated with the run_backtest_full(...) call signature it uses. A new @page mtf documents the script_tf/input_tf concatenation model, the lower-TF design contract (input feed bounds the target resolution, no separate finer feed), and the codegen pattern. timeframes.md and index.md cross-link to it. Co-Authored-By: Claude Opus 4.7 <[email protected]>
1 parent 2b997f4 commit b4dd9a3

11 files changed

Lines changed: 972 additions & 35 deletions

File tree

‎docs/Doxyfile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,7 @@ INPUT = ../include/pineforge/pineforge.h \
9494
pages/configuration.md \
9595
pages/magnifier.md \
9696
pages/timeframes.md \
97+
pages/mtf.md \
9798
pages/ffi-python.md \
9899
pages/tutorial-macd.md \
99100
pages/examples-c.md \

‎docs/pages/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ Five end-to-end, runnable examples that go beyond the MACD tutorial:
6060
| [Parameter sweep in Python](@ref examples_python_sweep) | Re-run one `.so` over a 2-D grid; sticky configuration; walk-forward variant. |
6161
| [Multi-strategy harness](@ref examples_multi) | Load N `.so` files; rank by net PnL; thread-pool execution. |
6262
| [Magnifier on vs off](@ref examples_magnifier) | A/B comparison with all six distribution modes. |
63+
| [Multi-timeframe (MTF)](@ref mtf) | `script_tf` switching, `request.security`, and lower-TF sub-bar synthesis. |
6364
| [Calling from Rust](@ref examples_rust) | Idiomatic `libloading` wrapper with safe Rust types. |
6465

6566
---

‎docs/pages/mtf.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Multi-Timeframe (MTF) {#mtf}
2+
3+
@tableofcontents
4+
5+
PineForge exposes two distinct multi-timeframe surfaces. They look
6+
similar from Pine but resolve through completely different runtime
7+
paths, and they have different rules:
8+
9+
| Surface | Pine call | Direction | Bars source |
10+
| --- | --- | --- | --- |
11+
| **Upward (HTF)** | `request.security(sym, "60", expr)` | target TF **coarser** than input | aggregated from input bars |
12+
| **Downward (LTF)** | `request.security_lower_tf(sym, "1", expr)` | target TF **finer** than input | **synthesized** from each input bar's OHLC path |
13+
14+
The downward path is where PineForge diverges from TradingView. TV
15+
downloads a separate finer-resolution feed when you switch to a lower
16+
timeframe; PF does **not**. The input feed's resolution is the upper
17+
bound on what `request.security_lower_tf` can target — beyond that, no
18+
data exists. Sub-bars are synthesized on demand by walking the input
19+
bar's OHLC path. See @ref magnifier for the same idea applied to fill
20+
resolution.
21+
22+
For the upward path and the chart-aggregation rules, see also
23+
@ref timeframes.
24+
25+
## The script_tf / input_tf model
26+
27+
Every backtest run takes two timeframe strings on
28+
`run_backtest_full(...)`:
29+
30+
```c
31+
run_backtest_full(s, bars, n,
32+
/* input_tf */ "", // empty → auto-detect from bar timestamps
33+
/* script_tf */ "", // empty → defaults to input_tf
34+
/* magnifier */ 0, 4, PF_MAGNIFIER_ENDPOINTS,
35+
&report);
36+
```
37+
38+
The runtime resolves them in order:
39+
40+
1. `input_tf` — what the bar feed actually is. If empty, the runtime
41+
computes the median delta between consecutive `pf_bar_t::timestamp`
42+
values and snaps to a canonical Pine TF.
43+
2. `script_tf` — what the strategy script believes it's running on.
44+
If empty, defaults to the resolved `input_tf`.
45+
3. If `script_tf > input_tf`, the runtime aggregates input bars up to
46+
script-TF parents before each `on_bar` dispatch. The two timeframes
47+
are concatenated by an aggregator (ratio or calendar — see
48+
`src/engine_security.cpp`).
49+
50+
The report exposes the resolved values and the ratio:
51+
52+
| Report field | Meaning |
53+
| --- | --- |
54+
| `input_tf_seconds` | Resolved input TF (after auto-detect). |
55+
| `script_tf_seconds` | Resolved script TF (after defaulting). |
56+
| `script_tf_ratio` | `script_tf_seconds / input_tf_seconds`. |
57+
| `needs_aggregation` | `1` when ratio > 1, `0` otherwise. |
58+
59+
## Switching timeframes — C
60+
61+
```c
62+
pf_report_t r = {0};
63+
64+
// 1. Both empty → auto-detect input, default script to input.
65+
run_backtest_full(s, bars, n, "", "", 0, 4, PF_MAGNIFIER_ENDPOINTS, &r);
66+
// r.input_tf_seconds == 900 (15m, auto-detected)
67+
// r.script_tf_seconds == 900 (defaulted)
68+
// r.script_tf_ratio == 1
69+
// r.needs_aggregation == 0
70+
71+
// 2. Explicit input + explicit higher script → 4:1 aggregation.
72+
run_backtest_full(s, bars, n, "15", "60", 0, 4, PF_MAGNIFIER_ENDPOINTS, &r);
73+
// r.input_tf_seconds == 900
74+
// r.script_tf_seconds == 3600
75+
// r.script_tf_ratio == 4
76+
// r.needs_aggregation == 1
77+
78+
// 3. Explicit input, script defaults to input.
79+
run_backtest_full(s, bars, n, "15", "", 0, 4, PF_MAGNIFIER_ENDPOINTS, &r);
80+
// r.input_tf_seconds == 900
81+
// r.script_tf_seconds == 900 (defaulted, NOT inferred separately)
82+
```
83+
84+
## Switching timeframes — Python (ctypes)
85+
86+
```python
87+
# Same three calls, byte-string TFs.
88+
lib.run_backtest_full(s, bars, n, b"", b"", 0, 4, 3, byref(r))
89+
lib.run_backtest_full(s, bars, n, b"15", b"60", 0, 4, 3, byref(r))
90+
lib.run_backtest_full(s, bars, n, b"15", b"", 0, 4, 3, byref(r))
91+
```
92+
93+
The full runnable harness — three tables walking the script_tf sweep,
94+
the input_tf/script_tf pair matrix, and the lower-TF synthesis ratio
95+
— is in `tutorial/run_mtf.py`. See the **Worked example** section
96+
below.
97+
98+
## request.security_lower_tf — the codegen contract
99+
100+
The lower-TF builtin returns an array of one value per synthesized
101+
sub-bar. The codegen pattern in `generated.cpp` is:
102+
103+
```cpp
104+
class GeneratedStrategy : public BacktestEngine {
105+
public:
106+
// Accumulator vector for the sub-bar values.
107+
std::vector<double> _req_sec_lower_tf_0{};
108+
109+
void configure_security_evaluators() override {
110+
security_eval_states_.clear();
111+
// sec_id 0, target "1" minute, input_tf passed through from the
112+
// run-time resolved value.
113+
register_security_lower_tf_eval(0, std::string("1"), input_tf_);
114+
}
115+
116+
void evaluate_security(int sec_id, const Bar& bar, bool is_complete) override {
117+
if (sec_id != 0 || !is_complete) return;
118+
// Sub-bar 0 marks the start of a new chart bar — clear before pushing.
119+
if (security_lower_tf_sub_bar_index(0) == 0) {
120+
_req_sec_lower_tf_0.clear();
121+
}
122+
_req_sec_lower_tf_0.push_back(bar.close);
123+
}
124+
125+
void on_bar(const Bar& bar) override {
126+
// _req_sec_lower_tf_0 is the Pine array returned by
127+
// request.security_lower_tf(sym, "1", close).
128+
// ... compute on it ...
129+
}
130+
};
131+
```
132+
133+
### Validation rules
134+
135+
When `configure_security_evaluators` runs, the engine validates each
136+
registered lower-TF site against `input_tf_`:
137+
138+
- The target TF must be **strictly finer** than the resolved input TF.
139+
- The input TF (in seconds) must be an **integer multiple** of the
140+
target TF — non-clean ratios are rejected.
141+
- `lookahead` and `gaps` must be off (TV does not expose them on this
142+
builtin and PF refuses to fake them).
143+
144+
Violations raise at run-time with a precise diagnostic, e.g.:
145+
146+
```
147+
request.security_lower_tf requires a timeframe finer than the
148+
chart's input timeframe: requested 30 from input timeframe 15
149+
```
150+
151+
### Sub-bar synthesis
152+
153+
For each input bar, the engine generates `input_tf / target_tf`
154+
synthetic sub-bars by walking the input bar's OHLC endpoints (the
155+
same path-sampling primitive the bar magnifier uses, see
156+
`src/engine_lower_tf.cpp`). Each synthetic sub-bar gets `1/ratio` of
157+
the input bar's volume.
158+
159+
Per-run sub-bar counts surface in the report's `security_feeds_total`
160+
field. With a 15m chart and a `"1"` lower-TF target, expect:
161+
162+
```
163+
security_feeds_total == 15 * input_bars_processed
164+
```
165+
166+
## Worked example
167+
168+
`tutorial/mtf/` ships two strategies side-by-side:
169+
170+
| File | Demonstrates |
171+
| --- | --- |
172+
| `tutorial/mtf/strategy_htf.pine` + `generated_htf.cpp` | `request.security` (HTF SMA filter on a 15m chart). HTF is an input — sweepable without rebuild. |
173+
| `tutorial/mtf/strategy_ltf.pine` + `generated_ltf.cpp` | `request.security_lower_tf("1", close)` — intra-bar 1m range as an entry signal. |
174+
| `tutorial/run_mtf.py` | Three tables: script_tf sweep, input_tf/script_tf pair matrix, lower-TF synthesis ratio. |
175+
176+
Build:
177+
178+
```bash
179+
cmake --build build --target strategy_tutorial_mtf_htf strategy_tutorial_mtf_ltf -j
180+
python3 tutorial/run_mtf.py
181+
```
182+
183+
Expected (excerpt):
184+
185+
```
186+
Table A — script_tf sweep, fixed input (HTF .so)
187+
script_tf in_s sc_s ratio agg? in_bars sc_bars trades net_pnl
188+
"" 900 900 1 0 672 672 1 -653.46
189+
"15" 900 900 1 0 672 672 1 -653.46
190+
"60" 900 3600 4 1 672 168 6 -962.57
191+
"240" 900 14400 16 1 672 42 0 +0.00
192+
```
193+
194+
Numbers depend on the OHLCV snapshot.
195+
196+
## See also
197+
198+
- @ref timeframes — TF strings, auto-detection, calendar vs ratio aggregation.
199+
- @ref magnifier — sub-bar synthesis for fill resolution (same primitive).
200+
- @ref tutorial_macd — single-cadence baseline this tutorial extends.

‎docs/pages/timeframes.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,10 @@ These are counted in `pf_report_t::security_complete_total` and
8888
`pf_report_t::security_partial_total`. Per-site counters live in
8989
`security_diag[i]`.
9090

91+
For the lower-TF surface (`request.security_lower_tf`) — including the
92+
codegen contract, validation rules, and the contrast with TradingView's
93+
separate-feed model — see @ref mtf.
94+
9195
## Practical guidance
9296

9397
- For trade-list parity with TradingView, set both `input_tf` and

‎tutorial/CMakeLists.txt‎

Lines changed: 59 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,69 @@
1-
# tutorial/CMakeLists.txt — build the tutorial MACD strategy.so.
1+
# tutorial/CMakeLists.txt — build the tutorial strategy .so files.
22
#
33
# Mirrors the per-strategy build in corpus/CMakeLists.txt but kept
4-
# small (one strategy, no glob) so the wiring is easy to read alongside
4+
# small (one helper, no glob) so the wiring is easy to read alongside
55
# the tutorial itself.
66
#
7-
# Output: tutorial/macd/strategy.so (loaded by tutorial/run.py)
8-
# Target: strategy_tutorial_macd (built by tutorial/run.sh)
7+
# Outputs:
8+
# tutorial/macd/strategy.so (loaded by tutorial/run.py)
9+
# tutorial/mtf/strategy_htf.so (loaded by tutorial/run_mtf.py)
10+
# tutorial/mtf/strategy_ltf.so (loaded by tutorial/run_mtf.py)
11+
# Targets:
12+
# strategy_tutorial_macd (built by tutorial/run.sh)
13+
# strategy_tutorial_mtf_htf (built by tutorial/run_mtf.py via cmake)
14+
# strategy_tutorial_mtf_ltf (built by tutorial/run_mtf.py via cmake)
915

10-
set(TUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/macd)
16+
# Helper — declares one strategy.so target with all the link-options /
17+
# warning-suppressions / output-path boilerplate the tutorial wants.
18+
function(pineforge_tutorial_strategy target src out_dir out_name)
19+
add_library(${target} SHARED ${src})
20+
target_link_libraries(${target} PRIVATE pineforge)
1121

12-
add_library(strategy_tutorial_macd SHARED ${TUT_DIR}/generated.cpp)
22+
# Force-load libpineforge so the c_abi.cpp symbols (pf_version_get,
23+
# strategy_set_trace_enabled) — which the strategy body never
24+
# references but the Python harnesses expect via dlsym — are pulled in.
25+
if(APPLE)
26+
target_link_options(${target} PRIVATE
27+
"-Wl,-force_load,$<TARGET_FILE:pineforge>")
28+
elseif(UNIX)
29+
target_link_options(${target} PRIVATE
30+
"-Wl,--whole-archive"
31+
"$<TARGET_FILE:pineforge>"
32+
"-Wl,--no-whole-archive")
33+
endif()
1334

14-
target_link_libraries(strategy_tutorial_macd PRIVATE pineforge)
35+
# Suppress a few warnings the strategy translation unit cannot fix.
36+
target_compile_options(${target} PRIVATE
37+
-Wno-unused-but-set-variable
38+
-Wno-unused-variable
39+
-Wno-unused-parameter
40+
-Wno-sign-compare)
1541

16-
# Force-load libpineforge so the c_abi.cpp symbols (pf_version_get,
17-
# strategy_set_trace_enabled) — which the strategy body never
18-
# references but tutorial/run.py expects via dlsym — are pulled in.
19-
if(APPLE)
20-
target_link_options(strategy_tutorial_macd PRIVATE
21-
"-Wl,-force_load,$<TARGET_FILE:pineforge>")
22-
elseif(UNIX)
23-
target_link_options(strategy_tutorial_macd PRIVATE
24-
"-Wl,--whole-archive"
25-
"$<TARGET_FILE:pineforge>"
26-
"-Wl,--no-whole-archive")
27-
endif()
28-
29-
# Suppress a few warnings the strategy translation unit cannot fix.
30-
target_compile_options(strategy_tutorial_macd PRIVATE
31-
-Wno-unused-but-set-variable
32-
-Wno-unused-variable
33-
-Wno-unused-parameter
34-
-Wno-sign-compare)
35-
36-
# Place the .so next to its source (so tutorial/run.py finds it at the
37-
# default path tutorial/macd/strategy.so).
38-
set_target_properties(strategy_tutorial_macd PROPERTIES
39-
LIBRARY_OUTPUT_DIRECTORY ${TUT_DIR}
40-
RUNTIME_OUTPUT_DIRECTORY ${TUT_DIR}
41-
OUTPUT_NAME strategy
42-
PREFIX ""
43-
SUFFIX ".so")
42+
# Place the .so next to its source so the Python harnesses find it
43+
# at their hard-coded path.
44+
set_target_properties(${target} PROPERTIES
45+
LIBRARY_OUTPUT_DIRECTORY ${out_dir}
46+
RUNTIME_OUTPUT_DIRECTORY ${out_dir}
47+
OUTPUT_NAME ${out_name}
48+
PREFIX ""
49+
SUFFIX ".so")
50+
endfunction()
4451

52+
set(TUT_MACD_DIR ${CMAKE_CURRENT_SOURCE_DIR}/macd)
53+
pineforge_tutorial_strategy(strategy_tutorial_macd
54+
${TUT_MACD_DIR}/generated.cpp
55+
${TUT_MACD_DIR}
56+
strategy)
4557
message(STATUS "tutorial: configured strategy_tutorial_macd → tutorial/macd/strategy.so")
58+
59+
set(TUT_MTF_DIR ${CMAKE_CURRENT_SOURCE_DIR}/mtf)
60+
pineforge_tutorial_strategy(strategy_tutorial_mtf_htf
61+
${TUT_MTF_DIR}/generated_htf.cpp
62+
${TUT_MTF_DIR}
63+
strategy_htf)
64+
pineforge_tutorial_strategy(strategy_tutorial_mtf_ltf
65+
${TUT_MTF_DIR}/generated_ltf.cpp
66+
${TUT_MTF_DIR}
67+
strategy_ltf)
68+
message(STATUS "tutorial: configured strategy_tutorial_mtf_htf → tutorial/mtf/strategy_htf.so")
69+
message(STATUS "tutorial: configured strategy_tutorial_mtf_ltf → tutorial/mtf/strategy_ltf.so")

‎tutorial/README.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,17 @@ tutorial/
77
├── macd/
88
│ ├── strategy.pine Pine v6 reference
99
│ └── generated.cpp compiled C++ (becomes strategy.so)
10+
├── mtf/
11+
│ ├── strategy_htf.pine HTF SMA filter via request.security
12+
│ ├── generated_htf.cpp → strategy_htf.so
13+
│ ├── strategy_ltf.pine intra-bar via request.security_lower_tf
14+
│ └── generated_ltf.cpp → strategy_ltf.so
1015
├── data/
1116
│ ├── btcusdt_15m_7d.csv 672 frozen bars (Binance)
1217
│ └── fetch_btcusdt.py refresh from Binance public API
1318
├── run.py ctypes harness + stats
1419
├── run_advanced.py parameter sweep using ABI overrides
20+
├── run_mtf.py MTF demo — script_tf switch + lower_tf
1521
├── run.sh one-shot: cmake build + run.py
1622
└── CMakeLists.txt
1723
```
@@ -100,6 +106,44 @@ docker run --rm \
100106
Both env vars are JSON `{key: value}` objects (values stringified).
101107
Empty / unset → defaults from `strategy.pine`.
102108

109+
## Multi-timeframe (MTF) demo
110+
111+
Two extra `.so` files demonstrate the runtime's two MTF surfaces:
112+
113+
- `tutorial/mtf/strategy_htf.so` — chart at 15m, HTF SMA trend filter
114+
pulled in via `request.security`. Demonstrates **upward** aggregation
115+
(input feed → coarser TF inside the strategy).
116+
- `tutorial/mtf/strategy_ltf.so` — chart at 15m (or any TF), intra-bar
117+
1m sub-bars synthesized via `request.security_lower_tf` from each
118+
chart bar's OHLC path. Demonstrates **downward** synthesis — PF's
119+
design is that the input feed's resolution is the upper bound on what
120+
the lower-TF target can be, with no separate finer feed (contrast
121+
TradingView).
122+
123+
Build and run:
124+
125+
```bash
126+
cmake --build build --target strategy_tutorial_mtf_htf strategy_tutorial_mtf_ltf -j
127+
python3 tutorial/run_mtf.py
128+
```
129+
130+
`run_mtf.py` prints three tables, each with the exact
131+
`run_backtest_full(...)` call signature above it:
132+
133+
1. **Table A** — `script_tf` sweep (`b""`, `b"15"`, `b"60"`, `b"240"`)
134+
over a fixed input feed. Shows how the same compiled `.so` reinterprets
135+
cadence per run.
136+
2. **Table B** — `(input_tf, script_tf)` pair matrix. Shows the
137+
auto-detect → defaulting → concatenation chain on resolved
138+
`input_tf_seconds` / `script_tf_seconds` / `script_tf_ratio`.
139+
3. **Table C** — lower-TF synthesis ratio at two different input TFs
140+
(`b"15"` → 15 sub-bars/bar; `b"60"` → 60 sub-bars/bar). Confirms
141+
`security_feeds_total == (input_tf_seconds / 60) * input_bars_processed`.
142+
143+
Full design notes (validation rules, codegen contract, comparison with
144+
TradingView's lower-TF model) live in
145+
[docs/pages/mtf.md](../docs/pages/mtf.md).
146+
103147
## Modify the strategy
104148

105149
`generated.cpp` is plain C++ over `<pineforge/engine.hpp>`. Edit it

0 commit comments

Comments
 (0)