Command-line interface: argument parsing, subcommands, and benchmark/evaluation orchestration. More...

Classes
struct	BenchmarkParams
	Benchmark-specific options. More...

struct	BenchmarkSuite
	A suite of scenarios with shared defaults. More...

struct	CLIOptions
	All CLI options and runtime parameters. More...

struct	ConvergenceCriteria
	Convergence criteria for adaptive stopping in benchmarks. More...

struct	ConvergenceParams
	Convergence and iteration control (evaluate + benchmark). More...

struct	EvaluateParams
	Evaluate-specific options. More...

struct	ModelParams
	Model training parameters shared by train and evaluate. More...

struct	Scenario
	A single benchmark scenario: data shape + model config. More...

struct	ScenarioResult
	Result of running a single benchmark scenario. More...

struct	SimulateParams
	Simulation data source options. More...

struct	SuiteResult
	Aggregated results for an entire suite run. More...

struct	TrainResult
	Result of a train operation containing the model and training duration. More...

struct	VarsSpec
	Result of parsing a vars specification. More...

Typedefs
using	ProgressCallback = std::function<void(int scenario_index, int total, std::string const& name)>
	Callback for progress reporting during benchmark execution.

Enumerations
enum class	Subcommand { none , train , predict , evaluate , benchmark , summarize }
	Available CLI subcommands. More...

Functions
void	add_model_options (CLI::App *sub, ModelParams &model)
	Add shared model options (size, lambda, threads, seed, vars) to `sub`.

void	init_params (CLIOptions &params, int total_vars=0)
	Resolve sentinel values in CLIOptions to concrete defaults.

CLIOptions	parse_args (int argc, char *argv[])
	Parse command-line arguments into a CLIOptions struct.

SuiteResult	parse_results (std::string const &path)
	Parse a SuiteResult from a JSON file (for baseline comparison).

BenchmarkSuite	parse_suite (nlohmann::json const &j)
	Parse a BenchmarkSuite from a JSON object.

BenchmarkSuite	parse_suite (std::string const &path)
	Parse a BenchmarkSuite from a JSON file path.

VarsSpec	parse_vars (nlohmann::json const &j)
	Parse vars from a JSON value (benchmark scenarios).

VarsSpec	parse_vars (std::string const &input)
	Parse vars from a string (CLI input).

void	print_benchmark_markdown (io::Output &out, SuiteResult const &current, std::optional< SuiteResult > const &baseline=std::nullopt)
	Print results as a GitHub-flavored markdown table.

void	print_benchmark_table (io::Output &out, SuiteResult const &current, std::optional< SuiteResult > const &baseline=std::nullopt)
	Print a formatted results table to stdout.

ppforest2::stats::DataPacket	read_data (CLIOptions const &params, ppforest2::stats::RNG &rng)
	Load or simulate data based on CLI options.

int	run_benchmark (CLIOptions &params, std::string const &binary_path)
	Run the benchmark subcommand.

int	run_evaluate (CLIOptions &params)
	Run the evaluate subcommand.

int	run_predict (CLIOptions &params)
	Run the predict subcommand.

ScenarioResult	run_scenario (Scenario const &scenario, std::string const &binary_path, bool quiet=false)
	Run a single scenario as a subprocess.

SuiteResult	run_suite (BenchmarkSuite const &suite, std::string const &binary_path, bool quiet=false, ProgressCallback progress=nullptr)
	Run all scenarios in a suite via subprocess invocations.

int	run_summarize (CLIOptions &params)
	Run the summarize subcommand.

int	run_train (CLIOptions &params)
	Run the train subcommand.

CLI::App *	setup_benchmark (CLI::App &app, CLIOptions &params)
	Register benchmark subcommand options on `app`.

CLI::App *	setup_evaluate (CLI::App &app, CLIOptions &params)
	Register evaluate subcommand options on `app`.

CLI::App *	setup_predict (CLI::App &app, CLIOptions &params)
	Register predict subcommand options on `app`.

CLI::App *	setup_summarize (CLI::App &app, CLIOptions &params)
	Register summarize subcommand options on `app`.

CLI::App *	setup_train (CLI::App &app, CLIOptions &params)
	Register train subcommand options on `app`.

TrainResult	train_model (ppforest2::types::FeatureMatrix const &x, ppforest2::types::ResponseVector const &y, CLIOptions const &params, ppforest2::stats::RNG &rng)
	Train a single model (Forest or Tree) on the given dataset.

