fastmm::bt Namespace Reference

Classes
struct	ArrayColumns
class	ArraySource
struct	BacktestConfig
struct	BacktestResult
class	BacktestRunner
	Convenience wrapper that owns the config. More...
class	BacktestSession
struct	BacktestTreasury
	The pool treasuries of a run ([venues. More...
class	ChainSource
	Concatenation of sources that cover consecutive spans of time (one file per day). More...
class	CsvSource
struct	EquityRows
struct	FillQuality
	Diagnostics of how the fills were obtained, next to the markouts. More...
struct	FillRows
struct	InstrumentEquityRows
	One instrument's columns of EquityRows, one row per bar. More...
struct	JournalInfo
class	JournalSource
struct	LiveAnalysis
struct	LiveAnalysisInstrument
struct	MarkoutBucket
struct	MarkoutHorizon
	Buckets of one horizon, all over the same measured fills. More...
class	MergedSource
	k-way merge of several sources by event time (stable: lower source index first on ties). More...
struct	Metrics
struct	MetricsInputs
struct	OrderRows
class	OwnedMergedSource
	MergedSource over sources it owns: open_data() of several specs ("a; b"), one per venue. More...
struct	PnlDecomposition
	How the net PnL of the run splits into the parts a market maker can act on: net == spread_capture + mid_drift - fees_paid + rebates_received + residual mid_drift is the move of the mid from each fill to the end of the run, valued at the signed quantity of the fill: adverse selection plus the mark-to-market of whatever is still open. More...
struct	ReplayOptions
struct	ReplayResult
struct	ReplayStrategy
	A strategy outside the registry (a Python hot strategy): the name for the result, the parameter schema that ParamUpdate fields are matched against, and a factory that builds the runner on the sim::ReplayBackend that deps.backend points at. More...
struct	Row
class	RowAssembler
	Builds messages from a row stream. Provider is bool(Row&) returning false at end. More...
struct	SlowMethodTiming
	Wall time of one slow method of a Python strategy over a backtest. More...
struct	SweepPoint
class	SyntheticSource
struct	SyntheticSourceConfig
class	TimeSliceSource
	The events of inner in [t0, t1) of event time (exch_ts, recv_ts when unset), for walk-forward folds. More...
struct	WalkForwardFold
struct	WalkForwardReport

Concepts
concept	DataSourceLike

Typedefs
using	ParamGrid = std::vector< std::pair< std::string, std::vector< std::string > > >
using	SourceFactory = std::function< std::unique_ptr< MdSource >()>
	may return nullptr
using	RunFn = std::function< BacktestResult(const BacktestConfig &, MdSource *)>
using	ScoreFn = double(*)(const BacktestResult &)
	Ranking metric of a run, higher is better: "net_pnl", "realized_pnl", "sharpe_bar" or "spread_captured_bps".

Enumerations
enum class	InitialState : std::uint8_t { StateFile = 0 , Journal = 1 , None = 2 }
	Where the strategy's starting state comes from ([backtest] initial_state). More...
enum class	RowType : std::uint8_t { Snapshot = 0 , Delta = 1 , Trade = 2 , Ticker = 3 }

Functions
template<StrategyLike S>
BacktestResult	run_backtest (const BacktestConfig &cfg, MdSource *source=nullptr)
BacktestResult	run_backtest (const BacktestConfig &cfg, std::string_view strategy, MdSource *source=nullptr)
	Registry path (registers the built-in strategies first).
SyntheticSourceConfig	synthetic_source_config (const BacktestConfig &cfg)
	The SyntheticSource a run with source == nullptr replays under the L2 queue fill model.
std::unique_ptr< MdSource >	open_data (std::string_view spec, const InstrumentTable *instruments=nullptr)
	Resolves --data through the data-source registry (data_registry.hpp): "\<name\>:\<args\>", or a bare *.fmj / *.csv path.
std::unique_ptr< MdSource >	open_source (const BacktestConfig &cfg)
	Source for [backtest] source / path.
Metrics	compute_metrics (const EquityRows &equity, const FillRows &fills, const OrderRows &orders, const MetricsInputs &in)
LiveAnalysis	analyze_live (const std::string &path, std::span< const std::int64_t > horizons_ns)
	Throws std::runtime_error when the journal cannot be read.
std::string	format_live_analysis (const LiveAnalysis &a)
std::string	live_analysis_json (const LiveAnalysis &a)
std::vector< ParamMap >	expand_grid (const ParamGrid &grid)
	Expands the grid in order: [{k1: v11, k2: v21}, {k1: v11, k2: v22}, ...].
std::vector< SweepPoint >	sweep (const BacktestConfig &base, const ParamGrid &grid, const SourceFactory &source_factory, const RunFn &run, int threads=0)
	Generic driver; run is called once per point on a worker thread.
template<StrategyLike S>
std::vector< SweepPoint >	sweep (const BacktestConfig &base, const ParamGrid &grid, const SourceFactory &source_factory={}, int threads=0)
std::vector< SweepPoint >	sweep_by_name (const BacktestConfig &base, std::string strategy, const ParamGrid &grid, const SourceFactory &source_factory={}, int threads=0)
ScoreFn	score_metric (std::string_view name)
WalkForwardReport	walk_forward (const BacktestConfig &base, const ParamGrid &grid, const SourceFactory &source_factory, const RunFn &run, int folds, std::string_view metric="net_pnl", int threads=0)
	Splits the data's event-time range into folds equal slices and runs the whole grid on each one (a fresh backtest per point and fold, all on one pool of threads workers).
WalkForwardReport	walk_forward_by_name (const BacktestConfig &base, std::string strategy, const ParamGrid &grid, const SourceFactory &source_factory, int folds, std::string_view metric="net_pnl", int threads=0)
JournalInfo	inspect_journal (const std::string &path)
	Throws std::runtime_error when the file cannot be opened / validated.
BacktestConfig	journal_config (const std::string &path)
	The configuration embedded in the journal.
std::string	describe_outbound (const EventHeader &h)
	One-line description of an Out* message (type, ids, side, price, quantity, stamp).
ReplayResult	replay_journal (const std::string &path, const BacktestConfig &cfg, const ReplayOptions &opt={})
	cfg supplies the engine configuration and strategy parameters (it must match the recording run for a verifying replay); the instrument table is taken from the journal.
ReplayResult	replay_journal (const std::string &path, const BacktestConfig &cfg, const ReplayOptions &opt, const ReplayStrategy &strategy)
	Replays strategy instead of a registered one (opt.strategy is ignored).
ReplayResult	replay_journal (const std::string &path, const ReplayOptions &opt={})
	Replays with the journal's embedded configuration (journal_config(path)).
std::uint64_t	write_md_journal (MdSource &source, const std::string &path, const InstrumentTable &instruments, std::uint64_t seed, std::string_view strategy="data", std::uint64_t max_events=0)
	Writes the events of source (all, or the first max_events when non-zero) to a fresh .fmj with JournalFileWriter (instrument table + header stamped with seed); used to produce fixtures.

Variables
constexpr std::uint8_t	kOrderKindNew = 0
constexpr std::uint8_t	kOrderKindCancel = 1
constexpr std::uint8_t	kOrderKindReplace = 2
constexpr double	kMinAnnualizedDurationS = 86400.0
	Shortest run whose Sharpe ratio is annualised: one day.
constexpr std::int64_t	kDefaultMarkoutHorizonsNs []
	Horizons measured by default, in simulated time.

Typedef Documentation

ParamGrid

using fastmm::bt::ParamGrid = typedef std::vector<std::pair<std::string, std::vector<std::string> >>

SourceFactory

using fastmm::bt::SourceFactory = typedef std::function<std::unique_ptr<MdSource>()>

may return nullptr

RunFn

using fastmm::bt::RunFn = typedef std::function<BacktestResult(const BacktestConfig&, MdSource*)>

ScoreFn

using fastmm::bt::ScoreFn = typedef double (*)(const BacktestResult&)

Ranking metric of a run, higher is better: "net_pnl", "realized_pnl", "sharpe_bar" or "spread_captured_bps".

Throws std::invalid_argument for any other name.

Enumeration Type Documentation

InitialState

enum class fastmm::bt::InitialState : std::uint8_t

strong

Where the strategy's starting state comes from ([backtest] initial_state).

Enumerator
StateFile	[strategy] state_file, when set
Journal	the data journal's (journal_state.hpp), with the session's positions
None	nothing: the strategy starts fresh

RowType

enum class fastmm::bt::RowType : std::uint8_t

strong

Enumerator
Snapshot
Delta
Trade
Ticker

Function Documentation

run_backtest() [1/2]

template<StrategyLike S>

BacktestResult fastmm::bt::run_backtest	(	const BacktestConfig &	cfg,
		MdSource *	source = nullptr
	)

run_backtest() [2/2]

BacktestResult fastmm::bt::run_backtest	(	const BacktestConfig &	cfg,
		std::string_view	strategy,
		MdSource *	source = nullptr
	)

Registry path (registers the built-in strategies first).

Throws std::invalid_argument for an unknown strategy or bad parameters.

synthetic_source_config()

SyntheticSourceConfig fastmm::bt::synthetic_source_config

(

const BacktestConfig &

cfg

)

The SyntheticSource a run with source == nullptr replays under the L2 queue fill model.

open_data()

std::unique_ptr< MdSource > fastmm::bt::open_data	(	std::string_view	spec,
		const InstrumentTable *	instruments = nullptr
	)

Resolves --data through the data-source registry (data_registry.hpp): "\<name\>:\<args\>", or a bare *.fmj / *.csv path.

"synthetic" (and "") open to nullptr, which selects the market generator. instruments lets a source map its symbols onto instrument ids; it may be null. Throws std::runtime_error for an unknown source, bad options or unreadable files.

open_source()

std::unique_ptr< MdSource > fastmm::bt::open_source

(

const BacktestConfig &

cfg

)

Source for [backtest] source / path.

source is a whole spec ("binance:BTCUSDT:2024-03-27"); a bare name plus path ("journal" + "x.fmj") is the same thing written as two keys.

compute_metrics()

Metrics fastmm::bt::compute_metrics	(	const EquityRows &	equity,
		const FillRows &	fills,
		const OrderRows &	orders,
		const MetricsInputs &	in
	)

analyze_live()

LiveAnalysis fastmm::bt::analyze_live	(	const std::string &	path,
		std::span< const std::int64_t >	horizons_ns
	)

Throws std::runtime_error when the journal cannot be read.

format_live_analysis()

std::string fastmm::bt::format_live_analysis

(

const LiveAnalysis &

a

)

live_analysis_json()

std::string fastmm::bt::live_analysis_json

(

const LiveAnalysis &

a

)

expand_grid()

std::vector< ParamMap > fastmm::bt::expand_grid

(

const ParamGrid &

grid

)

Expands the grid in order: [{k1: v11, k2: v21}, {k1: v11, k2: v22}, ...].

sweep() [1/2]

std::vector< SweepPoint > fastmm::bt::sweep	(	const BacktestConfig &	base,
		const ParamGrid &	grid,
		const SourceFactory &	source_factory,
		const RunFn &	run,
		int	threads = 0
	)

Generic driver; run is called once per point on a worker thread.

threads <= 0 uses hardware_concurrency.

sweep() [2/2]

template<StrategyLike S>

std::vector< SweepPoint > fastmm::bt::sweep	(	const BacktestConfig &	base,
		const ParamGrid &	grid,
		const SourceFactory &	source_factory = {},
		int	threads = 0
	)

sweep_by_name()

std::vector< SweepPoint > fastmm::bt::sweep_by_name ( const BacktestConfig &  base, std::string  strategy, const ParamGrid &  grid, const SourceFactory &  source_factory = {}, int  threads = 0  )

inline

score_metric()

ScoreFn fastmm::bt::score_metric

(

std::string_view

name

)

walk_forward()

WalkForwardReport fastmm::bt::walk_forward	(	const BacktestConfig &	base,
		const ParamGrid &	grid,
		const SourceFactory &	source_factory,
		const RunFn &	run,
		int	folds,
		std::string_view	metric = "net_pnl",
		int	threads = 0
	)

Splits the data's event-time range into folds equal slices and runs the whole grid on each one (a fresh backtest per point and fold, all on one pool of threads workers).

Each fold reads a TimeSliceSource over the worker's cursor, so it starts on the book as of its first instant with a flat engine. folds == 1 is exactly sweep(). The synthetic market (source_factory empty or returning nullptr) is sliced as a SyntheticSource stream, which needs fill_model l2_queue: the coupled matching market cannot be cut and throws std::invalid_argument.

walk_forward_by_name()

WalkForwardReport fastmm::bt::walk_forward_by_name ( const BacktestConfig &  base, std::string  strategy, const ParamGrid &  grid, const SourceFactory &  source_factory, int  folds, std::string_view  metric = "net_pnl", int  threads = 0  )

inline

inspect_journal()

JournalInfo fastmm::bt::inspect_journal

(

const std::string &

path

)

Throws std::runtime_error when the file cannot be opened / validated.

journal_config()

BacktestConfig fastmm::bt::journal_config

(

const std::string &

path

)

The configuration embedded in the journal.

Throws std::runtime_error when there is none (v1 journals, market-data journals, hand-built backtest configurations) or it does not parse.

describe_outbound()

std::string fastmm::bt::describe_outbound

(

const EventHeader &

h

)

One-line description of an Out* message (type, ids, side, price, quantity, stamp).

replay_journal() [1/3]

ReplayResult fastmm::bt::replay_journal	(	const std::string &	path,
		const BacktestConfig &	cfg,
		const ReplayOptions &	opt = {}
	)

cfg supplies the engine configuration and strategy parameters (it must match the recording run for a verifying replay); the instrument table is taken from the journal.

Throws std::runtime_error / std::invalid_argument on unreadable journals or unknown strategies.

replay_journal() [2/3]

ReplayResult fastmm::bt::replay_journal	(	const std::string &	path,
		const BacktestConfig &	cfg,
		const ReplayOptions &	opt,
		const ReplayStrategy &	strategy
	)

Replays strategy instead of a registered one (opt.strategy is ignored).

replay_journal() [3/3]

ReplayResult fastmm::bt::replay_journal	(	const std::string &	path,
		const ReplayOptions &	opt = {}
	)

Replays with the journal's embedded configuration (journal_config(path)).

write_md_journal()

std::uint64_t fastmm::bt::write_md_journal	(	MdSource &	source,
		const std::string &	path,
		const InstrumentTable &	instruments,
		std::uint64_t	seed,
		std::string_view	strategy = "data",
		std::uint64_t	max_events = 0
	)

Writes the events of source (all, or the first max_events when non-zero) to a fresh .fmj with JournalFileWriter (instrument table + header stamped with seed); used to produce fixtures.

Returns the number of events written.

Variable Documentation

kOrderKindNew

constexpr std::uint8_t fastmm::bt::kOrderKindNew = 0

inlineconstexpr

kOrderKindCancel

constexpr std::uint8_t fastmm::bt::kOrderKindCancel = 1

inlineconstexpr

kOrderKindReplace

constexpr std::uint8_t fastmm::bt::kOrderKindReplace = 2

inlineconstexpr

kMinAnnualizedDurationS

constexpr double fastmm::bt::kMinAnnualizedDurationS = 86400.0

inlineconstexpr

Shortest run whose Sharpe ratio is annualised: one day.

kDefaultMarkoutHorizonsNs

constexpr std::int64_t fastmm::bt::kDefaultMarkoutHorizonsNs[]

inlineconstexpr

Initial value:

= {
    1'000'000'000LL, 10'000'000'000LL, 60'000'000'000LL}

Horizons measured by default, in simulated time.