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

Namespaces
namespace	serve

Classes
struct	Baseline
	A baseline suite with a pre-built name → result index. More...

struct	BenchmarkParams
	Benchmark-specific options. More...

struct	BenchmarkReport
	Benchmark report with comparison, display, and export. More...

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

struct	EvaluateParams
	Evaluate and convergence options (shared by evaluate + benchmark). More...

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

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

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

struct	ServeParams
	`serve` subcommand options. CLI-exclusive; no config file roundtrip. 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...

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

Functions
void	add_evaluate_options (CLI::App *sub, EvaluateParams &evaluate)
	Add evaluate/convergence options shared by evaluate and benchmark.

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

void	check (bool condition, std::string const &message, std::vector< std::string > &errors)
	Collects validation errors grouped by label.

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

float	parse_proportion (nlohmann::json const &j)

float	parse_proportion (std::string const &input)
	Parse a proportion from a string or JSON value.

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.

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

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

int	run_predict (Params const &params)
	Run the predict subcommand.

ScenarioResult	run_scenario (nlohmann::json const &scenario, std::string const &binary_path)
	Run a single scenario as a subprocess.

int	run_serve (Params const &params)
	Run the serve subcommand.

SuiteResult	run_suite (BenchmarkSuite const &suite, std::string const &binary_path, io::Output &out)
	Run all scenarios in a suite via subprocess invocations.

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

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

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

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

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

void	setup_serve (CLI::App &app, Params &params)
	Register serve subcommand options on `app`.

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

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

nlohmann::json	strategy_string_to_json (std::string const &input)
	Parse a CLI strategy string into a JSON object.

TrainResult	train_model (ppforest2::types::FeatureMatrix const &x, ppforest2::types::OutcomeVector const &y, Params const &params)
	Train a single model (Forest or Tree) on the given dataset.

nlohmann::json	training_defaults ()
	Default values for shared training parameters.

void	validate_params (Params const &params)
	Validate training-related params and throw on errors.

void	validate_training_config (nlohmann::json const &config, std::vector< std::string > &errors)
	Validate a training config JSON.

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

Detailed Description

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

Enumeration Type Documentation

◆ Subcommand

enum class ppforest2::cli::Subcommand : uint8_t

strong

Available CLI subcommands.

Enumerator
none
train
predict
evaluate
benchmark
summarize
serve

Function Documentation

◆ add_evaluate_options()

void ppforest2::cli::add_evaluate_options	(	CLI::App *	sub,
		EvaluateParams &	evaluate )

Add evaluate/convergence options shared by evaluate and benchmark.

◆ 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.

◆ check()

void ppforest2::cli::check	(	bool	condition,
		std::string const &	message,
		std::vector< std::string > &	errors )

inline

Collects validation errors grouped by label.

Use begin() to start a new group (e.g., a scenario name), then pass errors() to validation functions that append to a std::vector<std::string>&.

Append an error message if condition is false.

◆ parse_args()

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

Parse command-line arguments into a Params struct.

Parameters

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

Returns: A populated Params struct.

◆ parse_proportion() [1/2]

float ppforest2::cli::parse_proportion ( nlohmann::json const & j )

◆ parse_proportion() [2/2]

float ppforest2::cli::parse_proportion ( std::string const & input )

Parse a proportion from a string or JSON value.

Formats:

String: "1/3", "0.5"
JSON string: "1/3", "0.5"
JSON number: 0.5, 1.0

Returns: A value in (0, 1].

Exceptions

UserError on invalid input.

◆ parse_suite() [1/2]

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

Parse a BenchmarkSuite from a JSON object.

Exceptions

UserError 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

UserError on parse or validation errors.

◆ run_benchmark()