void	warn_unused_params (io::Output &out, CLIOptions const &params)
	Warn the user about parameters that are ignored for single-tree training.

void	write_results_csv (SuiteResult const &result, std::string const &path)
	Write suite results to a CSV file.

void	write_results_json (SuiteResult const &result, std::string const &path)
	Write suite results to a JSON file.

Detailed Description

Command-line interface: argument parsing, subcommands, and benchmark/evaluation orchestration.

Typedef Documentation

◆ ProgressCallback

using ppforest2::cli::ProgressCallback = std::function<void(int scenario_index, int total, std::string const& name)>

Callback for progress reporting during benchmark execution.

Parameters

scenario_index	Current scenario index (0-based).
total	Total number of scenarios.
name	Name of the current scenario.

Enumeration Type Documentation

◆ Subcommand

enum class ppforest2::cli::Subcommand

strong

Available CLI subcommands.

Enumerator
none
train
predict
evaluate
benchmark
summarize

Function Documentation

◆ add_model_options()

void ppforest2::cli::add_model_options	(	CLI::App *	sub,
		ModelParams &	model )

Add shared model options (size, lambda, threads, seed, vars) to sub.

◆ init_params()

void ppforest2::cli::init_params	(	CLIOptions &	params,
		int	total_vars = 0 )

Resolve sentinel values in CLIOptions to concrete defaults.

Parameters

params	The CLI options to initialize (modified in place).
total_vars	Total number of feature columns (0 to skip vars resolution).

◆ parse_args()

CLIOptions ppforest2::cli::parse_args	(	int	argc,
		char *	argv[] )

Parse command-line arguments into a CLIOptions struct.

Parameters

argc	Argument count from main().
argv	Argument vector from main().

Returns: A populated CLIOptions struct.

◆ parse_results()

SuiteResult ppforest2::cli::parse_results ( std::string const & path )

Parse a SuiteResult from a JSON file (for baseline comparison).

◆ parse_suite() [1/2]

BenchmarkSuite ppforest2::cli::parse_suite ( nlohmann::json const & j )

Parse a BenchmarkSuite from a JSON object.

Exceptions

std::runtime_error on validation errors.

◆ parse_suite() [2/2]

BenchmarkSuite ppforest2::cli::parse_suite ( std::string const & path )

Parse a BenchmarkSuite from a JSON file path.

Exceptions

std::runtime_error on parse or validation errors.

◆ parse_vars() [1/2]

VarsSpec ppforest2::cli::parse_vars ( nlohmann::json const & j )

Parse vars from a JSON value (benchmark scenarios).

Formats:

JSON string: delegates to parse_vars(string)
JSON integer: count, is_proportion = false
JSON float: proportion, is_proportion = true

Exceptions

std::runtime_error on invalid input.

◆ parse_vars() [2/2]

VarsSpec ppforest2::cli::parse_vars ( std::string const & input )

Parse vars from a string (CLI input).

Formats:

"1/3" → fraction, is_proportion = true, value = 0.333...
"0.5" → decimal, is_proportion = true, value = 0.5
"5" → count, is_proportion = false, value = 5

Exceptions

std::runtime_error on invalid input.

◆ print_benchmark_markdown()

void ppforest2::cli::print_benchmark_markdown	(	io::Output &	out,
		SuiteResult const &	current,
		std::optional< SuiteResult > const &	baseline = std::nullopt )

Print results as a GitHub-flavored markdown table.

Prints directly via Output (no indentation). Suitable for piping to a file or posting as a PR comment. With a baseline, includes delta columns with emoji indicators.

Parameters

out	Output context.
current	Results from the current run.
baseline	Optional baseline results for comparison.

◆ print_benchmark_table()

void ppforest2::cli::print_benchmark_table	(	io::Output &	out,
		SuiteResult const &	current,
		std::optional< SuiteResult > const &	baseline = std::nullopt )

Print a formatted results table to stdout.

Without a baseline, prints absolute numbers. With a baseline, adds delta columns (green = faster/less memory, red = slower/more memory).

Parameters

out	Output context.
current	Results from the current run.
baseline	Optional baseline results for comparison.

◆ read_data()

ppforest2::stats::DataPacket ppforest2::cli::read_data	(	CLIOptions const &	params,
		ppforest2::stats::RNG &	rng )

Load or simulate data based on CLI options.

