All docs pages

Docs · Getting started

Reamer Research for C++

Adapted from cpp/README.md in the 4.11.3 Reamer Research kit.

One header, include/reamer_research.hpp (also in the kit's include/), over the Reamer Research C ABI. Include it, link libreamer_research, compile as C++20. There is nothing to build first.

#include <reamer_research.hpp>
#include <algorithm>
#include <iostream>
namespace rr = reamer_research;

int main() {
  auto r = rr::backtest([](rr::Data& d) {
    auto c = d.close(), h = d.high(), l = d.low();
    if (c[0] == 0) return;                // warm-up: the window is still filling
    double atr = 0;
    for (size_t i = 1; i < c.size(); ++i)
      atr += std::max(h[i], c[i - 1]) - std::min(l[i], c[i - 1]);
    atr /= double(c.size() - 1);
    double mid = c.mean(), px = c.back();
    if (d.position() == 0 && px < mid - 2 * atr) d.buy_market(10).bracket(mid, px - 2 * atr);
    if (d.position() == 0 && px > mid + 2 * atr) d.sell_market(10).bracket(mid, px + 2 * atr);
  }, "AAPL.csv", {.lookback = 20, .open_viewer = true});
  std::cout << r << '\n';
}

That is a complete program, an ATR band reversion: it fades a close more than two ATRs from its 20-bar mean, with a bracket that targets the mean and stops two ATRs further out. It reads the CSV, runs the strategy, prints the summary and opens the run in the visual trade diagnostics tool (viewer/README.md). It is examples/quickstart.cpp.

EXECUTION_SPEC.md (kit root) is authoritative on fill, slippage, spread, commission and margin behaviour. include/reamer_research_abi.h is the ABI contract. This header is part of the licensed product, supported like the library, and ships in source (LICENSE.txt, Section 4): read it, change it, keep it in your own tree.

Building

From the kit root, any of three ways.

By hand

c++ -std=c++20 -O2 run.cpp -Iinclude -Llib -lreamer_research -Wl,-rpath,"$PWD/lib" -o run

CMake (Linux and macOS)

find_package(ReamerResearch 4 REQUIRED)
target_link_libraries(run PRIVATE ReamerResearch::reamer_research)
cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/research-kit

The target carries the include path, C++20 and the library's location.

pkg-config (Linux and macOS)

export PKG_CONFIG_PATH=/path/to/research-kit/lib/pkgconfig
c++ run.cpp $(pkg-config --cflags --libs reamer-research) -o run

Each route sets an rpath, so the program finds the library at run time. The trade diagnostics page is found next to the library, at <kit>/viewer/reamer-viewer.html; set REAMER_VIEWER_HTML to use another copy. On a machine with no desktop (SSH, a server) path of the diagnostics page is printed and no browser is started.

The header needs a C++20 compiler and the standard library, nothing else.

Strategies

A strategy is a lambda or function taking rr::Data&, or an object with on_bar(rr::Data&). An object may also carry lookback (bars per window) and on_progress(done, total) (return true to stop the run). An exception thrown in either stops the run and is rethrown from backtest().

struct Breakout {
  size_t lookback = 20;
  void on_bar(rr::Data& d) {
    double close = d.close().back();
    if (d.position() == 0 && close >= d.high().max())
      d.buy_market(100).bracket(close * 1.04, d.low().min());
  }
};

auto r = rr::backtest(Breakout{}, "SPY.bin");

Orders are placed by calling methods on Data: buy_market(qty), sell_market(qty), buy_limit(price, qty), sell_limit, buy_stop(price, qty), sell_stop, close_position(qty = 0) (0 closes all of it) and cancel(order_id). Each returns the order just placed, so brackets and time in force chain on: .take_profit(p), .stop_loss(p), .bracket(tp, sl), .gtc(), .ioc(), .gtd("2024-06-30 16:00:00"). Actions on what is already open: modify_order(id, price, tp, sl), modify_position(tp, sl), close_all() and cancel_all(). An order placed on a bar is eligible from the next bar (EXECUTION_SPEC.md §6).

What on_bar reads:

Call Returns
d.close(), open(), high(), low(), volume() A column over the window. back() or ago(0) is the current bar, ago(1) the one before, [0] the oldest. sum(n), mean(n), max(n) and min(n) cover the last n bars, or the whole window when n is 0.
d.bar(ago) One whole bar: ts, open, high, low, close, volume, notional.
d.ts() The current step's time, epoch seconds UTC.
d.position() Signed position after this bar's fills: positive long, negative short, 0 flat.
d.position_state() Size, average entry price, the attached brackets, unrealised P&L and entry time.
d.open_orders(), d.action_results() Resting orders with their ids, and how the previous bar's actions went.
d.exogenous() The latest value of the ticker's exogenous sidecar at or before this bar, if there is one.

Several tickers

Pass several files, or a rr::Universe of in-memory bars. Each ticker is named after its file (AAPL.csv is "AAPL"), and every call then names one: d["AAPL"].close(), d.position("AAPL"), d.buy_market(10, "AAPL"), d.close_position("AAPL"). One wall clock runs the backtest and every row of every ticker is an event on it, so rows never need to line up. d["AAPL"].fresh() says whether that ticker's row closed at this step or was carried forward.

auto r = rr::backtest([](rr::Data& d) {
  for (const auto& name : d.names()) {
    auto t = d[name];
    if (t.fresh() && t.position() == 0 && t.close().back() > t.close().mean())
      d.buy_market(1, name);
  }
}, {"AAPL.csv", "MSFT.csv"}, {.lookback = 50});

Data

backtest() takes a .csv or .bin path, a list of paths, or bars in memory (rr::Bars, a std::vector<ReamerOhlcvBar>). When every path is a .bin file, the files are memory-mapped, so data larger than RAM runs (DEPLOYMENT.md, "Run from .bin files").

  • rr::load_csv(path) reads a CSV with a header row: a time or date column (plus an optional separate time column), open, high, low, close, and optionally volume. Header names are matched loosely (Date, <CLOSE>, Timestamp), so MetaTrader exports work as saved. Timestamps may be date strings, read as UTC, or epoch seconds, milliseconds, microseconds or nanoseconds. Rows are sorted by time.
  • rr::write_bin(path, bars) and rr::read_bin(path) write and read .bin files, the same files bin/reamer-csv-build makes.
  • rr::write_exogenous(path, {{ts, "value"}, ...}) writes an exogenous sidecar (EXOGENOUS_FORMAT.md). Pass it to a run as .exogenous = {{"AAPL", "aapl.exo.bin"}}.

Getting data in

rr::backtest(strategy, "AAPL.csv");                            // a CSV, ticker AAPL
rr::backtest(strategy, "AAPL.bin");                            // memory-mapped
rr::backtest(strategy, rr::Universe{{"AAPL", bars}});          // rr::Bars you built or loaded
rr::backtest(strategy, rr::Universe{{"AAPL", rr::parse_csv(text)}});  // CSV text already in memory

From a vendor, the Python fetchers in python/fetchers/ (Alpaca, Databento) download the bars and rr.write_bin saves them as a .bin, which C++ loads unchanged. Convert once, then every C++ run memory-maps the file:

cd python      # where fetchers/ is
python3 -c "import reamer_research as rr; from fetchers.alpaca_bars import fetch_alpaca_crypto; \
  rr.write_bin('BTC.bin', fetch_alpaca_crypto(['BTC/USD'], '1Hour', '2025-01-01', '2025-01-29')['BTC/USD'])"
cd .. && ./my_strategy python/BTC.bin

bin/reamer-csv-build makes the same .bin from a CSV on the command line. Anything else, from a database, a vendor SDK or your own capture, fills an rr::Bars (ts in epoch seconds UTC, open, high, low, close, volume, and tick_count = -1 when you have no tick count) and passes it as above. examples/data_csv.cpp and examples/data_bin.cpp run each path on the sample bars, with the same result as their Python twins.

Options

Every field has a default, so name only what differs:

auto r = rr::backtest(strategy, "ES.bin", {
  .lookback = 30,
  .initial_capital = 100000,
  .leverage = 2,
  .costs = {.commission_per_unit = 2.5, .slippage = 0.25, .spread = 0.25},
  .rng_seed = 7,
  .start = 1704067200,          // epoch seconds UTC, inclusive
  .result_json = "es.json",
  .open_viewer = true,
});

costs is the execution config from EXECUTION_SPEC.md §0a: commission and its mode, slippage, price_volatility, spread, bid, ask or mid data, swap by weekday and the roll cycle. ticker_costs overrides it for named tickers. Designated initialisers must keep declaration order: lookback, initial_capital, leverage, costs, rng_seed, ticker_costs, exogenous, start, end, periods_per_year, on_progress, result_json, viewer_html, open_viewer.

Results

backtest() returns an rr::Result, and std::cout << r prints its summary.

  • r.summary() is the full ReamerBacktestSummary: P&L, fees, slippage, swap, win rate, profit factor, Sharpe, Sortino, drawdown and trade counts. r.net_pnl() is the headline.
  • r.closed_trades() returns every round trip, however many there are.
  • r.json() is the full result document (RESULT_JSON_SCHEMA.md: orders, fills, trades, equity curve), and r.write_json(path) saves it.
  • r.monte_carlo(simulations, seed) resamples the closed trades and returns the distribution of outcomes.
  • r.write_viewer(path) writes the trade diagnostics page with this run in it. .open_viewer and .viewer_html do the same as part of the run.
  • r.handle() is the raw ReamerBacktestHandle, for any ABI call the wrapper does not cover.

Failures throw rr::Error: code() is the ReamerResearchErrorCode and what() the library's own message. A backtest past an Evaluation Mode limit, or the relay without a licence, throws rr::EvaluationLimit (an rr::Error), whose what() names the limit and https://reamerlabs.com/pricing.

Live orders

rr::Relay sends the same orders a backtest places to a receiver of your own over the published relay protocol (the relay section of include/reamer_research_abi.h). Linux and macOS. Live trading with Reamer Research covers going live, with a working receiver and paper broker.

rr::Relay relay("/run/reamer/strategy.sock", {"AAPL"});
std::vector<uint64_t> ids = relay.send(rr::buy_market(10).stop_loss(180));  // {1}
relay.poll(500);
relay.send(rr::modify_position(0, 185));   // actions: modify_order, modify_position, close_all, cancel_all

send() checks every order and action by the backtest's rules before it sends any, and returns the IDs of the orders it sent. positions() reads the fills back, one PositionState per ticker.

Paper trading

live/live_paper.cpp runs the quickstart's rule live against a paper broker: it replays a CSV one closed bar at a time, sends each order through rr::Relay, and prints each order and the position the fills leave. The receiver is python/live/relay_receiver.py, standard library only, which the program starts for you; for real orders, put your broker's API behind the receiver in place of its PaperBroker.

c++ -std=c++20 -O2 cpp/live/live_paper.cpp -Iinclude \
    -Llib -lreamer_research -Wl,-rpath,"$PWD/lib" -o live_paper
./live_paper                       # replays python/sample_data/SAMPLE_5min.csv

A live feed calls the same per-bar step with each bar as it closes. The relay needs a licence: Evaluation Mode has no live trading. The steps and the wire format are in Live trading with Reamer Research.

Examples

The programs in examples/ run on python/sample_data/SAMPLE_5min.csv when given no file, so all of them run in Evaluation Mode, and ./example your.csv runs one on your own bars. Between them they use all three strategy forms.

  • quickstart.cpp: ATR band reversion with a bracket on every entry, as a lambda, and with --object as an object with on_bar. The same rule as python/examples/quickstart.py, with the same result.
  • atr_stop_bracket.cpp: a buy stop and a sell stop spaced by ATR, the buy with a bracket, as an object. The same as python/examples/atr_stop_bracket.py.
  • donchian_breakout.cpp: a GTD buy stop at the 20-bar high and a stop loss trailed to the 10-bar low with modify_position, as a function.
  • buy_and_hold.cpp: one buy, held to the end of the run.
  • rejected_orders.cpp: submits malformed orders and reads the rejections back from the order log. A run whose orders were all rejected still succeeds; only the order log shows what the engine refused.
  • data_csv.cpp, data_bin.cpp: getting data in, above.
  • live/live_paper.cpp: paper trading through the relay, above. Needs a licence.

Build any of them as shown under Building.

The 4.x wrapper

The same header keeps the earlier wrapper in namespace reamer_research_ref, so code written against it compiles unchanged: run_backtest(bars_by_ticker, ticker_names, on_bar, config, capital, leverage) with a raw on_bar(window, ticker_count, positions, window_valid, out_orders) callback, returning std::optional<BacktestResult>. Its closed_trades() is no longer capped at 4,096 trades.

Overhead

The views on_bar reads are borrowed pointers into the engine's window, so no bar is copied; the wrapper adds a trampoline call per bar.

License

Provided under the terms of the Reamer Research licence, LICENSE.txt in the kit.

Buy a licenceKey and kit by email on payment.