int ppforest2::cli::run_benchmark	(	Params const &	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 ( Params & params )

Run the evaluate subcommand.

Returns: Exit code (0 on success).

◆ run_predict()

int ppforest2::cli::run_predict ( Params const & params )

Run the predict subcommand.

Returns: Exit code (0 on success).

◆ run_scenario()

ScenarioResult ppforest2::cli::run_scenario	(	nlohmann::json const &	scenario,
		std::string const &	binary_path )

Run a single scenario as a subprocess.

◆ run_serve()

int ppforest2::cli::run_serve ( Params const & params )

Run the serve subcommand.

Returns: Exit code (0 on graceful shutdown, non-zero on bind failure).

◆ run_suite()

SuiteResult ppforest2::cli::run_suite	(	BenchmarkSuite const &	suite,
		std::string const &	binary_path,
		io::Output &	out )

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. Progress is printed to out.

Parameters

suite	The benchmark suite to run.
binary_path	Path to the ppforest2 binary (typically argv[0]).
out	Output context for progress reporting.

Returns: Aggregated suite results.

◆ run_summarize()

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

Run the summarize subcommand.

Returns: Exit code (0 on success).

◆ run_train()

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

Run the train subcommand.

Returns: Exit code (0 on success).

◆ setup_benchmark()

void ppforest2::cli::setup_benchmark	(	CLI::App &	app,
		Params &	params )

Register benchmark subcommand options on app.

◆ setup_evaluate()

void ppforest2::cli::setup_evaluate	(	CLI::App &	app,
		Params &	params )

Register evaluate subcommand options on app.

◆ setup_predict()

void ppforest2::cli::setup_predict	(	CLI::App &	app,
		Params &	params )

Register predict subcommand options on app.

◆ setup_serve()

void ppforest2::cli::setup_serve	(	CLI::App &	app,
		Params &	params )

Register serve subcommand options on app.

◆ setup_summarize()

void ppforest2::cli::setup_summarize	(	CLI::App &	app,
		Params &	params )

Register summarize subcommand options on app.

◆ setup_train()

void ppforest2::cli::setup_train	(	CLI::App &	app,
		Params &	params )

Register train subcommand options on app.

◆ strategy_string_to_json()

nlohmann::json ppforest2::cli::strategy_string_to_json ( std::string const & input )

Parse a CLI strategy string into a JSON object.

Converts e.g. "pda:lambda=0.3" to {"name": "pda", "lambda": 0.3}.

◆ train_model()

TrainResult ppforest2::cli::train_model	(	ppforest2::types::FeatureMatrix const &	x,
		ppforest2::types::OutcomeVector const &	y,
		Params const &	params )

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

Takes x / y by const ref and copies internally — regression training (ByCutpoint) permutes rows in place via std::stable_sort, which would leak across calls if we passed the caller's matrix straight through. Centralising the copy here keeps the mutation contract internal and lets callers (warmup loops, multi-iteration evaluate, etc.) reuse the same input across calls without per-call boilerplate.

◆ training_defaults()

nlohmann::json ppforest2::cli::training_defaults ( )

Default values for shared training parameters.

Used by train and evaluate to fill in unset fields before validation. Benchmark does not apply these — its scenarios must be explicit.

◆ validate_params()

void ppforest2::cli::validate_params ( Params const & params )

Validate training-related params and throw on errors.

Builds a config from params, validates it, and throws UserError with all collected messages if any checks fail.

◆ validate_training_config()

void ppforest2::cli::validate_training_config	(	nlohmann::json const &	config,
		std::vector< std::string > &	errors )

Validate a training config JSON.

Checks all required fields, ranges, and mutual exclusions. Appends error messages to errors (empty if valid).

Parameters

config	The config to validate.
errors	Output vector to accumulate error messages.

◆ warn_unused_params()

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

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

Namespaces

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ Subcommand

Function Documentation

◆ add_evaluate_options()

◆ add_model_options()

◆ check()

◆ parse_args()

◆ parse_proportion() [1/2]

◆ parse_proportion() [2/2]

◆ parse_suite() [1/2]

◆ parse_suite() [2/2]

◆ run_benchmark()

◆ run_evaluate()

◆ run_predict()

◆ run_scenario()

◆ run_serve()

◆ run_suite()

◆ run_summarize()

◆ run_train()

◆ setup_benchmark()

◆ setup_evaluate()

◆ setup_predict()

◆ setup_serve()

◆ setup_summarize()

◆ setup_train()

◆ strategy_string_to_json()

◆ train_model()

◆ training_defaults()

◆ validate_params()

◆ validate_training_config()

◆ warn_unused_params()