If data_path is set, reads a CSV file; otherwise generates simulated data. Ensures the response vector is contiguous (sorted by group).

◆ run_benchmark()

int ppforest2::cli::run_benchmark	(	CLIOptions &	params,
		std::string const &	binary_path )

Run the benchmark subcommand.

Parameters

params	CLI options.
binary_path	Path to the ppforest2 binary (typically argv[0]).

Returns: Exit code.

◆ run_evaluate()

int ppforest2::cli::run_evaluate ( CLIOptions & params )

Run the evaluate subcommand.

Returns: Exit code (0 on success).

◆ run_predict()

int ppforest2::cli::run_predict ( CLIOptions & params )

Run the predict subcommand.

Returns: Exit code (0 on success).

◆ run_scenario()

ScenarioResult ppforest2::cli::run_scenario	(	Scenario const &	scenario,
		std::string const &	binary_path,
		bool	quiet = false )

Run a single scenario as a subprocess.

◆ run_suite()

SuiteResult ppforest2::cli::run_suite	(	BenchmarkSuite const &	suite,
		std::string const &	binary_path,
		bool	quiet = false,
		ProgressCallback	progress = nullptr )

Run all scenarios in a suite via subprocess invocations.

For each scenario, spawns ppforest2 evaluate as a child process with the appropriate flags, reads its JSON output, and collects results.

Parameters

suite	The benchmark suite to run.
binary_path	Path to the ppforest2 binary (typically argv[0]).
quiet	Suppress progress output.
progress	Optional progress callback.

Returns: Aggregated suite results.

◆ run_summarize()

int ppforest2::cli::run_summarize ( CLIOptions & params )

Run the summarize subcommand.

Returns: Exit code (0 on success).

◆ run_train()

int ppforest2::cli::run_train ( CLIOptions & params )

Run the train subcommand.

Returns: Exit code (0 on success).

◆ setup_benchmark()

CLI::App * ppforest2::cli::setup_benchmark	(	CLI::App &	app,
		CLIOptions &	params )

Register benchmark subcommand options on app.

◆ setup_evaluate()

CLI::App * ppforest2::cli::setup_evaluate	(	CLI::App &	app,
		CLIOptions &	params )

Register evaluate subcommand options on app.

◆ setup_predict()

CLI::App * ppforest2::cli::setup_predict	(	CLI::App &	app,
		CLIOptions &	params )

Register predict subcommand options on app.

◆ setup_summarize()

CLI::App * ppforest2::cli::setup_summarize	(	CLI::App &	app,
		CLIOptions &	params )

Register summarize subcommand options on app.

◆ setup_train()

CLI::App * ppforest2::cli::setup_train	(	CLI::App &	app,
		CLIOptions &	params )

Register train subcommand options on app.

◆ train_model()

TrainResult ppforest2::cli::train_model	(	ppforest2::types::FeatureMatrix const &	x,
		ppforest2::types::ResponseVector const &	y,
		CLIOptions const &	params,
		ppforest2::stats::RNG &	rng )

Train a single model (Forest or Tree) on the given dataset.

◆ warn_unused_params()

void ppforest2::cli::warn_unused_params	(	io::Output &	out,
		CLIOptions const &	params )

Warn the user about parameters that are ignored for single-tree training.

◆ write_results_csv()

void ppforest2::cli::write_results_csv	(	SuiteResult const &	result,
		std::string const &	path )

Write suite results to a CSV file.

◆ write_results_json()

void ppforest2::cli::write_results_json	(	SuiteResult const &	result,
		std::string const &	path )

Write suite results to a JSON file.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ProgressCallback

Enumeration Type Documentation

◆ Subcommand

Function Documentation

◆ add_model_options()

◆ init_params()

◆ parse_args()

◆ parse_results()

◆ parse_suite() [1/2]

◆ parse_suite() [2/2]

◆ parse_vars() [1/2]

◆ parse_vars() [2/2]

◆ print_benchmark_markdown()

◆ print_benchmark_table()

◆ read_data()

◆ run_benchmark()

◆ run_evaluate()

◆ run_predict()

◆ run_scenario()

◆ run_suite()

◆ run_summarize()

◆ run_train()

◆ setup_benchmark()

◆ setup_evaluate()

◆ setup_predict()

◆ setup_summarize()

◆ setup_train()

◆ train_model()

◆ warn_unused_params()

◆ write_results_csv()

◆ write_results_json()